Radio Group
여러 값 중 하나를 고르고 방향키 탐색과 하나의 네이티브 폼 값을 제공해요.
핵심 속성
| 판단 기준 | 선택 방법 |
|---|---|
| 레이블 | aria-label, aria-labelledby, 필드셋 범례 중에서 골라요. |
| 값 | 비제어 상태는 defaultValue, 제어 상태는 value와 onValueChange를 써요. |
| 사용 가능 여부 | readOnly는 선택한 항목의 초점을 유지하고, disabled는 상호작용과 폼 데이터를 없애요. |
| 폼 | 그룹에 name, form, required를 설정하며 초기화하면 defaultValue로 돌아가요. |
| 키보드 | 방향키는 비활성 항목을 건너뛰며 초점과 선택을 순환해요. |
그룹은 값 하나만 선택해요. 두 축 방향키 탐색을 사용하고 공개 orientation prop은 없어요. 보이는 방향은 레이아웃 클래스로 정해요.
설치
pnpm add @tinyrack/ui긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
스타일
@import '@tinyrack/ui/components/radio-group.css';긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
가져오기
import { TRRadioGroup } from '@tinyrack/ui/components/radio-group';
import { TRRadio } from '@tinyrack/ui/components/radio';긴 줄은 코드 영역 안에서 가로로 스크롤해 확인하세요.
플레이그라운드
사용법
예시
전체 선택의 사용 가능 여부를 정해요
값 하나를 필수로 받아요
외부 폼에 연결해요
외부 소유 폼과 초기화 고유 링크
`form`은 그룹의 숨겨진 라디오 입력을 다른 폼에 연결해요. 네이티브 초기화는 비제어 기본값을 복원해요.
API
값, 사용 가능 여부, 폼
| Prop | 타입 / 기본값 | 용도 |
|---|---|---|
value, defaultValue | unknown, 선택 없음 | 선택한 자식 값을 제어하거나 초기화해요. |
onValueChange | (value, details) => void | 선택을 알려주며 details.cancel()로 변경을 거부할 수 있어요. |
disabled, readOnly | boolean, false | 그룹을 비활성화하거나 선택한 값을 초점 가능한 읽기 전용으로 유지해요. |
name, form, required | 네이티브 폼 prop | 직렬화, 외부 소유권, 제약 조건 검사를 설정해요. |
inputRef | Ref<HTMLInputElement> | 그룹의 숨겨진 네이티브 입력에 접근해요. |
비제어 그룹은 소유 폼을 초기화할 때 defaultValue로 돌아가고, 제어 그룹은 value를 따라요. 비활성 그룹은 FormData에서 빠져요.
합성과 접근성
고유한 값을 가진 TRRadio.Root 자식을 렌더링하고 그룹에 접근 가능한 이름을 제공해요. 각 항목은 TRField.Item 안에 TRField.Label과 함께 두어요. 아이템이 그 안의 라디오에 레이블을 연결하니 id나 htmlFor가 필요 없어요. TRField.Item에는 TRField.Root 조상이 반드시 필요하니, 아이템이나 그룹 전체를 하나의 TRField.Root로 감싸세요. 루트는 Base UI의 render, ref, 네이티브 이벤트와 속성, 상태 기반 className과 style을 지원해요. 서버 렌더링과 하이드레이션에서도 선택 값을 유지해요.
모듈은 TRRadioGroup, TRRadioGroupProps, TRRadioGroupState를 내보내요. CSS는 직접 가져와야 해요.