> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Radio and RadioGroup Components: Single-Select Groups

> Use Radio and RadioGroup to present a mutually exclusive set of options — users pick exactly one, with full keyboard and screen-reader support.

The `Radio` and `RadioGroup` components let you present a set of mutually exclusive options so the user can pick exactly one. Both are **Status: Draft** and are backed by [Mantine's Radio](https://mantine.dev/core/radio/) primitive. Clementine exports them directly from `@clementine-ds/ui` with the Clementine theme applied.

***

## When to use

* You need to let the user select **one and only one** option from a small, fixed set (typically 2–6 items).
* All options should be visible at once — no scrolling, no searching.
* The choice requires clear visual separation between options (radio circles make mutually exclusive semantics obvious).

## When not to use

* **Non-exclusive selection** — use `Checkbox` instead so the user can pick multiple items.
* **Many options** (more than \~6) — use `Select` to keep the interface compact.
* A single on/off toggle — use `Switch`, which communicates binary state more clearly.

***

## Usage

Import both `Radio` and `RadioGroup` from `@clementine-ds/ui`. Wrap individual `Radio` items inside a `RadioGroup` to wire up accessible group semantics, keyboard navigation, and shared controlled state.

### Uncontrolled group

```tsx theme={null}
import { Radio, RadioGroup, Stack } from '@clementine-ds/ui';

export function PlanSelector() {
  return (
    <RadioGroup
      name="plan"
      label="Choose a plan"
      description="You can change your plan at any time."
      defaultValue="pro"
    >
      <Stack mt="xs" gap="xs">
        <Radio value="free" label="Free" />
        <Radio value="pro" label="Pro" />
        <Radio value="enterprise" label="Enterprise" />
      </Stack>
    </RadioGroup>
  );
}
```

### Controlled group

```tsx theme={null}
import { useState } from 'react';
import { Radio, RadioGroup, Stack } from '@clementine-ds/ui';

export function ControlledPlanSelector() {
  const [plan, setPlan] = useState<string>('pro');

  return (
    <RadioGroup
      name="plan"
      label="Choose a plan"
      value={plan}
      onChange={setPlan}
    >
      <Stack mt="xs" gap="xs">
        <Radio value="free" label="Free" />
        <Radio value="pro" label="Pro" />
        <Radio value="enterprise" label="Enterprise" />
      </Stack>
    </RadioGroup>
  );
}
```

### Disabled state

```tsx theme={null}
import { Radio, RadioGroup, Stack } from '@clementine-ds/ui';

export function DisabledGroup() {
  return (
    <RadioGroup name="tier" label="Subscription tier" defaultValue="basic" disabled>
      <Stack mt="xs" gap="xs">
        <Radio value="basic" label="Basic" />
        <Radio value="standard" label="Standard" />
        <Radio value="premium" label="Premium" />
      </Stack>
    </RadioGroup>
  );
}
```

***

## Props

### `Radio`

`RadioProps` extends Mantine's `RadioProps`, which itself extends the native `<input type="radio">` element. All standard HTML input attributes are forwarded to the underlying input.

| Prop | Type | Default | Description |
| - | - | - | - |
| `label` | `React.ReactNode` | — | Text label associated with the radio input. Clickable. |
| `description` | `React.ReactNode` | — | Help text displayed below the label. |
| `error` | `React.ReactNode` | — | Error message displayed below the label; applies error styles. |
| `value` | `string` | — | Value submitted with `FormData` and used by `RadioGroup` to identify which option is selected. |
| `checked` | `boolean` | — | Controls the checked state (controlled usage). |
| `defaultChecked` | `boolean` | — | Sets the initial checked state (uncontrolled usage). |
| `disabled` | `boolean` | — | Prevents interaction and applies disabled styles. |
| `name` | `string` | — | Groups radios for native browser behaviour. Generated automatically when used inside `RadioGroup`. |
| `labelPosition` | `"left" \| "right"` | `"right"` | Position of the label relative to the radio input. |
| `size` | `MantineSize` | `"sm"` | Controls the size of the radio and its label (`"xs"` `"sm"` `"md"` `"lg"` `"xl"`). |
| `color` | `MantineColor` | — | Theme color key or CSS color string for the checked state background. |
| `radius` | `MantineRadius \| number` | — | Border-radius of the radio circle. |
| `icon` | `FC<RadioIconProps>` | — | Replaces the default centered-dot icon inside the radio. |
| `iconColor` | `MantineColor` | — | Color of the icon inside the radio. |
| `autoContrast` | `boolean` | — | When set, adjusts the icon color automatically to contrast with the `color` background. |
| `rootRef` | `Ref<HTMLDivElement>` | — | Ref forwarded to the root wrapper element. |
| `wrapperProps` | `React.ComponentProps<"div">` | — | Additional props spread onto the root wrapper `<div>`. |
| `withErrorStyles` | `boolean` | — | When set, applies error styles when `error` is provided. |

### `RadioGroup`

`RadioGroupProps` extends Mantine's `RadioGroupProps`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `children` | `React.ReactNode` | **required** | `Radio` components and any layout elements. |
| `name` | `string` | auto-generated | Shared `name` attribute forwarded to all child `Radio` inputs. |
| `label` | `React.ReactNode` | — | Group label rendered above the options; sets `aria-labelledby` on the group wrapper. |
| `description` | `React.ReactNode` | — | Group-level description displayed below the label. |
| `error` | `React.ReactNode` | — | Group-level error message. |
| `value` | `Primitive \| null` | — | Controlled selected value. |
| `defaultValue` | `Primitive \| null` | — | Initial selected value (uncontrolled). |
| `onChange` | `(value: Value) => void` | — | Called whenever the selected radio changes. |
| `disabled` | `boolean` | — | Disables all child radio inputs. |
| `required` | `boolean` | — | Marks the group as required and adds a red asterisk. |
| `withAsterisk` | `boolean` | — | Adds the required asterisk without setting the `required` attribute. |
| `readOnly` | `boolean` | — | Prevents value from changing. |
| `size` | `MantineSize` | — | Controls size of the `Input.Wrapper` around the group. |
| `id` | `string` | auto-generated | Base id used to generate `aria-` attribute connections. |
| `labelElement` | `"div" \| "label"` | — | Root element for the group label. |
| `labelProps` | `InputLabelProps` | — | Props forwarded to the label element. |
| `descriptionProps` | `InputDescriptionProps` | — | Props forwarded to the description element. |
| `errorProps` | `InputErrorProps` | — | Props forwarded to the error element. |
| `inputContainer` | `(children: ReactNode) => ReactNode` | — | Render function that wraps the input group (useful for tooltips). |
| `inputWrapperOrder` | `("input" \| "label" \| "description" \| "error")[]` | — | Controls order and visibility of wrapper elements. |
| `wrapperProps` | `React.ComponentProps<"div">` | — | Props spread onto the root `Input.Wrapper` div. |

***

## Interaction states

| State | Description |
| - | - |
| `default` | Unchecked, no user interaction. |
| `hover` | Cursor moves over the radio or label. |
| `focus` | Keyboard focus ring appears on the radio input (`:focus-visible`). |
| `checked` | Radio is selected; the inner dot and ring fill with the active color. |
| `disabled` | Input and label are greyed out; all pointer events are suppressed. |

***

## Accessibility

* Each `Radio` renders a native `<input type="radio">`, which provides full browser and assistive-technology support out of the box.
* Wrapping radios in `RadioGroup` adds `role="radiogroup"` and `aria-labelledby` pointing at the group label.
* Arrow keys move focus between options within the group. `Tab` moves focus out of the group.
* Always provide either a `label` prop or an `aria-label`/`aria-labelledby` attribute on each `Radio`. An unlabeled input will not be announced correctly by screen readers.
* When you use `RadioGroup`, set the `label` prop on the group — it becomes the accessible name for the entire `radiogroup` region.

```tsx theme={null}
// ✅ Labeled via prop
<Radio value="opt" label="Option A" />

// ✅ Labeled via aria-label (when visual label is not needed)
<Radio value="opt" aria-label="Option A" />

// ❌ No label — screen readers cannot announce this radio
<Radio value="opt" />
```

***

> [!WARNING]
>
> **Draft status.** The `Radio` and `RadioGroup` components are currently **Draft**. Verify that `role="radiogroup"` is correctly emitted on the `RadioGroup` wrapper and that arrow-key navigation between options works as expected in your target browsers before shipping to production.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.