Checkbox
체크 가능한 옵션을 선택하는 폼 컴포넌트
개요
Checkbox 컴포넌트는 Base UI의 Checkbox를 기반으로 구축된 체크박스 컴포넌트입니다.
주요 특징
- ✅ Base UI 기반: 접근성이 검증된 Headless UI
- ✅ 다양한 크기: xs, sm, md, lg, xl 5단계 크기 지원
- ✅ Indeterminate 상태: 부분 선택 상태 지원
- ✅ 키보드 네비게이션: Space 키로 토글
- ✅ 접근성: ARIA 속성 자동 적용
- ✅ 디자인 토큰: 테마 커스터마이징 지원
Sizes
Checkbox는 5가지 크기를 지원합니다.
Preview
Extra Small
Small
Medium
Large
Extra Large
Size 설명
| Size | 설명 | 사용 사례 |
|---|---|---|
| xs | 가장 작은 크기 | 밀집된 목록, 테이블 내부 |
| sm | 작은 크기 | 컴팩트한 폼 |
| md | 기본 크기 | 일반적인 폼 |
| lg | 큰 크기 | 강조가 필요한 옵션 |
| xl | 가장 큰 크기 | 터치 최적화, 메인 동의항목 |
사용 예시
기본 사용
라벨과 함께 사용하는 기본 형태입니다.
Preview
Checked 상태
Preview
Disabled 상태
Preview
ReadOnly 상태
읽기 전용 상태에서는 조회만 가능하며 선택 및 변경이 제한됩니다.
Preview
오류 상태
오류 발생 시 aria-invalid 속성으로 시각적 피드백을 제공합니다.
Preview
Indeterminate 상태
부분 선택 상태를 표시할 때 indeterminate prop을 사용합니다.
참고: Indeterminate는 시각적 상태만 나타내며, 체크박스 자체는 checked/unchecked 두 상태만 가집니다. Indeterminate → checked → unchecked 순환 전환은 자동으로 제공되지 않으며,
onCheckedChange콜백에서 상태를 직접 관리해야 합니다.
Preview
부분 선택됨
체크박스 그룹
여러 옵션을 그룹으로 묶어 표시합니다.
Preview
알림 설정
value 속성
value는 폼 제출 시 서버로 전달되는 값을 지정합니다. name과 함께 사용하면 체크된 항목만 name=value 형태로 전송됩니다.
참고:
value를 지정하지 않으면 기본값"on"이 전송됩니다.
Preview
관심 분야
약관 동의
필수/선택 항목을 구분하여 표시합니다.
Preview
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
size | "xs" | "sm" | "md" | "lg" | "xl" | "md" | 체크박스 크기 |
checked | boolean | - | 체크 상태 (제어 모드) |
defaultChecked | boolean | - | 초기 체크 상태 (비제어 모드) |
indeterminate | boolean | - | 부분 선택 상태 |
disabled | boolean | - | 비활성화 여부 |
readOnly | boolean | - | 읽기 전용 여부 |
value | string | - | 폼 제출 시 전달되는 값 |
name | string | - | 폼 필드 이름 |
className | string | - | 추가 CSS 클래스 |
Events
| Event | Type | Description |
|---|---|---|
onCheckedChange | (checked: boolean) => void | 체크 상태 변경 콜백 |
기본 사용법
import { Checkbox } from "@vortex/ui-foundation"
<Checkbox />
<Checkbox size="sm" />
<Checkbox defaultChecked />
<Checkbox indeterminate checked />
<Checkbox disabled />접근성
ARIA 속성
Base UI Checkbox가 자동으로 제공합니다:
// role="checkbox" 자동 적용
// aria-checked="true" | "false" | "mixed" 자동 적용
// aria-disabled 자동 적용
<Checkbox aria-label="이용약관 동의" />키보드 네비게이션
- Tab: 체크박스로 포커스 이동
- Space: 체크/해제 토글
권장 사항
- ✅
<label htmlFor>또는aria-label로 반드시 라벨 연결 - ✅ 체크박스 그룹에
<fieldset>+<legend>사용 - ✅ 에러 상태 시
aria-invalid속성 추가 - ❌ 라벨 없이 단독 사용 지양
관련 컴포넌트
Last updated on