Components

Radio

Docs

Radio API 사용가이드입니다. 조합 예시는 Overview를 참고하세요.

API

RadioGroup · Radio · RadioItem을 조합합니다. size는 medium(기본) · large. 레이블은 RadioItem children 또는 @/components/label의 Label(htmlFor)과 조합합니다.

import { RadioGroup, Radio, RadioItem } from "@/components/radio";
import { Label } from "@/components/label";

{/* RadioItem — 레이블 포함 · size 기본 medium */}
<RadioGroup
  name="plan"
  defaultValue="free"
  className="flex flex-col gap-[var(--padding-12)]"
>
  <RadioItem value="free">Free</RadioItem>
  <RadioItem value="pro">Pro</RadioItem>
</RadioGroup>

{/* large */}
<RadioGroup
  name="plan-lg"
  size="large"
  defaultValue="free"
  className="flex flex-col gap-[var(--padding-12)]"
>
  <RadioItem value="free">Free</RadioItem>
  <RadioItem value="pro">Pro</RadioItem>
</RadioGroup>

{/* Radio + Label — htmlFor로 연결 */}
<RadioGroup
  name="theme"
  defaultValue="light"
  className="flex flex-col gap-[var(--padding-12)]"
>
  <div className="flex items-center gap-[var(--gap-8)]">
    <Radio id="theme-light" value="light" />
    <Label htmlFor="theme-light">Light</Label>
  </div>
  <div className="flex items-center gap-[var(--gap-8)]">
    <Radio id="theme-dark" value="dark" />
    <Label htmlFor="theme-dark">Dark</Label>
  </div>
</RadioGroup>

Props

Name	Type	Default	Description
`Radio.value`Required	`string`	—	옵션 값. native value와 동일합니다.
`RadioGroup.value`	`string`	—	제어 모드 선택값. 있으면 checked로 제어합니다. onValueChange와 함께 사용합니다.
`RadioGroup.defaultValue`	`string`	—	비제어 초기 선택값. 해당 value Radio에 defaultChecked를 연결합니다 (native와 동일).
`RadioGroup.name`	`string`	—	폼 제출 시 필드 키. native name과 동일합니다. 생략 시 자동 생성.
`RadioGroup.size`	`"medium" \| "large"`	`"medium"`	컨트롤 크기. medium 16px · large 20px. 개별 Radio/RadioItem size가 있으면 그쪽이 우선합니다.
`RadioGroup.disabled`	`boolean`	—	그룹 전체 비활성화. 자식 Radio에 disabled를 전달합니다.
`RadioGroup.className`	`string`	—	레이아웃용. 예: flex flex-col gap-… / flex flex-row flex-wrap gap-…
`Radio.size`	`"medium" \| "large"`	`"medium"`	개별 크기. 미전달 시 그룹 size(또는 medium).
`Radio.defaultChecked`	`boolean`	—	비제어 초기 선택. 그룹 defaultValue 대신 개별 Radio에 직접 줄 수 있습니다.
`Radio.checked`	`boolean`	—	제어 모드 선택. 단독 사용 시 native checked와 동일합니다.
`Radio.disabled`	`boolean`	—	개별 비활성화. disabled만이면 Disabled(미선택), 선택 후 disabled면 Selected + Disabled.
`Radio.required`	`boolean`	—	native required. Overview는 제출 시 앱 검증(FieldError) 데모를 보여 줍니다.
`RadioItem`	`Radio + label`	—	Radio와 children 레이블을 한 줄로 묶습니다. itemClassName으로 래퍼를 조정합니다.
`Label (from @/components/label)`	`native <label>`	—	htmlFor로 Radio id와 연결합니다. Radio 패키지와 분리되어 있어 단독 import합니다.

Events

Name	Signature	Description
`RadioGroup.onValueChange`	`(value: string) => void`	선택값이 바뀔 때 호출됩니다. 제어/비제어 모두에서 사용 가능합니다.
`Radio.onChange`	`(event: ChangeEvent<HTMLInputElement>) => void`	native onChange. 그룹 사용 시에도 함께 호출됩니다.

Notes

소비 앱 필수: React 19, Tailwind CSS v4, ClaBi tokens.css(+ @theme 매핑), clsx.
clsx 패키지가 필수입니다. className 병합에 import { clsx } from "clsx" 를 사용합니다.
native <input type="radio"> 기반입니다. value가 없으면 비제어(defaultValue/defaultChecked), 있으면 제어입니다.
size는 medium(기본) · large입니다. 반응형(md:) 크기 전환은 없습니다. className에 size-* / w-* / h-*가 있으면 그 크기가 우선합니다.
disabled만이면 Disabled(미선택). Selected + Disabled는 defaultValue(또는 checked)로 선택한 뒤 disabled합니다.
Label은 @/components/label입니다. radio 폴더는 label에 의존하지 않습니다.