Checkbox Group
독립적으로 전환하는 값을 하나의 접근 가능한 그룹으로 조정해요.
핵심 속성
| 판단 기준 | 선택 방법 |
|---|---|
| 값 소유권 | 비제어 상태는 defaultValue, 제어 상태는 value와 onValueChange를 써요. |
| 사용 가능 여부 | 그룹 전체는 disabled, 폼 값을 유지할 개별 항목은 readOnly를 써요. |
| 폼 | 자식 체크박스에 같은 name을 주면 선택한 각 항목이 value를 제공해요. |
| 부모 선택 | allValues를 전달하고 자식 체크박스에 parent를 써요. |
| 유효성 검사 | 네이티브 필수 조건보다 복잡한 선택 개수 규칙은 제어 배열을 검사해요. |
그룹에는 aria-label이나 aria-labelledby로 이름을 주고, 모든 자식 체크박스에도 이름을 제공해요. 자식마다 TRField.Item 안에 TRField.Label을 함께 두면 아이템이 그 안의 체크박스에 레이블을 연결하니, 항목이 반복돼도 id나 htmlFor가 필요 없어요. TRField.Item에는 TRField.Root 조상이 반드시 필요하니, 아이템이나 그룹 전체를 하나의 TRField.Root로 감싸세요. 그룹은 독립 선택을 조정해요. 하나의 값만 골라야 한다면 TRRadioGroup을 써요.
설치
pnpm add @tinyrack/ui긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
스타일
@import '@tinyrack/ui/components/checkbox-group.css';긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
가져오기
import { TRCheckboxGroup } from '@tinyrack/ui/components/checkbox-group';
import { TRCheckbox } from '@tinyrack/ui/components/checkbox';긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
플레이그라운드
사용법
예시
전체 집합의 사용 가능 여부를 정해요
선택 개수를 검사해요
값을 한 개나 두 개 골라요 고유 링크
제품 규칙에 최소와 최대 선택 개수가 있다면 값 배열을 제어해요.
모두 선택하는 부모를 추가해요
부모와 일부 선택 상태 고유 링크
모든 값을 고르면 부모가 선택되고, 일부 값만 고르면 일부 선택 상태가 돼요.
외부 폼에 연결해요
외부 소유 폼과 초기화 고유 링크
모든 자식 체크박스에 `form`을 설정해요. 초기화하면 그룹의 비제어 `defaultValue`로 돌아가요.
API
값과 사용 가능 여부
| Prop | 타입 / 기본값 | 용도 |
|---|---|---|
value, defaultValue | string[], [] | 선택한 자식 값을 제어하거나 초기화해요. |
onValueChange | (value, details) => void | 다음 값 배열을 알려줘요. |
disabled | boolean, false | 모든 자식을 비활성화하고 폼 데이터에서 빼요. |
allValues | string[] | parent 체크박스가 쓸 전체 집합을 정의해요. |
합성과 폼
각기 다른 value와 같은 name을 가진 TRCheckbox.Root 자식을 렌더링해요. readOnly와 폼 소유권은 숨겨진 입력을 가진 자식 체크박스에 설정해요. 비제어 그룹은 초기화할 때 defaultValue로 돌아가고, 제어 그룹은 value를 따라요.
루트는 Base UI의 render, ref, 이벤트, 네이티브 속성, 상태 기반 className과 style을 유지해요. 모듈은 TRCheckboxGroup, TRCheckboxGroupProps, TRCheckboxGroupState를 내보내요. CSS는 직접 가져와야 해요.