RadioGroup

import { RadioGroup, RadioGroupItem } from '@elirobinson/react/components/atoms/RadioGroup';

import { RadioGroup, RadioGroupItem } from '@elirobinson/react/components/atoms/RadioGroup';

export default function Basic() {
  return (
    <RadioGroup name="plan" defaultValue="pro">
      <RadioGroupItem value="free" label="Free" />
      <RadioGroupItem value="pro" label="Pro" />
      <RadioGroupItem value="enterprise" label="Enterprise" />
    </RadioGroup>
  );
}

When to use it

Use RadioGroup for a small, always-visible set of mutually exclusive options — two to six is the sweet spot. Once the list gets long enough to need scrolling or search, reach for Select or Combobox instead.

RadioGroup is context-based: the group owns name, the current value, and change handling. RadioGroupItem only takes value and label — it can't take checked, onChange, or name directly, so there's no way to desync an item from its group. Rendering a RadioGroupItem outside a RadioGroup throws immediately; the two aren't meant to be used apart.

Controlled

Pass value and onValueChange to drive selection from your own state. Passing defaultValue instead makes it uncontrolled — don't pass both.

import { useState } from 'react';

import { RadioGroup, RadioGroupItem } from '@elirobinson/react/components/atoms/RadioGroup';

export default function Controlled() {
  const [duration, setDuration] = useState('60');

  return (
    <div className="demo-col">
      <RadioGroup name="session-length" value={duration} onValueChange={setDuration}>
        <RadioGroupItem value="30" label="30 minutes" />
        <RadioGroupItem value="60" label="60 minutes" />
        <RadioGroupItem value="90" label="90 minutes" />
      </RadioGroup>
      <p>Booking a {duration}-minute session.</p>
    </div>
  );
}

Clearing a controlled group

value distinguishes empty from absent, and the difference decides the mode:

• null — controlled, nothing selected. This is how you clear a controlled group.
• undefined — uncontrolled. The group falls back to defaultValue and its own internal state, exactly as if value had never been passed.

So type your state string | null, not string | undefined:

const [plan, setPlan] = useState<string | null>(null);

<RadioGroup name="plan" value={plan} onValueChange={setPlan}>
  <RadioGroupItem value="free" label="Free" />
  <RadioGroupItem value="pro" label="Pro" />
</RadioGroup>
<button onClick={() => setPlan(null)}>Clear</button>;

Clearing with undefined instead does not clear the group — it hands selection back to the group's own state, which still holds the last click. TypeScript can't catch that, since undefined is legal for an optional prop, so the group warns in development when value goes from a string to undefined.

Form submission

The group works with native form submission on its own — no hidden input, no extra wiring. RadioGroupItem renders a real input[type="radio"], so the group's name is also the submitted field name, and the selection is in FormData and in a server action's payload under that name:

<form action={savePlan}>
  <RadioGroup name="plan" defaultValue="free">
    <RadioGroupItem value="free" label="Free" />
    <RadioGroupItem value="pro" label="Pro" />
  </RadioGroup>
  <Button type="submit">Save</Button>
</form>

formData.get('plan') is 'free' or 'pro'. This holds in both modes — a controlled group submits its current selection too.

Props

Accessibility

• The wrapper renders role="radiogroup"; each RadioGroupItem renders a native input[type="radio"] sharing the group's name.
• Keyboard: because the inputs share a native name, arrow keys move between items and select as they go, and Tab treats the whole group as a single stop — that's the browser's built-in radio-group behavior, not something this component reimplements.
• RadioGroup has no label prop of its own — introduce it with a standalone Label connected via aria-labelledby (a plain div isn't a labelable element, so htmlFor doesn't reliably associate here).
• The ref on RadioGroup forwards to the wrapping <div>; the ref on RadioGroupItem forwards to its <input>.

Related