> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/radio.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# Radio

Choose one option from a group.


## Basic usage

Define choices with `RadioGroup.options`. Give the group a name with `label`, `aria-label` or `aria-labelledby`. Selected borders use the theme color and pressing keeps the control size unchanged; the selection dot uses a 300ms transition by default.


Choose appearanceLightDarkSystem

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/radio/basic.tsx"
import { RadioGroup } from '@ifhover/leaf-ui';

export function RadioBasic() {
  return (
    <RadioGroup
      label="Choose appearance"
      name="appearance"
      defaultValue="light"
      options={[
        { label: 'Light', value: 'light' },
        { label: 'Dark', value: 'dark' },
        { label: 'System', value: 'system' },
      ]}
    />
  );
}
```

Expand code


## Examples

### Controlled selection

Control the selected string with `value`, and read `event.target.value` in `onChange`.


Notification frequencyDailyWeeklyImportant messages onlySelected: daily

controlled.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/radio/controlled.tsx"
import { Flex, RadioGroup, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function RadioControlled() {
  const [value, setValue] = useState('daily');
  return (
    <Flex direction="column" gap="md" align="start">
      <RadioGroup
        label="Notification frequency"
        value={value}
        onChange={(event) => setValue(event.target.value)}
        options={[
          { label: 'Daily', value: 'daily' },
          { label: 'Weekly', value: 'weekly' },
          { label: 'Important messages only', value: 'important' },
        ]}
      />
      <Text tone="muted" role="status">
        Selected: {value}
      </Text>
    </Flex>
  );
}
```

Expand code

### Vertical layout

Set `direction="vertical"` for a vertical group.


Notification frequencyDailyWeeklyImportant messages only

vertical.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/radio/vertical.tsx"
import { RadioGroup } from '@ifhover/leaf-ui';

export function RadioVertical() {
  return (
    <RadioGroup
      label="Notification frequency"
      direction="vertical"
      defaultValue="daily"
      options={[
        { label: 'Daily', value: 'daily' },
        { label: 'Weekly', value: 'weekly' },
        { label: 'Important messages only', value: 'important' },
      ]}
    />
  );
}
```

Expand code

[](#)
### Card choices

Set `variant="card"` for choices with icons and descriptions.


Backup methodCloud backupSync across your devicesLocal backupKeep data on this device

surfaces.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/radio/surfaces.tsx"
import { RadioGroup } from '@ifhover/leaf-ui';
import { Cloud, HardDrive } from 'lucide-react';

export function RadioCards() {
  return (
    <RadioGroup
      variant="card"
      label={'Backup method'}
      defaultValue="cloud"
      options={[
        {
          value: 'cloud',
          label: 'Cloud backup',
          description: 'Sync across your devices',
          icon: <Cloud />,
        },
        {
          value: 'local',
          label: 'Local backup',
          description: 'Keep data on this device',
          icon: <HardDrive />,
        },
      ]}
    />
  );
}
```

Expand code

### Grouped choices

Use `variant="list"` for a shared list. Keep `extra` to non-interactive status, not buttons or links.


Access policyRead onlyChanges require approvalRecommendedApprove every requestAsk the owner to approve every action

list.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/radio/list.tsx"
import { RadioGroup, Tag } from '@ifhover/leaf-ui';

export function RadioList() {
  return (
    <RadioGroup
      variant="list"
      label={'Access policy'}
      defaultValue="readonly"
      options={[
        {
          value: 'readonly',
          label: 'Read only',
          description: 'Changes require approval',
          extra: (
            <Tag color="success" size="sm">
              {'Recommended'}
            </Tag>
          ),
        },
        {
          value: 'review',
          label: 'Approve every request',
          description: 'Ask the owner to approve every action',
        },
      ]}
    />
  );
}
```

Expand code

#### Forms and reset

Set `name` to submit the selected option's `value`. Unselected and disabled options are not submitted. When composing individual `Radio` controls, use the same `name` and unique values for each group.

Uncontrolled groups return to `defaultValue` on form reset. For controlled groups, reset application state as well.


## API

### Radio API

Configure selection, submission value and disabled state for an individual radio.

Individual `Radio` controls support native radio attributes. `className` and `style` apply to the label container.

| Property         | Type                                    | Default   | Description                                                                          |
| ---------------- | --------------------------------------- | --------- | ------------------------------------------------------------------------------------ |
| `size`           | `'sm' \| 'md' \| 'lg'`                  | `'md'`    | Control size                                                                         |
| `variant`        | `'plain' \| 'card'`                     | `'plain'` | Plain choice or a card with a full clickable surface.                                |
| `description`    | `ReactNode`                             | —         | Supporting text below the option.                                                    |
| `icon`           | `ReactNode`                             | —         | Leading icon content for the option.                                                 |
| `extra`          | `ReactNode`                             | —         | Supplementary status or tags; avoid interactive controls.                            |
| `checked`        | `boolean`                               | —         | Controlled checked state.                                                            |
| `defaultChecked` | `boolean`                               | —         | Initial checked state for uncontrolled usage.                                        |
| `value`          | `string \| number \| readonly string[]` | —         | The value submitted by this radio, not its checked state; use checked for selection. |
| `name`           | `string`                                | —         | Field name in native FormData.                                                       |
| `onChange`       | `ChangeEventHandler<HTMLInputElement>`  | —         | Read the selected value from event.target.value.                                     |
| `disabled`       | `boolean`                               | `false`   | Disable interaction.                                                                 |
| `required`       | `boolean`                               | `false`   | Require a selection among radios with the same name.                                 |
| `children`       | `ReactNode`                             | —         | Clickable choice label.                                                              |
| `ref`            | `Ref<HTMLInputElement>`                 | —         | DOM reference                                                                        |

### RadioGroup API

Manage the selected value and layout of a group of radio options.

| Property       | Type                                         | Default        | Description                                                                      |
| -------------- | -------------------------------------------- | -------------- | -------------------------------------------------------------------------------- |
| `options`      | `readonly `[`RadioOption`](#radiooption)`[]` | Required       | Options                                                                          |
| `value`        | `string`                                     | —              | Controlled selected value; the internal uncontrolled value is used when omitted. |
| `defaultValue` | `string`                                     | —              | Initial selected value for uncontrolled usage; native form reset is supported.   |
| `name`         | `string`                                     | Generated      | Shared field name; specify it for form submission                                |
| `label`        | `ReactNode`                                  | —              | Group name                                                                       |
| `size`         | `'sm' \| 'md' \| 'lg'`                       | `'md'`         | Control size                                                                     |
| `variant`      | `'plain' \| 'card' \| 'list'`                | `'plain'`      | Plain choices, a card grid or a list with shared borders and dividers.           |
| `direction`    | `'horizontal' \| 'vertical'`                 | `'horizontal'` | Layout direction                                                                 |
| `required`     | `boolean`                                    | `false`        | Require a non-empty value; compound controls validate once.                      |
| `onChange`     | `ChangeEventHandler<HTMLInputElement>`       | —              | Read event.target.value                                                          |
| `disabled`     | `boolean`                                    | `false`        | Disable interaction.                                                             |
| `ref`          | `Ref<HTMLFieldSetElement>`                   | —              | DOM reference                                                                    |

### RadioOption

One group option containing its submission value and displayed content.

| Property      | Type        | Default  | Description                                               |
| ------------- | ----------- | -------- | --------------------------------------------------------- |
| `label`       | `ReactNode` | Required | Visible option content.                                   |
| `description` | `ReactNode` | —        | Supporting text below the option.                         |
| `icon`        | `ReactNode` | —        | Leading icon content for the option.                      |
| `extra`       | `ReactNode` | —        | Supplementary status or tags; avoid interactive controls. |
| `value`       | `string`    | Required | Option value; unique within the group.                    |
| `disabled`    | `boolean`   | `false`  | Disable the option.                                       |
