Radios

Use radios when users need to select exactly one option from a list. For longer lists (more than 6-7 options), consider using a select instead.

Default Radios

Radios use a large 32x32px touch target for accessibility and ease of use on mobile devices. Built with Radix UI primitives for full accessibility.

import * as RadioGroup from '@radix-ui/react-radio-group';

<fieldset className="form-fieldset">
  <legend className="form-legend">Where do you live?</legend>
  <RadioGroup.Root className="radix-radio-group" defaultValue="kaharagia">
    <div className="radix-radio-item">
      <RadioGroup.Item className="radix-radio" value="kaharagia" id="location-1">
        <RadioGroup.Indicator className="radix-radio-indicator" />
      </RadioGroup.Item>
      <label className="radix-radio-label" htmlFor="location-1">Kaharagia</label>
    </div>
    ...
  </RadioGroup.Root>
</fieldset>

Inline Radios

Use inline radios for short lists with short labels (like Yes/No questions).

<RadioGroup.Root
  className="radix-radio-group"
  style={{ flexDirection: 'row', gap: 'var(--space-6)' }}
>
  ...
</RadioGroup.Root>

With Hint Text

Use hint text in the legend to provide additional context.

<legend className="form-legend">
  How would you prefer to be contacted?
  <span className="form-legend-hint">Select one option.</span>
</legend>

Pre-selected Radio

Only pre-select a radio when there's a sensible default option.

<RadioGroup.Root className="radix-radio-group" defaultValue="html">
  ...
</RadioGroup.Root>

Error State

<fieldset className="form-fieldset form-group-error">
  <legend className="form-legend">Where do you live?</legend>
  <span className="form-error-message">Select where you live</span>
  <RadioGroup.Root className="radix-radio-group">
    ...
  </RadioGroup.Root>
</fieldset>

Controlled Radio Group

Use controlled components when you need to manage state in React.

const [value, setValue] = useState('');

<RadioGroup.Root
  className="radix-radio-group"
  value={value}
  onValueChange={setValue}
>
  ...
</RadioGroup.Root>

Usage Guidelines

Do

• Use radios when users can only select one option
• Use a fieldset and legend to group radios
• List options in a logical order
• Consider adding an "I don't know" or "None of the above" option

Don't

• Don't use radios for multiple selections (use checkboxes)
• Don't use radios for more than 6-7 options (use select)
• Don't pre-select a radio unless there's a sensible default

Radios vs Select

Accessibility

• Built with Radix UI primitives for full WAI-ARIA compliance
• Group radios in a fieldset with a descriptive legend
• Large touch targets (32x32px) for mobile accessibility
• Clear focus states with yellow outline
• Labels are clickable to select options
• Keyboard navigation: Arrow keys to move, Space to select

CSS Classes

/* Radix radio container */
.radix-radio-group { }
.radix-radio-item { }

/* Radio button */
.radix-radio { }
.radix-radio-indicator { }

/* Label (includes -2px adjustment for vertical centering) */
.radix-radio-label { }

/* Fieldset grouping */
.form-fieldset { }
.form-legend { }
.form-legend-hint { }

/* Error state */
.form-group-error { }
.form-error-message { }

Vertical Alignment

Radio labels include a margin-top: -2px adjustment for precise vertical centering with the radio button. This compensates for the visual difference between the geometric center and the optical center of text.

Installation

npm install @radix-ui/react-radio-group