RadioTile

RadioTile provides a larger, more prominent radio button option with optional description text.

Installation

npx usmds add radiotile

Usage

import { RadioTileGroup, RadioTile } from '@components/RadioTile';
import { useState } from 'react';
 
function App() {
  const [value, setValue] = useState('1');
 
  return (
    <RadioTileGroup value={value} onValueChange={setValue}>
      <RadioTile 
        value="1" 
        label="Option 1"
        description="Optional description text" 
      />
      <RadioTile 
        value="2" 
        label="Option 2"
        description="Optional description text" 
      />
    </RadioTileGroup>
  );
}

Props

RadioTile

Extends RadioGroupPrimitive.Item props.

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

RadioTileGroup

Extends RadioGroupPrimitive.Root props.

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

Examples

Basic Usage

<RadioTileGroup value={value} onValueChange={setValue}>
  <RadioTile value="1" label="Option 1" />
  <RadioTile value="2" label="Option 2" />
  <RadioTile value="3" label="Option 3" />
</RadioTileGroup>

With Description

<RadioTileGroup value={value} onValueChange={setValue}>
  <RadioTile
    value="1"
    label="Option with description"
    description="This is optional text that can be used to describe the label in more detail."
  />
  <RadioTile
    value="2"
    label="Another option"
    description="More descriptive text here."
  />
</RadioTileGroup>

Disabled States

<RadioTileGroup value="1" onValueChange={() => {}}>
  <RadioTile
    value="1"
    label="Disabled selected"
    description="Optional description text"
    disabled
  />
  <RadioTile
    value="2"
    label="Disabled unselected"
    description="Optional description text"
    disabled
  />
</RadioTileGroup>

Styling

The RadioTile component uses Tailwind CSS classes for styling through class-variance-authority (cva). Default styling includes:

Container width: 329px
Rounded corners (2px)
2px border width
Radio indicator: 20px × 20px
Consistent padding (13px 16px 13px 9px)
Primary colors when selected
Light background when selected
Gap spacing between elements

States

Radio tiles have several visual states:

Unchecked: White background with light border
Checked: Light primary background with primary border
Disabled: White background with gray border and text

Accessibility

The RadioTile component:

Uses accessibilityRole="radio" for proper semantic structure
Supports keyboard navigation within RadioTileGroup
Maintains WCAG color contrast requirements
Provides appropriate accessibilityState for checked and disabled states
Uses proper labeling with aria-labelledby and aria-describedby
Ensures adequate touch target size

RadioTile

On this page