Radio
An independent React adapter where Ark UI provides the parts and Zag maintains exclusive selection, roving focus, keyboard, and form behavior.
Design
Functional preview
Running with the independent Ark UI adapter and Zag behavior.
Loading functional preview…
Anatomy
1 Label (
2 Input (
3 Dot — CSS pseudo-element, visible when selected.
4 Group (
5 Legend (
.ds-radio-label) — wraps radio + text, extends click target.2 Input (
.ds-radio) — styled native <input type="radio">.3 Dot — CSS pseudo-element, visible when selected.
4 Group (
.ds-radio-group) — <fieldset> wrapping related radios.5 Legend (
.ds-radio-group__legend) — group heading, provides context to screen readers.
Radio Group
Sizes
Error Group
Disabled
States
| State | CSS trigger | Visual change | Token |
|---|---|---|---|
| Unselected | --- | Neutral control fill and border | component.radio.control.fill.unselected.default, component.radio.control.border-color.unselected.default |
| Unselected hover | :hover | Darker neutral control border/fill | component.radio.control.fill.unselected.hover, component.radio.control.border-color.unselected.hover |
| Selected | :checked | Primary control fill with dot | component.radio.control.fill.selected.default, component.radio.dot.fill.selected.default |
| Selected hover | :checked:hover | Darker primary control fill | component.radio.control.fill.selected.hover, component.radio.dot.fill.selected.hover |
| Focus | :focus-visible | 2px outline ring | component.radio.focus-ring.radius.default + component.focus-ring.* |
| Error group | .ds-radio-group--error | Error border on controls and message below group | component.radio.control.border-color.unselected.error, semantic.feedback.error.content-default |
| Disabled | [disabled] | Muted control, dot and label | component.radio.control.fill.*.disabled, semantic.content.disabled |
Figma properties
| Property | Type | Default | Description |
|---|---|---|---|
Show Label | Boolean | true | Shows or hides the control label |
Label | Text | "Rótulo" | Label text (label/md) |
Show Description | Boolean | false | Shows descriptive text below the label |
Description | Text | "Texto descritivo" | Multiline description text (body/sm) |
Show Helper Text | Boolean | false | Shows helper text below the description |
Helper Text | Text | "Texto auxiliar" | Caption/sm annotation (content/secondary) |
Usage
When to use
- Exactly one option must be selected among two to seven visible alternatives.
- Comparing the alternatives before choosing supports the decision.
When not to use
- Zero, one, or multiple options may be selected; use Checkbox.
- There are many alternatives or limited space; use Select.
When to choose this output
Choose this adapter in projects that adopted Ark UI and Zag as their behavioral architecture. Do not import it into the shadcn/Base UI output.
Implementation
- Status
- Beta
- Distribution
- Source adapter
Adapter source
packages/react/src/ark/radio.jsx
import {
RadioGroup,
RadioGroupContent,
RadioGroupHiddenInput,
RadioGroupItem,
RadioGroupLabel,
RadioGroupLegend,
RadioGroupOption,
} from '@tis/react/ark/radio'Accessibility
Keyboard interaction
| Key | Action |
|---|---|
Tab | Moves focus into the radio group (single tab stop) or out of it |
Arrow Up / Arrow Left | Selects the previous option in the group |
Arrow Down / Arrow Right | Selects the next option in the group |
A radio group behaves as a single tab stop. Arrow keys navigate between options within the group, and selection moves with focus.
Accessibility
| WCAG criterion | Requirement | Status |
|---|---|---|
| 1.3.1 Info and Relationships (A) | Group in <fieldset> + <legend> | ✓ |
| 2.4.11 Focus Appearance (AA) | Focus ring visible via :focus-visible | ✓ |
| 2.5.8 Target Size min (AA) | Label extends click target beyond the radio itself | ✓ |
| 4.1.2 Name, Role, Value (A) | Native <input type="radio"> provides role + state automatically | ✓ |
| 3.3.1 Error Identification (A) | Group error communicated via ds-radio-group--error | ✓ |
Implementation notes
Always wrap radio groups in a <fieldset> with a <legend> to provide group context to screen readers. Uses native <input type="radio"> for built-in keyboard navigation -- arrow keys move between options within a group, Tab enters and exits the group. Focus ring is visible on keyboard focus via :focus-visible.
Invisible label — requires explicit ARIA
When Show Label = false and Show Description = true, link the <input> to the description via aria-labelledby="description-id". If neither is visible, use aria-label directly on the <input>. Helper Text should always be linked via aria-describedby="helper-id".
Output responsibility
Preserve the Ark/Zag semantics and validate exclusive selection, arrow navigation, Space, disabled and invalid states, visible focus, and hidden-input form submission.
Validation evidence
Covered by its independent Storybook output plus browser, responsive, keyboard, Axe, and bundle checks.