RadioButton

Installation

npx usmds add radiobutton

Usage

import { RadioGroup, RadioButton } from '@components/RadioButton';
import { useState } from 'react';
 
function App() {
  const [value, setValue] = useState('1');
 
  return (
    <RadioGroup value={value} onValueChange={setValue}>
      <RadioButton value="1" label="Option 1" />
      <RadioButton value="2" label="Option 2" />
      <RadioButton value="3" label="Option 3" />
    </RadioGroup>
  );
}

Props

RadioButton

Extends RadioGroupPrimitive.Item props.

Prop	Type	Default	Description
label	`string`	-	The text label for the radio button.
value	`string`	-	The value associated with this radio button.
disabled	`boolean`	`false`	When true, prevents user interaction.
className	`string`	-	Additional Tailwind classes to apply.

RadioGroup

Extends RadioGroupPrimitive.Root props.

Prop	Type	Default	Description
value	`string`	-	The value of the selected radio button.
onValueChange	`(value: string) => void`	-	Callback fired when selection changes.

Examples

Basic Usage

<RadioGroup value={value} onValueChange={setValue}>
  <RadioButton value="1" label="Option 1" />
  <RadioButton value="2" label="Option 2" />
  <RadioButton value="3" label="Option 3" />
</RadioGroup>

Single Radio Button

<RadioGroup value={value} onValueChange={setValue}>
  <RadioButton value="1" label="Single radio button" />
</RadioGroup>

Disabled States

<RadioGroup value="4" onValueChange={() => {}}>
  <RadioButton value="3" label="Disabled unselected" disabled />
  <RadioButton value="4" label="Disabled selected" disabled />
</RadioGroup>

Styling

The RadioButton component uses Tailwind CSS classes for styling. Default styling includes:

Container dimensions: 329px × 44px (minimum height)
Radio button size: 20px × 20px
2px border width
Rounded full circles
Primary color when selected
Disabled state styling
8px gap between radio and label

States

Radio buttons have several visual states:

Unselected: White background with base ink border
Selected: Primary color fill with primary border
Disabled unselected: Gray border
Disabled selected: Gray fill and border

Accessibility

The RadioButton component:

Uses accessibilityRole="radio" for proper semantic structure
Supports keyboard navigation within RadioGroup
Maintains WCAG color contrast requirements
Provides appropriate accessibilityState for checked and disabled states
Uses proper labeling with aria-labelledby
Ensures adequate touch target size (44px minimum height)

RadioButton

On this page