Radio Group

Powered by

Base UIShadcn UI

Installation

Horizontal

Disabled items

When to use

Radio groups provide mutually exclusive options where users must select exactly one choice. Use this decision tree to determine when radio groups are appropriate:

Usage

Basic Usage

import { RadioGroup, RadioGroupItem } from "@/components/redpanda-ui/radio-group"
import { Label } from "@/components/redpanda-ui/label"

<RadioGroup defaultValue="option1">
  <div className="flex items-center space-x-2">
    <RadioGroupItem value="option1" id="r1" />
    <Label htmlFor="r1">Option 1</Label>
  </div>
  <div className="flex items-center space-x-2">
    <RadioGroupItem value="option2" id="r2" />
    <Label htmlFor="r2">Option 2</Label>
  </div>
  <div className="flex items-center space-x-2">
    <RadioGroupItem value="option3" id="r3" />
    <Label htmlFor="r3">Option 3</Label>
  </div>
</RadioGroup>

Controlled Usage

import { useState } from "react"

function ControlledRadioGroup() {
  const [value, setValue] = useState("option1")

  return (
    <RadioGroup value={value} onValueChange={setValue}>
      <div className="flex items-center space-x-2">
        <RadioGroupItem value="option1" id="r1" />
        <Label htmlFor="r1">Option 1</Label>
      </div>
      <div className="flex items-center space-x-2">
        <RadioGroupItem value="option2" id="r2" />
        <Label htmlFor="r2">Option 2</Label>
      </div>
    </RadioGroup>
  )
}

Anatomy

The Radio Group component is built with Base UI primitives:

RadioGroup (Root Container)
├── RadioGroupItem (Individual Radio Button)
│   ├── Border/Visual styling - circular border
│   └── RadioGroupIndicator (Selection Indicator)
│       └── Filled circle - shown when checked, fades/scales in via CSS
└── Layout - grid with gap-2.5 spacing

Key Features:

• Single Selection: Only one option can be selected at a time
• Keyboard Navigation: Arrow keys move between options, Space/Enter selects
• Accessibility: Full ARIA support with proper labeling and focus management
• Animation: Indicator fades and scales in via Base UI CSS transitions

Props

Examples

Default

Attached

With description

Error state

Card style

Form

Keyboard interactions

Accessibility

• The group container is role="radiogroup" and each item role="radio" with aria-checked. Base UI additionally sets the Radix-compat data-state="checked" | "unchecked" attribute.
• Always label the group: wrap it in a <Label> + visual heading, or use <Field> / <FormLabel> in a form context. Individual items also need associated <Label htmlFor>.
• Focus is roving — only the currently-selected item is tabbable. Arrow keys both move focus and select the next item (standard radio group semantics).
• onValueChange narrows Base UI's unknown value to string and forwards Base UI's eventDetails as an optional second argument, so the Radix-style single-argument callback keeps working while event/reason inspection remains available.

Credits

• We use Base UI for the radio group component.
• We take our inspiration from Shadcn UI for the radio group style.