Installation

Barrel

Granular

Usage

export default function Example() {
  return (
    <Radio.Group legend="Choose an option" defaultValue="a">
      <Radio.Item label="Option A" value="a" />
      <Radio.Item label="Option B" value="b" />
    </Radio.Group>
  );
}

Examples

Default (Vertical)

Radio groups display vertically by default. Each radio has a label displayed to its right.

Horizontal

Use orientation="horizontal" for inline layouts. Items wrap when there isn't enough space.

With Description

Add helper text below the radio items using the description prop.

Control Position

Use controlPosition="end" to place labels before radio buttons.

Radio Card

Use appearance="card" on the group to display each option as a selectable card. Combine with the description prop on each item for richer content.

Radio Card (Control on the Left)

Use controlPosition="start" on a card radio group to place the radio control on the left of the label and description.

Rich Label Content

The label prop on Radio.Item accepts React nodes, so you can embed icons, badges, or other markup alongside the text.

Radio Card (Horizontal)

Combine appearance="card" with orientation="horizontal" for a side-by-side card layout.

With Error

Show validation errors at the group level using the error prop.

Disabled

Disable the entire group or individual items.

Visually Hidden Legend

Use Radio.Legend with className="sr-only" to keep the legend accessible to screen readers while hiding it visually. This is useful when the radio group is already labeled by a parent Field or heading, and showing the legend would create a redundant label.

Custom Legend Styling

Radio.Legend accepts className for full control over legend presentation. Use it instead of the legend string prop when you need custom typography, colors, or layout.

API Reference

Radio.Group

Container for radio buttons with legend, description, and error support.

Radio.Legend

Composable legend sub-component for Radio.Group. Accepts className for full styling control (e.g. className="sr-only" to visually hide). Use instead of the legend string prop when you need custom legend styling.

Radio.Item

Individual radio button within Radio.Group.

Accessibility

  ### Semantic HTML

  
    Radio.Group uses semantic `<fieldset>` and `<legend>` elements for proper grouping and screen reader announcement.
  



  ### Keyboard Navigation

  
    <kbd class="rounded bg-kumo-control px-1.5 py-0.5">Arrow Up/Down</kbd> or <kbd class="rounded bg-kumo-control px-1.5 py-0.5">Arrow Left/Right</kbd> moves between options. <kbd class="rounded bg-kumo-control px-1.5 py-0.5">Space</kbd> selects the focused option. <kbd class="rounded bg-kumo-control px-1.5 py-0.5">Tab</kbd> moves focus to and from the radio group.
  



  ### Screen Readers

  
    Each radio is announced with its label and selection state. The group legend provides context for all options.