RadioGroup
상호 배타적인 옵션 중 하나를 선택하는 라디오 버튼 그룹
개요
RadioGroup은 Base UI의 Radio를 기반으로 구축된 라디오 버튼 그룹 컴포넌트입니다.
주요 특징
- ✅ Base UI 기반: 접근성이 검증된 Headless UI
- ✅ 다양한 크기: xs, sm, md, lg, xl 5단계 크기 지원
- ✅ 읽기 전용: readOnly 상태에서 조회만 가능
- ✅ 오류 상태: aria-invalid를 통한 시각적 오류 표시
- ✅ 키보드 네비게이션: 방향키로 항목 간 이동
- ✅ 접근성: ARIA 속성 자동 적용
- ✅ 디자인 토큰: 테마 커스터마이징 지원
Sizes
RadioGroup은 5가지 크기를 지원합니다.
Preview
Extra Small
Small
Medium
Large
Extra Large
Size 설명
| Size | 설명 | 사용 사례 |
|---|---|---|
| xs | 가장 작은 크기 | 밀집된 목록, 테이블 내부 |
| sm | 작은 크기 | 컴팩트한 폼 |
| md | 기본 크기 | 일반적인 폼 |
| lg | 큰 크기 | 강조가 필요한 옵션 |
| xl | 가장 큰 크기 | 터치 최적화, 메인 선택항목 |
사용 예시
기본 사용
라벨과 함께 사용하는 기본 형태입니다.
Preview
Disabled 상태
Preview
ReadOnly 상태
읽기 전용 상태에서는 조회만 가능하며 선택 변경이 제한됩니다.
Preview
오류 상태
오류 발생 시 aria-invalid 속성으로 시각적 피드백을 제공합니다.
Preview
수평 배치
Preview
API Reference
RadioGroup Props
| Prop | Type | Default | Description |
|---|---|---|---|
size | "xs" | "sm" | "md" | "lg" | "xl" | "md" | 라디오 버튼 크기 |
value | string | - | 선택 값 (제어 모드) |
defaultValue | string | - | 초기 선택 값 (비제어 모드) |
disabled | boolean | - | 비활성화 여부 |
readOnly | boolean | - | 읽기 전용 여부 |
className | string | - | 추가 CSS 클래스 |
RadioGroup Events
| Event | Type | Description |
|---|---|---|
onValueChange | (value: string) => void | 값 변경 시 호출 |
RadioGroupItem Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | - | 항목 값 |
disabled | boolean | - | 개별 비활성화 |
className | string | - | 추가 CSS 클래스 |
기본 사용법
import { RadioGroup, RadioGroupItem, Label } from "@vortex/ui-foundation"
<RadioGroup defaultValue="option1">
<div className="flex items-center gap-2">
<RadioGroupItem value="option1" id="r1" />
<Label htmlFor="r1">옵션 1</Label>
</div>
</RadioGroup>접근성
ARIA 속성
Base UI Radio가 자동으로 제공합니다:
// role="radiogroup" 자동 적용
// role="radio" 자동 적용
// aria-checked="true" | "false" 자동 적용
// aria-disabled 자동 적용키보드 네비게이션
- Tab: 라디오 그룹으로 포커스 이동
- ↑ ↓ ← →: 항목 간 이동 및 선택
- Space: 포커스된 항목 선택
권장 사항
- ✅
<Label htmlFor>또는aria-label로 반드시 라벨 연결 - ✅ 에러 상태 시
aria-invalid속성 추가 - ❌ 라벨 없이 단독 사용 지양
관련 컴포넌트
Last updated on