Checkbox

여러 개를 고르는 선택 컨트롤이다.

import { Checkbox, CheckboxGroup } from "@nui-kit/react";
// 서브패스로 좁힐 때
import { Checkbox } from "@nui-kit/react/checkbox";
import "@nui-kit/react/styles/checkbox.css";   // 온디맨드일 때

기본

이메일 수신 동의

Field.Label 을 label 로 쓰면 클릭으로도 토글된다

전체 선택 — 중간 상태

하위 항목이 일부만 선택됐을 때 쓴다. indeterminate 를 주면 대시(−)로 그리고, 스크린리더에는 aria-checked="mixed" 로 읽힌다. CheckboxGroup 이 대신 계산해 주지는 않는다 — 값은 소비자가 소유한다.

전체 선택

이메일

SMS

앱 푸시

<Checkbox
  checked={checked.length === OPTIONS.length}
  indeterminate={checked.length > 0 && checked.length < OPTIONS.length}
  onChange={toggleAll}
/>

일부만 고르면 대시, 전부 고르면 체크

그룹

CheckboxGroup 은 role="group" 을 붙이고 name · disabled · readOnly · isError 를 하위에 전파한다.

수신 방법

이메일

SMS

앱 푸시

direction="column" (기본)

이메일

SMS

앱 푸시

direction="row"

상태

<Checkbox checked={v} onChange={onChange} isError={hasError} />

checked 가 다른 상태와 겹치면 함께 그린다

선택된 채로 에러면 빨강, 비활성이면 회색이다.

readOnly

네이티브 checkbox 에는 readonly 가 없다. 그래서 컴포넌트가 클릭과 Space·Enter 키를 직접 막고 aria-readonly 를 붙인다. disabled 와 달리 포커스는 유지되므로 스크린리더가 값을 읽을 수 있다.

값 소유

React 는 checked 를 주면서 onChange 가 없으면 콘솔 경고를 낸다. disabled 로는 막히지 않는다 — 표시 전용으로 쓸 때는 readOnly 를 함께 준다.

// ⚠️ 콘솔 경고
<Checkbox checked disabled />

// ✅
<Checkbox checked disabled readOnly />
<Checkbox checked onChange={handleChange} />

react-hook-form

RHFCheckbox 는 /rhf 서브패스에 있다. 체크박스 하나가 boolean 필드 하나다. checked · onChange · name 은 RHF 가 소유하고, 에러는 isError 로 컨트롤에 표시된다. 여러 개를 배열 값 하나로 묶는 형태는 없다. 항목마다 필드를 둔다.

이용약관에 동의합니다 (필수)

마케팅 정보 수신 (선택)

{
  "values": {
    "agree": false,
    "marketing": false
  },
  "isValid": false
}

<RHFCheckbox control={control} name="agree" rules={{ validate: (v) => v || "…" }} />

validate 로 필수 동의를 검사한다

에러 문구는 컨트롤이 그리지 않는다. 체크박스는 메시지 영역이 없어 isError 로 빨간 테두리만 표시한다. 문구는 formState.errors 를 읽어 Field.Message 등으로 직접 보여 준다.

커스터마이징

컴포넌트	변수	기본값	비고
Checkbox · Radio · Switch	--nui-selector--border-width	`var(--nui-border-width-1)`	—
Checkbox · Radio · Switch	--nui-selector--size	`var(--nui-size-selector)`	— · 2자리를 함께 움직인다

API

Checkbox

이름	타입	기본값	설명
`className`	string \| undefined	—	—
`id`	string \| undefined	—	—
`indeterminate`	boolean	`false`	중간 상태. 하위 항목이 일부만 선택된 "전체 선택" 체크박스에 쓴다 (KRDS 가이드 539·545쪽 · 체크리스트 [체크박스 5]). `CheckboxGroup` 이 자동으로 계산하지 않는다 — 그룹은 배치와 문맥만 갖고 값은 소비자가 소유하기 때문이다. 전체 선택 체크박스는 그룹 밖에 두는 일도 많다.
`isError`	boolean	—	—
`readOnly`	boolean	—	—

CheckboxProps 에서 자동 생성됨 (components/Checkbox/Checkbox.tsx). 표준 DOM 속성 304개는 그대로 전달되며 표에서 생략했다.

CheckboxGroup

이름	타입	기본값	설명
`children` *	ReactNode	—	—
`direction`	"row" \| "column"	`"column"`	—
`disabled`	boolean	—	—
`isError`	boolean	—	—
`name`	string	—	하위 항목들이 공유할 input name
`readOnly`	boolean	—	—

CheckboxGroupProps 에서 자동 생성됨 (components/Checkbox/CheckboxGroup.tsx). 표준 DOM 속성 276개는 그대로 전달되며 표에서 생략했다.