Checkbox
네이티브 input 기반 체크박스 — 커스텀 박스 시각화, indeterminate(혼합) 상태, children 라벨 자동 연동.
마지막 업데이트 2026-06-11
한눈에#
비제어가 기본입니다 — defaultChecked만으로 동작하고, 제어가 필요하면 checked + onChange를 함께 넘깁니다.
- 네이티브 input 기반
- indeterminate(혼합)
- 2 크기(md·sm)
- 라벨 자동 연동
박스는 장식 — 상태의 진실은 시각적으로 숨긴 네이티브 input입니다(키보드·SR 경로 보존)
사용 시점#
제출 전까지 보류되는 다중 선택이면 Checkbox — 즉시 적용/단일 선택은 다른 컴포넌트입니다.
약관 동의·옵션 다중 선택처럼 제출 전까지 보류되는 켜고 끄기(혼합 상태 가능)
플레이그라운드#
컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.
import { Checkbox } from '@wds/ui-web';
<Checkbox>이메일 알림 수신</Checkbox>해부#
박스·체크·라벨 위에 토큰 실측을 핀으로 얹습니다 — 박스는 장식, 진실은 숨긴 네이티브 input입니다.
- box
- 18px
- check/dash
- 14px
- gap
- 8px
space-2 - radius
- 6px
checkbox.radius - border
- 1px
checkbox.border - label
- 14px
body-2 - hit area
- +6px (::after)
변형 — indeterminate#
전체 선택 헤더처럼 "일부만 선택"인 혼합 상태입니다. HTML 속성이 없는 DOM
전용 프로퍼티라 컴포넌트가 ref로 el.indeterminate를 동기하고, 박스에는
체크 대신 대시를 그립니다.
크기#
size로 2단(ADR-012 B-P2) — md(기본) 18px 박스, sm 16px 박스. 라벨은 body-2로
공통이며, 시각 크기와 무관하게 박스의 히트 영역이 control.height-md(44px) 터치 타깃으로
역산 확장됩니다(레이아웃을 밀어내지 않는 ::after, Switch·RadioGroup과 동형). 라벨은
label 래핑으로 함께 클릭되어 히트 폭을 더 넓힙니다.
상태#
- Focus — 박스에 2px primary 아웃라인 (Tab으로 확인하세요)
- Checked / Indeterminate —
checkbox.bg-checked채움 + 체크/대시 표시 - Disabled — 커서 차단 + 60% 투명도
Props#
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
indeterminate | boolean | false | 혼합 상태 — el.indeterminate 동기 + 대시 표시. checked와 독립 |
size | 'sm' | 'md' | 'md' | 컨트롤 크기 — md 18px / sm 16px 박스 |
children | ReactNode | — | 라벨 — label 요소로 감싸 클릭·접근성 이름 자동 연동 |
…rest | Omit<InputHTMLAttributes, 'type' | 'size'> | — | defaultChecked · checked · onChange · disabled 등은 input으로 전달 (size는 WDS prop으로 대체) |
className은 루트 label에 적용됩니다.
접근성#
- 네이티브
<input type="checkbox">를 시각적으로만 숨겨 키보드(Space)· 스크린리더 경로를 그대로 유지합니다 children라벨은<label>로 감싸 클릭 영역과 접근성 이름이 자동 연동됩니다 — 라벨 없이 쓰면aria-label을 부여하세요indeterminate는 접근성 트리에 mixed 상태로 보고됩니다- 커스텀 박스·체크는 장식(
aria-hidden) — 상태의 진실은 네이티브 input
토큰#
| 토큰 | 값 | 설명 |
|---|---|---|
| — | ||
| — | ||
| — | ||
| — | ||
| — |