Skip to Content
ComponentsIcignalRadioButton

RadioButton

레이블을 포함한 라디오 버튼 입력 컴포넌트

개요

iCignal RadioButton은 Foundation RadioGroupItem을 래핑하여 레이블 기능을 추가한 컴포넌트입니다. RadioButtonGroup을 통해 그룹으로 관리합니다.

주요 특징

  • ✅ 레이블 통합: 라디오 버튼 우측에 레이블 자동 배치
  • ✅ 다양한 크기: xs, sm, md, lg, xl 5단계 크기 지원
  • ✅ 읽기 전용: readOnly 상태에서 조회만 가능
  • ✅ 오류 상태: error prop을 통한 시각적 오류 표시
  • ✅ FormItem 통합: 그룹 레이블, 설명, 에러 메시지
  • ✅ 접근성: ARIA 속성 자동 적용
  • ✅ 디자인 토큰: 테마 커스터마이징 지원

사용 예시

기본 상태

상호 배타적인 선택지 중 하나를 선택하는 입력 요소입니다.

체크 상태 표시

선택 시 Checked 상태를 시각적으로 표시합니다.

읽기 전용 상태

읽기 전용 상태에서는 조회만 가능하며 선택 변경이 제한됩니다.

오류 상태 표시

오류 발생 시 그룹 단위로 오류 상태를 시각적으로 표현합니다.

레이블 제공

각 Radio Button의 Label은 버튼 우측에 배치됩니다. 레이블 클릭 시에도 선택이 동작합니다.

입력 가능 제어

API Reference

RadioButtonGroup Props

PropTypeDefaultDescription
itemsRadioButtonProps[][]라디오 버튼 항목 배열
valuestring-선택된 값 (제어)
defaultValuestring-기본 선택 값
itemOrientation"horizontal" | "vertical""horizontal"항목 배치 방향
size"xs" | "sm" | "md" | "lg" | "xl""md"라디오 버튼 크기
disabledboolean-비활성화 여부
readOnlyboolean-읽기 전용 여부
labelstring-필드 레이블
labelWidthstring | number-레이블 너비
requiredboolean-필수 여부
orientation"horizontal" | "vertical""horizontal"레이블-필드 배치 방향
descriptionstring-설명 텍스트
errorstring-에러 메시지
classNamestring-추가 CSS 클래스

Events

EventTypeDescription
onValueChange(value: string) => void값 변경 핸들러

RadioButton Props

PropTypeDefaultDescription
valuestring-항목 값
labelstring-항목 레이블
disabledboolean-개별 비활성화
readOnlyboolean-읽기 전용 여부

기본 사용법

import { RadioButtonGroup } from "@vortex/ui-icignal"
 
<RadioButtonGroup
  label="옵션 선택"
  labelWidth={100}
  items={[
    { value: "a", label: "옵션 A" },
    { value: "b", label: "옵션 B" },
  ]}
  defaultValue="a"
/>

접근성

ARIA 속성

Base UI Radio가 자동으로 제공합니다:

// role="radiogroup" 자동 적용
// role="radio" 자동 적용
// aria-checked="true" | "false" 자동 적용
// aria-disabled 자동 적용

권장 사항

  • ✅ label prop을 통해 그룹 레이블을 제공
  • ✅ 각 항목에 label을 제공하여 개별 라벨 연결
  • ✅ 에러 상태 시 error prop으로 구체적 안내
  • ❌ 라벨 없이 단독 사용 지양

관련 컴포넌트

Last updated on
ProgressRadioButtonGroup