Radio

페이지에 계속 보이는 배타적 선택입니다. RadioGroup.Root가 값, 공유 name, disabled, invalid를 소유합니다. RadioGroup.Item은 checked나 name을 받을 수 없습니다. 루트 밖의 항목은 오류를 던집니다.

그룹 타입은 aria-label이나 aria-labelledby를 요구합니다. role="radiogroup" div는 레이블을 붙일 수 있는 컨트롤이 아니므로, Label htmlFor로 그룹을 가리키지 마세요. Text와 aria-labelledby로 캡션을 붙이세요.

value={null}은 아무것도 선택되지 않은 제어 상태입니다. 비제어로 쓰려면 value를 생략하세요.

const captionId = useId()

<Text as="span" id={captionId} size="s" weight="medium">Plan</Text>
<RadioGroup.Root aria-labelledby={captionId} value={plan} onValueChange={setPlan}>
	<RadioGroup.Item value="free">Free</RadioGroup.Item>
	<RadioGroup.Item value="pro">Pro</RadioGroup.Item>
</RadioGroup.Root>

Plan

FreeProEnterprise

Pro adds seats and audit logs.

이름이 같은 네이티브 라디오는 화살표 키로 포커스를 옮깁니다. 그룹은 키보드 핸들러를 더하지 않습니다.

옵션이 계속 보여야 하면 Radio를 쓰세요. 옵션이 팝오버나 시트 안에 있으면 OptionList를 쓰세요. 둘을 같은 값에 연결하면 QA 실패입니다.

언제 쓰나요

언제: 페이지에 계속 보이는 배타적 선택. 그룹이 value/name을 소유하고, 캡션은 aria-label / aria-labelledby로 붙입니다.

쓰지 않을 때: 독립적인 토글 → Checkbox. 오버레이 목록 → OptionList. 같은 값을 OptionList에도 연결(이중 연결 = 실패).

Props

RadioGroup.Root props
이름	타입	필수	기본값	설명
aria-label	`string`	아니요	—	보이는 캡션이 없을 때의 접근 가능한 이름. aria-label과 aria-labelledby 중 정확히 하나만 지정합니다.
aria-labelledby	`string`	아니요	—	보이는 캡션의 id. aria-label과 aria-labelledby 중 정확히 하나만 지정합니다.
value	`string \| null`	아니요	—	제어 값. null은 아무것도 선택되지 않은 제어 상태입니다. 비제어로 쓰려면 생략합니다.
defaultValue	`string \| null`	아니요	—	비제어일 때의 초기 값.
onValueChange	`(value: string) => void`	아니요	—	다음 선택 값과 함께 호출됩니다.
name	`string`	아니요	—	공유되는 네이티브 name. 생략하면 생성됩니다.
disabled	`boolean`	아니요	—	모든 라디오를 비활성화합니다.
invalid	`boolean`	아니요	—	모든 라디오를 유효하지 않음으로 표시합니다.
orientation	`"vertical" \| "horizontal"`	아니요	"vertical"	레이아웃과 aria-orientation.
children	`React.ReactNode`	아니요	—	RadioGroup.Item 자식.
className	`string`	아니요	—	radiogroup에 붙는 선택적 클래스.

RadioGroup.Item props
이름	타입	필수	기본값	설명
value	`string`	예	—	옵션 값. 선택 상태는 그룹이 관리합니다.
children	`React.ReactNode`	예	—	보이는 레이블.
disabled	`boolean`	아니요	—	이 옵션을 비활성화합니다. 그룹의 disabled 플래그도 적용됩니다.
className	`string`	아니요	—	감싸는 label에 붙는 선택적 클래스.