RadioGroup

하나의 값을 고르는 visible option set을 native fieldset과 same-name radio로 제공합니다.

예제

사용해야 할 때

배송 방법이나 연락 수단처럼 사용자가 작은 visible set에서 정확히 하나를 선택해야 할 때 사용합니다. 선택지를 한 화면에서 비교할 수 있고 각 항목을 짧게 설명할 수 있을 때 적합합니다.

사용하지 말아야 할 때

여러 값을 독립적으로 선택하려면 Checkbox를 사용합니다. 선택지가 매우 많거나 공간이 제한적이면 Select를 사용하고, 즉시 켜고 끄는 binary setting에는 Switch를 사용합니다.

구조

native fieldset 안에 visible legend, optional group description, same-name radio option list, optional group error가 순서대로 옵니다. 각 option label row는 native radio와 label, optional option description을 함께 감쌉니다.

크기와 변형

small indicator는 20px, medium은 24px이며 기본값은 medium입니다. 모든 option row는 최소 44px입니다. public metadata의 none, first, second는 문서와 Figma가 보여 주는 selection 예시이며 option 수는 runtime data입니다.

상태와 동작

상태 우선순위는 Disabled > Error > Focus > Default입니다. controlled value와 uncontrolled defaultValue를 모두 지원하지만 내부 mirror state는 만들지 않습니다. 같은 name을 공유하므로 browser가 단일 선택, 방향키 이동, form value를 소유합니다.

반응형 동작

fieldset은 content width를 사용하되 available width를 넘지 않습니다. 긴 legend, option label, description과 error는 줄바꿈되며 모바일에서도 같은 native radios와 44px rows를 유지합니다.

접근성

visible legend가 group name을 제공합니다. option label click, Tab 진입, 방향키 선택, native required와 disabled semantics를 보존합니다. required는 첫 enabled option 하나에만 적용합니다. group description/error는 fieldset과 각 radio에 연결되고 option description이 먼저 결합됩니다.

React 예제

import { RadioGroup } from '@hds/react';
import '@hds/react/styles.css';

const options = [
  { value: 'standard', label: '일반 배송' },
  { value: 'express', label: '빠른 배송' },
];

export function DeliveryMethod() {
  return (
    <RadioGroup
      defaultValue="standard"
      legend="배송 방법"
      name="delivery"
      options={options}
      required
    />
  );
}

API

사용 토큰

• size/control/small, size/selection/small, size/selection/medium
• space/2, space/4, space/8, radius/full
• font/*, color/bg/*, color/text/*, color/border/*, color/action/*, color/status/*, color/focus/ring

Figma

라이브 RadioGroup component set은 Size 2 × Selection 3 × State 3 = 18 variants와 Legend, Option 1, Option 2, Option 3, Description, Error TEXT properties를 제공합니다. 44px option rows, indicator 크기·0 padding·radius, gaps, semantic colors와 text styles는 local Variables와 Styles에 연결되어 있습니다.

지원 상태