RadioGroup
라디오 버튼 그룹을 렌더링하는 폼 컨트롤 컴포넌트
개요
Cals RadioGroup은 Foundation RadioGroup을 래핑하여 CALS 제품의 groupCode 기반 라디오 UI를 선언적으로 구현하는 컴포넌트입니다.
주요 특징
- ✅ items 선언형 API: 배열 데이터만 넘기면 라디오 옵션 자동 렌더링
- ✅ children 패턴 지원: RadioGroupItem을 직접 배치하여 커스텀 레이아웃 가능
- ✅ 동적 색상 파생: backgroundColor/borderColor 지정 시 상태별 색상 자동 계산
- ✅ 조건부 토큰 오버라이드: prop이 있을 때만 토큰 오버라이드 (기본값 보존)
- ✅ FormItem 내장: label/required/description/error prop으로 폼 레이블 자동 래핑
- ✅ 가시성 제어: visible prop으로 선언적 표시/숨김
- ✅ 포커스 제어: ref.focus()/blur()/element로 프로그래밍 제어
- ✅ 디자인 토큰: Foundation 토큰 시스템 완벽 호환
기본 사용
items prop으로 라디오 옵션 배열을 전달합니다. 각 항목은 value와 label을 가집니다.
Preview
children 사용
items 대신 children으로 RadioGroupItem을 직접 배치하여 커스텀 레이아웃을 구성할 수 있습니다.
Preview
크기
size prop으로 라디오 버튼 크기를 지정합니다. xs / sm / md / lg / xl을 지원합니다.
Preview
비활성 상태
disabled prop으로 전체 그룹을 비활성화하거나, 개별 항목의 disabled로 부분 비활성화합니다.
Preview
읽기 전용
readOnly prop은 disabled와 동일하게 동작합니다 (원본 CALS 호환).
Preview
FormItem 래핑
label, required, description, error prop을 지정하면 FormItem으로 자동 래핑됩니다.
Preview
필수 선택 항목입니다
커스텀 색상
backgroundColor, borderColor, color prop으로 토큰을 오버라이드합니다.
Preview
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | RadioGroupOption[] | - | 라디오 옵션 배열 ({ value, label, disabled? }) |
value | string | - | 선택된 값 (제어 모드) |
defaultValue | string | - | 초기 선택 값 (비제어 모드) |
size | "xs" | "sm" | "md" | "lg" | "xl" | "md" | 라디오 버튼 크기 |
visible | boolean | true | 표시 여부 |
disabled | boolean | - | 전체 비활성화 |
readOnly | boolean | - | 읽기 전용 (disabled와 동일 동작) |
showLabel | boolean | false | 빈 레이블 공간 표시 |
backgroundColor | string | - | 라디오 배경색 (상태별 자동 파생) |
color | string | - | 텍스트 색상 |
borderColor | string | - | 테두리 색상 (상태별 자동 파생) |
fontSize | string | - | 폰트 크기 |
fontWeight | string | number | - | 폰트 굵기 |
fontFamily | string | - | 폰트 패밀리 |
fontStyle | string | - | 폰트 스타일 |
label | string | - | FormItem 레이블 |
required | boolean | - | 필수 표시 |
description | string | - | 설명 텍스트 |
error | string | - | 에러 메시지 |
className | string | - | 컴포넌트 컨테이너에 적용할 CSS 클래스 |
formClassName | string | - | FormItem 래퍼에 적용할 CSS 클래스 |
style | CSSProperties | - | 인라인 스타일 |
children | ReactNode | - | items 대신 직접 RadioGroupItem 배치 |
Events
| Event | Type | Description |
|---|---|---|
onChange | (value: string) => void | 선택 값 변경 시 호출 |
Ref (RadioGroupRef)
| Property | Type | Description |
|---|---|---|
focus | () => void | 라디오 그룹에 포커스 |
blur | () => void | 포커스 해제 |
element | HTMLDivElement | null | 내부 radio-group DOM 요소 |
접근성
권장 사항
- ✅ 각 라디오 항목에 의미 있는 label 텍스트를 제공합니다
- ✅ FormItem label을 사용하여 그룹 전체에 대한 설명을 제공합니다
- ✅ disabled 상태에서는 사용자 인터랙션이 완전히 차단됩니다
- ❌ 라디오 항목에 label 없이 value만 전달하지 마세요
관련 컴포넌트
- Foundation RadioGroup: 기본 RadioGroup 컴포넌트
- FormItem: 폼 래퍼
- Checkbox: 다중 선택이 필요한 경우
Last updated on