Checkbox
먼저 보고, 그다음 계약을 읽습니다
Radix 기반 tri-state 체크박스 (checked / unchecked / indeterminate).
Component intent의도와 경계 읽기
@radix-ui/react-checkbox 의 Root 를 감싼 얇은 래퍼로, box 와 check/dash 아이콘 CSS 만 담당하고 상태·키보드·포커스는 Radix 가 처리한다. checked 는 boolean 또는 "indeterminate" 를 받아 부분선택(전체선택 헤더 등)을 표현한다. Indicator 는 forceMount 로 항상 렌더되고 표시할 아이콘은 data-state 에 따라 CSS 로 분기된다. 커스텀 prop 은 없고 Radix Checkbox.Root 의 props 를 그대로 노출한다.
예제
SSOT에 등록된 실제 API 기준 snippet입니다. standalone 배지만 독립 실행 단위이며, fragment는 주변 state·handler 문맥을 생략합니다.
import { Checkbox, Label } from "@axe/ui";const [agreed, setAgreed] = useState(false);<div style={{ display: "flex", gap: 8, alignItems: "center" }}> <Checkbox id="terms" checked={agreed} onCheckedChange={(v) => setAgreed(v === true)} /> <Label htmlFor="terms">약관에 동의합니다</Label></div>import { Checkbox } from "@axe/ui";// all ? true : some ? "indeterminate" : false<Checkbox checked={selectAllState} onCheckedChange={toggleAll} aria-label="전체 선택"/>Props
TSX 소스가 진실입니다. 주요 export 컴포넌트의 public API만 노출합니다.
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
checked | boolean | "indeterminate" | — | — | controlled 상태. "indeterminate" = 부분선택 (aria-checked="mixed"). |
defaultChecked | boolean | "indeterminate" | — | — | uncontrolled 초기값. |
onCheckedChange | (checked: boolean | "indeterminate") => void | — | — | 상태 변경 콜백. |
disabled | boolean | — | — | 비활성 — data-disabled → opacity 0.5, 클릭 불가. |
required | boolean | — | — | 폼 제출 시 필수. |
name | string | — | — | 폼 필드명 — 지정 시 Radix 가 제출용 hidden input 을 렌더. |
value | string | — | "on" | 체크 시 폼에 전송되는 값. |
...rest | React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root> | — | — | asChild 등 나머지 Radix Checkbox.Root props 전파 (className 은 axe-checkbox 와 병합). |
.axe-* 클래스 계약
React 밖에서도 같은 표면을 그리는 공개 계약입니다. stable은 minor 버전 안에서 이름을 바꾸지 않습니다.
| 클래스 | 안정성 | 용도 |
|---|---|---|
.axe-checkbox | stable | 체크박스 루트 (18px box). data-state=checked/indeterminate 시 accent 배경. |
.axe-checkbox__indicator | internal | 아이콘 컨테이너 (Radix Indicator, forceMount). |
.axe-checkbox__icon | internal | check/dash SVG 공통 (기본 display:none). |
.axe-checkbox__icon--check | internal | 체크 아이콘 — data-state=checked 에서만 표시. |
.axe-checkbox__icon--dash | internal | 대시(부분선택) 아이콘 — data-state=indeterminate 에서만 표시. |
접근성
키보드, ARIA, 구현 노트를 함께 검토합니다.
- Space 로 토글
- Tab 으로 포커스
Radix 가 role="checkbox" + aria-checked(true/false/"mixed") 를 부여. indeterminate → aria-checked="mixed". disabled → aria-disabled + data-disabled.
box 자체엔 텍스트가 없으므로 <Label htmlFor> 또는 aria-label 로 이름을 제공. name 지정 시 Radix 가 폼 제출용 hidden input 을 렌더. 포커스 링 = :focus-visible box-shadow var(--ring).