Checkbox
이진 선택이나 일부 선택 상태를 네이티브 폼 값으로 다루는 컨트롤이에요.
핵심 속성
| 판단 기준 | 선택 방법 |
|---|---|
| 선택 상태 | 선택 안 함, 선택함, 일부 항목만 선택했을 때 indeterminate를 써요. |
| 사용 가능 여부 | 기본 상태, 초점과 폼 값을 유지하는 readOnly, 사용할 수 없는 disabled 중에서 골라요. |
| 크기 | md, lg 중에서 고르며 기본값은 md예요. |
| 폼 | name, value, uncheckedValue, form, required와 네이티브 초기화를 지원해요. |
모든 체크박스에 보이는 레이블이나 접근 가능한 이름을 제공해요. 컨트롤과 TRField.Label을 TRField.Item으로 감싸면 클릭할 수 있는 레이블이 생겨요. 아이템이 그 안의 컨트롤에 레이블을 연결하니 id나 htmlFor를 직접 이어줄 필요가 없어요. TRField.Item에는 TRField.Root 조상이 반드시 필요하니, 아이템이나 그룹 전체를 하나의 TRField.Root로 감싸세요. 독립 선택이나 여러 항목을 함께 제출하는 선택에는 체크박스를 쓰고, 여러 체크박스 값을 조정할 때는 TRCheckboxGroup을 써요.
설치
pnpm add @tinyrack/ui긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
스타일
@import '@tinyrack/ui/components/checkbox.css';긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
가져오기
import { TRCheckbox } from '@tinyrack/ui/components/checkbox';긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
플레이그라운드
사용법
예시
선택 상태를 정해요
선택 안 함, 선택함, 일부 선택 고유 링크
체크박스가 일부만 선택한 집합을 요약할 때만 일부 선택 상태를 써요.
컨트롤 밀도에 맞춰요
상호작용을 유지하거나 없애요
편집 가능, 읽기 전용, 사용 불가 고유 링크
읽기 전용 컨트롤은 초점과 폼 값을 유지하고, 비활성 컨트롤은 탭 순서와 제출에서 빠져요.
동의를 필수로 받아요
켜짐과 꺼짐 값을 모두 제출해요
외부 폼 연결 고유 링크
숨겨진 입력을 다른 폼에 연결하려면 `form`을 쓰고, 꺼진 상태도 직렬화하려면 `uncheckedValue`를 써요.
API
선택과 상호작용
| Prop | 타입 / 기본값 | 용도 |
|---|---|---|
checked, defaultChecked | boolean, false | 선택 상태를 제어하거나 초기화해요. |
indeterminate | boolean, false | 일부 선택 상태를 노출하며 사용자가 선택을 확정하면 해제해요. |
onCheckedChange | (checked, details) => void | 변경 시도를 알려줘요. |
disabled, readOnly | boolean, false | 상호작용을 없애거나 초점 가능한 읽기 전용 값을 유지해요. |
uiSize | 'md' | 'lg', 'md' | 보이는 컨트롤 크기를 정해요. |
폼과 합성
name, value, uncheckedValue, form, required, inputRef는 숨겨진 네이티브 체크박스로 전달해요. 비제어 루트는 소유 폼을 초기화할 때 defaultChecked로 돌아가고, 제어 루트는 checked를 따라요. Base UI의 render, 루트 ref, 이벤트 prop, 상태 기반 className과 style을 그대로 쓸 수 있어요.
TRCheckbox.Indicator는 선택하거나 일부 선택한 상태에서 렌더링해요. render 콜백은 state.indeterminate를 받고, keepMounted는 전환 효과를 위해 DOM을 유지해요. Root와 Indicator는 관련 상태를 data 속성으로 노출해요.
모듈은 TRCheckbox, 이름 있는 파트 두 개, 각 prop 및 상태 타입, TRCheckboxUiSize를 내보내요. CSS는 직접 가져와야 해요.