Components
Checkbox
Checkbox는 여러 항목 중 복수 선택을 가능하게 하는 입력 컴포넌트입니다.
Import
import { Checkbox } from '@vapor-ui/core';Preview
import { Checkbox } from '@vapor-ui/core';
export default function DefaultCheckbox() {
return (
<Checkbox.Root>
<Checkbox.Control />
<Checkbox.Label>동의</Checkbox.Label>
</Checkbox.Root>
);
}Props
Checkbox.Root
| 이름 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| checked | booleanundefined | - | 제어형 체크 상태입니다. true이면 체크박스가 선택된 상태를 강제로 유지합니다. |
| defaultChecked | booleanundefined | false | 언컨트롤드 초기 체크 상태를 지정합니다. |
| onCheckedChange | (checked: boolean) => void | - | 체크 상태가 변경될 때 호출되는 콜백 함수입니다. |
| indeterminate | booleanundefined | false | 혼합(indeterminate) 상태를 표시합니다. 일부 선택된 경우를 나타낼 때 사용합니다. |
| size | mdlg | md | 체크박스의 크기를 설정합니다. |
| disabled | booleanundefined | false | 체크박스를 비활성화합니다. |
| invalid | booleanundefined | false | 폼 유효성 검증 실패 등의 상태를 나타냅니다. |
| visuallyHidden | booleanundefined | false | 레이블을 시각적으로 숨기지만 스크린리더에는 읽히도록 합니다. |
Checkbox.Control
| 이름 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| forceMount | trueundefined | - | 언마운트되지 않고 표시 상태만 토글되도록 강제합니다. |
| id | stringundefined | - | 체크박스 컨트롤의 id를 지정합니다. 값을 지정하지 않으면 React의 useId() 훅을 통해 Checkbox.Root 단계에서 고유 id가 1회 생성되며, 해당 id는 동일 컨텍스트에 포함된 Checkbox.Control·Checkbox.Label 간에 자동으로 공유되어 접근성이 보장됩니다. |
Checkbox.Label
| 이름 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| htmlFor | stringundefined | - | 레이블이 연결될 Checkbox.Control 요소의 id를 지정합니다. 이 값을 생략하면 같은 Checkbox.Root 안에서 발견된 Checkbox.Control 의 id가 자동으로 대입되어 시멘틱 연관성이 유지되고 키보드·스크린리더 접근성이 확보됩니다. |
| children | React.ReactNode | - | 레이블에 표시할 텍스트나 노드입니다. |
Accessibility Table
Checkbox WAI-ARIA 표준에 기반한 웹 접근성(A11y)을 준수합니다. Vapor Checkbox는 Radix 기능을 기반으로 구축되어 일부 웹 접근성은 Radix에서 제공하고 있습니다.
개발 시 준수해야 할 내용을 명시합니다.
| Props | Description |
|---|---|
| label | 각 체크박스는 시각적으로도 명확한 레이블(Label)과 연관되어야 합니다. Label 컴포넌트를 사용하거나 `htmlFor` 속성을 통해 컨트롤과 연결해야 합니다. |
<Checkbox.Root> <Checkbox.Control id="terms" /> <Checkbox.Label htmlFor="terms">이용약관에 동의</Checkbox.Label> </Checkbox.Root> | |
| indeterminate | indeterminate 상태는 혼합(mixed) 상태를 의미하며, 보조 기술에 올바르게 전달됩니다. 부분 선택을 나타낼 때 이 상태를 사용하세요. |
<Checkbox.Root indeterminate> <Checkbox.Control /> <Checkbox.Label>부분 선택</Checkbox.Label> </Checkbox.Root> | |
Keyboard Interactions
| Interaction | Description |
|---|---|
| Space | 체크박스에 포커스가 있을 때 space 키를 누르면 체크/해제됩니다. |