RadioGroup
먼저 보고, 그다음 계약을 읽습니다
Radix 기반 단일 선택 라디오 그룹 (roving tabindex).
Component intent의도와 경계 읽기
@radix-ui/react-radio-group 의 Root/Item 을 감싼 래퍼로, dot+ring CSS 만 담당하고 방향키 이동·roving tabindex·폼 연동은 Radix 가 처리한다. RadioGroup 이 선택 상태(value)를 들고, 각 RadioGroupItem 이 하나의 선택지(value 필수)다. 그룹은 기본 세로 배치(axe-radio__group, flex column)이며 항목마다 <Label htmlFor> 를 붙여 클릭 영역을 넓힌다.
예제
SSOT에 등록된 실제 API 기준 snippet입니다. standalone 배지만 독립 실행 단위이며, fragment는 주변 state·handler 문맥을 생략합니다.
import { RadioGroup, RadioGroupItem, Label } from "@axe/ui";const [plan, setPlan] = useState("pro");<RadioGroup value={plan} onValueChange={setPlan}> <div style={{ display: "flex", gap: 8, alignItems: "center" }}> <RadioGroupItem id="p-free" value="free" /> <Label htmlFor="p-free">Free</Label> </div> <div style={{ display: "flex", gap: 8, alignItems: "center" }}> <RadioGroupItem id="p-pro" value="pro" /> <Label htmlFor="p-pro">Pro</Label> </div></RadioGroup>Props
TSX 소스가 진실입니다. 주요 export 컴포넌트의 public API만 노출합니다.
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
value | string | — | — | (RadioGroup) controlled 선택값. |
defaultValue | string | — | — | (RadioGroup) uncontrolled 초기 선택값. |
onValueChange | (value: string) => void | — | — | (RadioGroup) 선택 변경 콜백. |
disabled | boolean | — | — | (RadioGroup) 그룹 전체 비활성. |
required | boolean | — | — | (RadioGroup) 폼 제출 시 선택 필수. |
name | string | — | — | (RadioGroup) 폼 필드명 — 지정 시 제출용 hidden input 생성. |
orientation | "horizontal" | "vertical" | undefined | — | — | (RadioGroup) 방향키 매핑 힌트 (기본 미지정). |
...rest | React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root> | — | — | (RadioGroup) loop·dir·asChild 등 나머지 Radix Root props 전파 (className 은 axe-radio__group 과 병합). |
value (RadioGroupItem) | string | 필수 | — | (RadioGroupItem) 이 선택지의 값 (필수). |
disabled (RadioGroupItem) | boolean | — | — | (RadioGroupItem) 이 항목만 비활성. |
...rest (RadioGroupItem) | React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item> | — | — | (RadioGroupItem) id 등 나머지 Radix Item props 전파 (Label htmlFor 매칭용 id, className 은 axe-radio__item 과 병합). |
.axe-* 클래스 계약
React 밖에서도 같은 표면을 그리는 공개 계약입니다. stable은 minor 버전 안에서 이름을 바꾸지 않습니다.
| 클래스 | 안정성 | 용도 |
|---|---|---|
.axe-radio__group | stable | 그룹 컨테이너 (flex column, gap). |
.axe-radio__item | stable | 라디오 버튼 (18px 원형). data-state=checked 시 accent 테두리. |
.axe-radio__indicator | internal | 선택 dot 컨테이너 — ::after 로 8px accent 점을 그림 (Radix Indicator, checked 일 때만 마운트). |
접근성
키보드, ARIA, 구현 노트를 함께 검토합니다.
- ↑/↓ (또는 ←/→) 로 항목 이동하며 즉시 선택
- Tab 으로 그룹 진입/탈출 — 선택된 항목만 tab-stop (roving tabindex)
Radix 가 그룹 role="radiogroup", 항목 role="radio" + aria-checked 를 부여. disabled → aria-disabled + data-disabled.
각 항목에 <Label htmlFor={item id}> 를 연결해 클릭 영역을 넓힘. name 지정 시 Radix 가 폼 제출용 hidden input 렌더. 포커스 링 = :focus-visible box-shadow var(--ring).