RadioGroup

RadioGroup is a single-choice control: a set of circular options, each with an inline label. The circles reuse the family's shared control surface, so they sit flush beside an Input, and label / description / error / required are built in via Field. It implements the kit's form-control contract — name submits, and ref / onBlur land on the group root — so it binds to react-hook-form, TanStack Form, or a plain <form> with no glue.

import { RadioGroup } from '@42-central/ui-react/radio-group';

<RadioGroup
  label="Coalition"
  data={[
    { value: 'federation', label: 'The Federation' },
    { value: 'order', label: 'The Order' },
    { value: 'alliance', label: 'The Alliance' },
  ]}
/>

The data prop also accepts bare strings, normalized to { value, label }:

<RadioGroup label="Size" data={['Small', 'Medium', 'Large']} />

Playground

<Component
  label="Coalition"
  orientation="vertical"
  size="md"
  variant="default"
/>

Orientation

Options stack vertically by default. Set orientation="horizontal" to lay them out in a wrapping row.

<RadioGroup
  label="Coalition"
  orientation="horizontal"
  defaultValue="order"
  data={[
    { value: 'federation', label: 'The Federation' },
    { value: 'order', label: 'The Order' },
    { value: 'alliance', label: 'The Alliance' },
  ]}
/>

Sizes

Five sizes — xs through xl — matching the rest of the family. The circle and its dot scale together.

<RadioGroup size="xs" defaultValue="a" data={[{ value: 'a', label: 'xs' }]} />
<RadioGroup size="sm" defaultValue="a" data={[{ value: 'a', label: 'sm' }]} />
<RadioGroup size="md" defaultValue="a" data={[{ value: 'a', label: 'md' }]} />
<RadioGroup size="lg" defaultValue="a" data={[{ value: 'a', label: 'lg' }]} />
<RadioGroup size="xl" defaultValue="a" data={[{ value: 'a', label: 'xl' }]} />

Variants

Two variants decide the selected circle's fill. default is a neutral, monochrome circle that stays palette-independent; filled tints the circle with color. The two share one inner dot.

<RadioGroup
  variant="default"
  defaultValue="a"
  data={[{ value: 'a', label: 'Default' }]}
/>
<RadioGroup
  variant="filled"
  color="brand"
  defaultValue="a"
  data={[{ value: 'a', label: 'Filled' }]}
/>

Colors

color tints the selected circle in the filled variant — the default variant stays monochrome. The resting circle is palette-independent, and the focus ring is always the brand ring. Set data-color once on the root and every kit palette tints for free.

<RadioGroup variant="filled" color="brand" defaultValue="a" data={[{ value: 'a', label: 'brand' }]} />
<RadioGroup variant="filled" color="green" defaultValue="a" data={[{ value: 'a', label: 'green' }]} />
<RadioGroup variant="filled" color="blue" defaultValue="a" data={[{ value: 'a', label: 'blue' }]} />
<RadioGroup variant="filled" color="purple" defaultValue="a" data={[{ value: 'a', label: 'purple' }]} />
<RadioGroup variant="filled" color="red" defaultValue="a" data={[{ value: 'a', label: 'red' }]} />

Disabled & per-option disabled

disabled dims the whole group and blocks interaction. A single option can also be disabled by setting disabled on its data entry.

Each option also accepts its own optional testId, defaulting to `item-${value}` when omitted, rendered on that option's own element — see the Testing guide.

<RadioGroup
  label="Coalition"
  defaultValue="federation"
  data={[
    { value: 'federation', label: 'The Federation' },
    { value: 'order', label: 'The Order (full)', disabled: true },
    { value: 'alliance', label: 'The Alliance' },
  ]}
/>

<RadioGroup label="Coalition" disabled defaultValue="federation" data={[{ value: 'federation', label: 'The Federation' }, { value: 'order', label: 'The Order' }]} />

With description & error

description (helper text) and error sit below the group via the built-in Field. Passing error flips the circles to the invalid (red) state; required adds the semantic flag and a red asterisk on the label.

<RadioGroup
  label="Coalition"
  description="You can change this at any time."
  defaultValue="order"
  data={[{ value: 'federation', label: 'The Federation' }, { value: 'order', label: 'The Order' }]}
/>

<RadioGroup label="Pick a coalition" required data={[{ value: 'federation', label: 'The Federation' }, { value: 'order', label: 'The Order' }]} />

<RadioGroup label="Pick a coalition" error="Please choose a coalition" data={[{ value: 'federation', label: 'The Federation' }, { value: 'order', label: 'The Order' }]} />

Controlled

Drive the selection from state. onChange hands you the next value (a string).

'use client';
import { useState } from 'react';
import { RadioGroup } from '@42-central/ui-react/radio-group';

export function CoalitionPicker() {
  const [coalition, setCoalition] = useState('federation');
  return (
    <RadioGroup
      label="Coalition"
      value={coalition}
      onChange={setCoalition}
      data={[
        { value: 'federation', label: 'The Federation' },
        { value: 'order', label: 'The Order' },
      ]}
    />
  );
}

Forms

Each option renders a hidden native <input type="radio"> sharing the group name, so a name wires the selection into native <form> submission and FormData.

<form action={save}>
  <RadioGroup
    name="coalition"
    label="Coalition"
    data={[
      { value: 'federation', label: 'The Federation' },
      { value: 'order', label: 'The Order' },
    ]}
  />
</form>

API

Accessibility

• Full RadioGroup model from Ark: arrow keys move between options and select, Space selects the focused option, focus shows the ring, and the group / label / description / error associations are wired (the latter via the built-in Field).
• Each option is backed by a hidden native <input type="radio"> sharing the group name, exposing role="radio" with aria-checked.
• invalid (or error) sets aria-invalid on the options.
• RTL is honored via the document dir — circles and labels mirror automatically.

Changelog