Radio
radioSelects one mutually exclusive value from an accessible radio group.
Usage
Basic usage
RadioGroup packages multiple Radio, single selections are mutually exclusive, and the default is vertical arrangement.
<RadioGroup defaultValue="b" aria-label="options">
<Radio value="a" label="Option 1" />
<Radio value="b" label="Option 2" />
<Radio value="c" label="Option 3" />
</RadioGroup>Horizontal arrangement
Set orientation="horizontal" to arrange the options horizontally.
<RadioGroup orientation="horizontal" defaultValue="m" aria-label="Gender">
<Radio value="m" label="Male" />
<Radio value="f" label="Female" />
</RadioGroup>Disabled
A single Radio plus disabled disables one item; the entire group disabled disables all.
<RadioGroup defaultValue="a" aria-label="Package">
<Radio value="a" label="Standard" />
<Radio value="b" label="Professional (not available yet)" disabled />
<Radio value="c" label="Flagship" />
</RadioGroup>With Field verification
Package into Field to get labels and error prompts, and the check state will be transmitted to the circle stroke.
<Field label="Package" error="Please select a package" className="w-72">
<RadioGroup defaultValue="">
<Radio value="basic" label="Basic Edition" />
<Radio value="plus" label="Enhanced Version" />
</RadioGroup>
</Field>When to use
Use Radio when exactly one choice must be selected from a small set—typically two to six—and every option should remain visible. Use Select when a larger set should collapse or support search, CheckboxGroup when several choices may coexist, or Segmented for two or three compact horizontal choices with a sliding indicator.
Import
import { RadioGroup, Radio } from "@hulianui/ui"Props
RadioGroup
| Name | Type | Default | Description |
|---|---|---|---|
| value | string | — | Controlled selected value. |
| defaultValue | string | — | Initial selected value when uncontrolled. |
| disabled | boolean | false | Disables the entire group. |
| required | boolean | — | Marks the native form control as required. |
| name | string | — | Native form name |
| orientation | "vertical"|"horizontal" | "vertical" | Controls layout only. |
| className | string | — | — |
| aria-label | string | — | Provided when no title is visible |
Radio
| Name | Type | Default | Description |
|---|---|---|---|
| value * | string | — | Required value identifying the option. |
| disabled | boolean | false | Disables this option. |
| id | string | — | — |
| className | string | — | Applied to Radio.Root. |
| aria-label | string | — | Accessible name. Required when `label` is omitted or contains only visual content such as an icon. |
| aria-labelledby | string | — | ID of an existing element used as the accessible name; use instead of aria-label. |
| aria-describedby | string | — | ID of supplementary descriptive text for the option. |
Events
RadioGroup
| Event | Type | Description |
|---|---|---|
| onValueChange | (value: string) => void | Called when selection changes. |
Slots
RadioGroup
| Slot | Type | Description |
|---|---|---|
| children | ReactNode | Radio items in the group. |
Radio
| Slot | Type | Description |
|---|---|---|
| label | ReactNode | Optional clickable inline label with native <label> association. |
Example
<RadioGroup defaultValue="b" aria-label="Options">
<Radio value="a" label="Option one" />
<Radio value="b" label="Option two" />
<Radio value="c" label="Option three (disabled)" disabled />
</RadioGroup>Horizontal and controlled:
const [value, setValue] = useState("standard");
<RadioGroup value={value} onValueChange={setValue} orientation="horizontal" aria-label="Plan">
<Radio value="standard" label="Standard" />
<Radio value="pro" label="Pro" />
</RadioGroup>Usage guidelines
RadioGroupowns selection; individual Radio items do not expose a separatecheckedstate.- Controlled usage requires
valueandonValueChange. UsedefaultValueonly for uncontrolled initial state; do not mix the two patterns. - Give a group without a visible heading an
aria-labelso screen readers can identify its purpose. - A Radio without a textual `label` must provide `aria-label` or `aria-labelledby`. This includes icon cards and custom layouts; otherwise assistive technology announces only “radio button” without identifying the choice.
Related
Input · Textarea · Select · Checkbox · CheckboxGroup · Switch
Playground
<RadioGroup orientation="vertical" defaultValue="standard">
<Radio value="standard" label="Standard" />
<Radio value="pro" label="Professional" />
</RadioGroup>