Radio

A radio button component for selecting a single option from a group.

Beer Preference

Choose your preferred beer type

 
<Fieldset 
    title="Beer Preference" 
    subtitle="Choose your preferred beer type">
    <Field>
        <RadioGroup defaultValue="ale">
            <Radio value="ale">Ale</Radio>
            <Radio value="lager">Lager</Radio>
            <Radio value="na">Non-Alcoholic</Radio>
        </RadioGroup>
    </Field>
</Fieldset>

Overview

The Radio component provides a way for users to select a single option from a group of choices. It’s designed to work within the RadioGroup component for proper grouping and works seamlessly with the Field component for labels and error handling.

Basic Usage

Description

Radio can be used with or without labels, and supports standard states including disabled and error states.

With Label
With Error
Disabled 
<div className="space-y-6 max-w-sm">
  <Field>
    <RadioGroup>
      <Radio value="unlabeled">Unlabeled radio group</Radio>
      <Radio value="option2">Option 2</Radio>
    </RadioGroup>
  </Field>

  <Field>
    <FieldLabel>With Label</FieldLabel>
    <RadioGroup>
      <Radio value="ipa">IPA</Radio>
      <Radio value="stout">Stout</Radio>
      <Radio value="pilsner">Pilsner</Radio>
    </RadioGroup>
  </Field>
  
  <Field>
    <FieldLabel>With Error</FieldLabel>
    <RadioGroup aria-invalid={true}>
      <Radio value="option1">This radio group has an error</Radio>
      <Radio value="option2">Option 2</Radio>
    </RadioGroup>
  </Field>
  
  <Field>
    <FieldLabel>Disabled</FieldLabel>
    <RadioGroup disabled defaultValue="disabled2">
      <Radio value="disabled1">This radio is disabled</Radio>
      <Radio value="disabled2">This is disabled and selected</Radio>
    </RadioGroup>
  </Field>
</div>

Horizontal Layout

Description

Display radio buttons in a horizontal row by customizing the RadioGroup’s className.

Serving Temperature

Select your preferred serving temperature

 
<Fieldset 
    title="Serving Temperature" 
    subtitle="Select your preferred serving temperature">
    <Field>
        <RadioGroup defaultValue="cold" className="flex-row space-x-6 space-y-0">
            <Radio value="cold">Cold</Radio>
            <Radio value="cool">Cool</Radio>
            <Radio value="cellar">Cellar Temp</Radio>
        </RadioGroup>
    </Field>
</Fieldset>

Components

Radio

The individual radio button component.

Props

PropTypeDefaultDescription
valuestring-The value of this radio option
childrenReactNode-Label text for the radio button
classNamestring-Additional CSS class names
disabledbooleanfalseDisables the radio button (inherited from RadioGroup)

RadioGroup

A container component for organizing multiple radio buttons.

Props

PropTypeDefaultDescription
defaultValuestring-Initial selected value (uncontrolled)
valuestring-Controlled selected value
disabledbooleanfalseDisables all radio buttons in the group
aria-invalidbooleanfalseIndicates validation error state for the group
classNamestring-Additional CSS class names for layout customization
childrenReactNode-Radio components to display

Additional Features

  • Validation States: Use aria-invalid on RadioGroup to show error styling on all radios
  • Focus States: Automatic focus ring styling matching other form components
  • Dark Mode: Fully themed with CSS custom properties
  • Keyboard Navigation: Arrow keys navigate between options, Space selects
  • Custom Layout: Use className to control spacing and direction (flex-row for horizontal)

Usage Notes

  • Radio buttons should always be used within a RadioGroup
  • Each Radio must have a unique value prop
  • Only one radio can be selected at a time within a group
  • Use FieldLabel or Fieldset title for the group label
  • The disabled state applies to all radios when set on RadioGroup

Accessibility

The Radio component follows accessibility best practices:

  • Uses semantic HTML with proper ARIA attributes
  • Supports keyboard navigation (Arrow keys to move, Space to select)
  • Maintains proper focus styles for keyboard users
  • Provides visual feedback for selected/unselected states
  • Ensures sufficient color contrast for the radio indicator

When implementing radio buttons, ensure that:

  1. Radio groups have clear labels describing the choice
  2. Each radio option has descriptive text
  3. Related radios are grouped using RadioGroup
  4. Form validation messages are clearly associated with radio groups
  5. Only one radio can be selected at a time within a group