Radio
A React source recipe with Base UI behavior and the public TIS Radio classes and tokens.
Design
Functional preview
Running with the React source recipe distributed through shadcn and based on Base UI.
Loading functional preview…
Open the React · shadcn/Base UI playground
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.
React composition
import {
RadioGroup,
RadioGroupItem,
RadioGroupLabel,
RadioGroupLegend,
RadioGroupOption,
} from "@/components/ui/radio-group"
<RadioGroup name="channel" defaultValue="email">
<RadioGroupLegend>Canal</RadioGroupLegend>
<RadioGroupOption>
<RadioGroupItem value="email" />
<RadioGroupLabel>E-mail</RadioGroupLabel>
</RadioGroupOption>
</RadioGroup>Implementation
- Status
- Beta
- Distribution
- Source via shadcn
Installation
Configure the namespace once in the React integration guide.
npx shadcn@latest add @tis/radio-grouppnpm dlx shadcn@latest add @tis/radio-groupyarn dlx shadcn@latest add @tis/radio-groupbunx --bun shadcn@latest add @tis/radio-groupPublic contract
- Registry item
@tis/radio-group- Provider
- Base UI
- Distribution
- Source copied into the application
- Status
- Beta
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 Base UI semantics and test real content, focus visibility, and accessible names in the consuming application.
Validation evidence
Covered by its independent Storybook output plus browser, responsive, keyboard, Axe, and bundle checks.