Radio Group

한 번에 하나의 버튼만 체크할 수 있는 일련의 체크 가능한 버튼(라디오 버튼)들의 그룹이에요.

출처: 문서

본문

여러 옵션 중 하나만 선택해야 할 때 쓰는 라디오 버튼 그룹 컴포넌트예요. 키보드 내비게이션을 완전히 지원하고 가로/세로 방향을 모두 지원하며, 제어/비제어 방식 모두 사용할 수 있어요.

Features

완전한 키보드 내비게이션.
가로/세로 방향 지원.
제어(controlled)/비제어(uncontrolled) 방식 모두 지원.

Anatomy

모든 파트를 임포트해 조립해요.

import { RadioGroup } from "radix-ui";

export default () => (
  <RadioGroup.Root>
    <RadioGroup.Item>
      <RadioGroup.Indicator />
    </RadioGroup.Item>
  </RadioGroup.Root>
);

API Reference

Root

라디오 그룹의 모든 파트를 담아요.

Prop	Type	Default
`asChild`	`boolean`	`false`
`defaultValue`	`string`	No default value
`value`	`string`	No default value
`onValueChange`	`function`	No default value
`disabled`	`boolean`	No default value
`name`	`string`	No default value
`required`	`boolean`	No default value
`orientation`	`enum`	`undefined`
`dir`	`enum`	No default value
`loop`	`boolean`	`true`

Data attribute	Values
`[data-disabled]`	Present when disabled

Item

그룹에서 체크할 수 있는 아이템이에요. form 안에서 사용하면 이벤트 전파가 올바르게 되도록 input도 함께 렌더링돼요.

Prop	Type	Default
`asChild`	`boolean`	`false`
`value`	`string`	No default value
`disabled`	`boolean`	No default value
`required`	`boolean`	No default value

Data attribute	Values
`[data-state]`	`"checked" \| "unchecked"`
`[data-disabled]`	Present when disabled

Indicator

라디오 아이템이 checked 상태일 때 렌더링돼요. 이 요소를 직접 스타일하거나 아이콘을 넣는 래퍼로 쓰거나 둘 다 할 수 있어요.

Prop	Type	Default
`asChild`	`boolean`	`false`
`forceMount`	`boolean`	No default value

Data attribute	Values
`[data-state]`	`"checked" \| "unchecked"`
`[data-disabled]`	Present when disabled

Examples

숨겨진 input 분리하기

기본적으로 RadioGroup.Item은 폼 제출을 위해 시각적으로 숨겨진 input을 렌더링해요. 그 input을 재구성하거나 이동하거나 제외하려면, 더 낮은 레벨의 파트들로 각 아이템을 조립할 수 있어요.

중요: 이 파트들은 불안정하며 unstable_ 접두사가 붙어 있어서 API가 향후 릴리스에서 바뀔 수 있어요.

RadioGroup.unstable_ItemProvider는 아이템 상태를 제공하고 아이템의 value와 disabled props를 받아요.
RadioGroup.unstable_ItemTrigger는 RadioGroup.Indicator를 감싸는 상호작용 요소예요.
RadioGroup.unstable_ItemBubbleInput은 RadioGroup.Item이 기본으로 렌더링하는 시각적으로 숨겨진 input이에요. 폼 제출이 필요 없으면 생략해요.

import { RadioGroup } from "radix-ui";

export default () => (
  <RadioGroup.Root>
    {["one", "two", "three"].map((value) => (
      <RadioGroup.unstable_ItemProvider key={value} value={value}>
        <RadioGroup.unstable_ItemTrigger>
          <RadioGroup.Indicator />
        </RadioGroup.unstable_ItemTrigger>

        <RadioGroup.unstable_ItemBubbleInput />
      </RadioGroup.unstable_ItemProvider>
    ))}
  </RadioGroup.Root>
);

Accessibility

Radio Group WAI-ARIA 디자인 패턴을 준수하고, 라디오 아이템 간 포커스 이동을 roving tabindex로 관리해요.

키보드 상호작용

Key	Description
`Tab`	Moves focus to either the checked radio item or the first radio item in the group.
`Space`	When focus is on an unchecked radio item, checks it.
`ArrowDown`	Moves focus and checks the next radio item in the group.
`ArrowRight`	Moves focus and checks the next radio item in the group.
`ArrowUp`	Moves focus to the previous radio item in the group.
`ArrowLeft`	Moves focus to the previous radio item in the group.

더 알아보기 (Learn more)

RadioGroup.Root에 name/required를 지정하면 폼에서 그룹 값을 전송할 수 있어요.
선택 표시는 RadioGroup.Indicator로 하고, forceMount로 상태와 무관하게 렌더링할 수도 있어요.