Skip to main content
Kaleidoscope

RadioGroup

Use RadioGroup to select a single option from a list of choices.

Default

The <RadioGroup /> component wraps a set of <RadioGroupItem /> children and manages the selected value via onChange.

Editable example
() => {
  const [value, setValue] = React.useState("swiss")

  return (
    <RadioGroup value={value} onChange={setValue} label="Pick a cheese">
      <RadioGroupItem value="swiss" label="Swiss" />
      <RadioGroupItem value="camembert" label="Camembert" />
      <RadioGroupItem value="parmesan" label="Parmesan" />
    </RadioGroup>
  )
}

Disabled items

Use the disabled prop on individual <RadioGroupItem /> elements to prevent selection.

Editable example
() => {
  const [value, setValue] = React.useState("swiss")

  return (
    <RadioGroup value={value} onChange={setValue} label="Pick a cheese">
      <RadioGroupItem value="swiss" label="Swiss" />
      <RadioGroupItem value="camembert" label="Camembert" disabled />
      <RadioGroupItem value="parmesan" label="Parmesan" />
    </RadioGroup>
  )
}

Hidden labels

By default the group label is visible. Set labelHidden on <RadioGroup /> to visually hide the group label, or on individual <RadioGroupItem /> elements to hide item labels. Hidden labels are still accessible to screen readers.

Editable example
() => {
  const [value, setValue] = React.useState("swiss")

  return (
    <RadioGroup value={value} onChange={setValue} label="Pick a cheese" labelHidden>
      <RadioGroupItem value="swiss" label="Swiss" />
      <RadioGroupItem value="camembert" label="Camembert" />
      <RadioGroupItem value="parmesan" label="Parmesan" />
    </RadioGroup>
  )
}

Truncated labels

For long labels that might overflow, use the truncate prop on <RadioGroupItem /> to clip the text with an ellipsis.

Editable example
() => {
  const [value, setValue] = React.useState("1")

  return (
    <div style={{ maxWidth: 300 }}>
      <RadioGroup value={value} onChange={setValue} label="Long labels">
        <RadioGroupItem
          value="1"
          label="This is a radio button with a really long label that wraps over multiple lines by default"
        />
        <RadioGroupItem
          truncate
          value="2"
          label="And here's one with a truncated long label that will get chopped off with ellipsis"
        />
      </RadioGroup>
    </div>
  )
}

Best practices

  1. Use RadioGroup when only one option can be selected from a list. For selecting zero or more options, use .
  2. For selecting one item from a small set of compact options, consider or instead.
  3. Keep labels short and descriptive so users can quickly scan the available choices.

Accessibility

  • Always provide a meaningful label on <RadioGroup /> — even when hidden, it is used by screen readers to describe the group.
  • Arrow keys navigate between items within the group, following the standard radiogroup keyboard interaction pattern.
  • Each radio item uses role="radio" and aria-checked to communicate its state to assistive technology.