Checkbox

체크박스 컨트롤. 클릭으로 선택/해제할 수 있으며, 3단계 순환 모드를 지원한다.

개요

CALS Checkbox는 Foundation Checkbox를 래핑하여 CALS 전용 기능(토큰 오버라이드, FormItem 래핑, 3단계 순환 등)을 제공한다.

주요 특징

• ✅ 기본 선택/해제: 클릭으로 체크 토글
• ✅ 3단계 순환: threeState 모드에서 unchecked→checked→indeterminate 순환
• ✅ 읽기 전용: 상태 표시만 하고 조작 차단
• ✅ 디자인 토큰: Foundation 토큰 시스템 완벽 호환
• ✅ FormItem 래핑: label/required/error 자동 래핑

기본 사용

children으로 라벨 텍스트를 전달한다.

<Checkbox>동의합니다</Checkbox>
<Checkbox defaultChecked={true}>기본 선택됨</Checkbox>

크기

size prop으로 체크박스 크기를 변경한다.

<Checkbox size="xs">XS</Checkbox>
<Checkbox size="sm">SM</Checkbox>
<Checkbox size="md">MD</Checkbox>
<Checkbox size="lg">LG</Checkbox>
<Checkbox size="xl">XL</Checkbox>

비활성 상태

disabled prop으로 클릭을 차단한다.

<Checkbox disabled>미선택 비활성</Checkbox>
<Checkbox disabled defaultChecked={true}>선택됨 비활성</Checkbox>

읽기 전용

readOnly prop은 클릭을 차단하지만 기존 상태를 유지한다.

<Checkbox readOnly>미선택</Checkbox>
<Checkbox readOnly defaultChecked={true}>선택됨</Checkbox>

3단계 체크박스

threeState prop으로 unchecked→checked→indeterminate 순환을 활성화한다.

const [value, setValue] = useState<CheckedValue>(false)
 
<Checkbox threeState checked={value} onCheckedChange={setValue}>
  3단계 순환
</Checkbox>

FormItem 래핑

label, required, description, error prop을 제공하면 FormItem으로 자동 래핑된다.

<Checkbox label="동의 항목" required>이용약관에 동의합니다</Checkbox>
<Checkbox label="에러 표시" error="필수 선택 항목입니다">동의</Checkbox>

커스텀 색상

backgroundColor, color, borderColor prop으로 토큰을 오버라이드한다.

<Checkbox backgroundColor="#7c3aed" defaultChecked={true}>배경색</Checkbox>
<Checkbox borderColor="#e8553d" defaultChecked={true}>테두리색</Checkbox>
<Checkbox color="#16a34a">라벨 텍스트색</Checkbox>

API Reference

Props

Events

Ref (CheckboxRef)

접근성

권장 사항

• ✅ 의미 있는 라벨 텍스트를 children으로 제공
• ✅ 라벨 없는 체크박스에는 aria-label 사용
• ✅ 그룹화된 체크박스는 fieldset/legend으로 감싸기
• ❌ 라벨 없이 체크박스만 사용하지 않기

관련 컴포넌트

• Foundation Checkbox: 기본 체크박스 컴포넌트
• RadioGroup: 단일 선택 라디오 그룹
• FormItem: 폼 래퍼