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

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

# Radio

Choose one option from a group.

## Examples

RadioGroup builds options and supplies a group name. Provide label, aria-label or aria-labelledby. Give the group a name for form submission. Read event.target.value in onChange. Individual Radio controls with the same name form a native group.


Choose appearanceLightDarkSystemCustom (unavailable)

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' },
        { label: 'Custom (unavailable)', value: 'custom', disabled: true },
      ]}
    />
  );
}
```

Expand code


Notification frequencyDailyWeeklyImportant messages onlySelected:daily

controlled.tsx

Copy code

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

import { useState } from 'react';

export function RadioControlled() {
  const [value, setValue] = useState('daily');
  return (
    <Space direction="vertical" align="stretch">
      <RadioGroup
        label="Notification frequency"
        direction="vertical"
        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">Selected:{value}</Text>
    </Space>
  );
}
```

Expand code

## Card choices

Use icons and descriptions to help people choose a plan.


Backup methodCloud backupSync across your devicesLocal backupKeep data on this device

surfaces.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/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

Group choices into one list while retaining native arrow-key navigation.


Access policyRead-only accessAllow reading and require approval for changesRecommendedApprove every requestAsk the owner to approve every action

surfaces.tsx

Copy code

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

import { ShieldCheck } from 'lucide-react';

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

Expand code

## RadioGroup API

| Property       | Type                                         | Default        | Description                                                            |
| -------------- | -------------------------------------------- | -------------- | ---------------------------------------------------------------------- |
| `options`      | `readonly `[`RadioOption`](#radiooption)`[]` | Required       | Required. Options                                                      |
| `value`        | `string`                                     | —              | Controlled value / initial uncontrolled value                          |
| `defaultValue` | `string`                                     | —              | Controlled value / initial uncontrolled value                          |
| `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                                                          |

## Radio API

| 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`                            | —         | Additional description.                                     |
| `icon`           | `ReactNode`                            | —         | Icon content.                                               |
| `extra`          | `ReactNode`                            | —         | Supplementary status or tags; avoid interactive controls.   |
| `checked`        | `boolean`                              | —         | Controlled checked state / initial checked state            |
| `defaultChecked` | `boolean`                              | —         | Controlled checked state / initial checked state            |
| `value`          | `string`                               | Required  | Controlled value.                                           |
| `name`           | `string`                               | —         | Field name in native FormData.                              |
| `onChange`       | `ChangeEventHandler<HTMLInputElement>` | —         | Called when the value changes.                              |
| `disabled`       | `boolean`                              | `false`   | Disable interaction.                                        |
| `required`       | `boolean`                              | `false`   | Require a non-empty value; compound controls validate once. |
| `children`       | `ReactNode`                            | —         | Content, or child nodes for hierarchical records.           |
| `ref`            | `Ref<HTMLInputElement>`                | —         | DOM reference                                               |

### RadioOption

| Property   | Type      | Default  | Description                    |
| ---------- | --------- | -------- | ------------------------------ |
| `label`    | `string`  | Required | Option label                   |
| `value`    | `string`  | Required | Value; unique within the group |
| `disabled` | `boolean` | `false`  | Disable the option             |

## Types

Import RadioProps to describe component props. Option types in the API table link to their detailed fields above.

```ts
import type { RadioProps, RadioGroupProps, RadioOption } from '@ifhover/leaf-ui';
```

## Forms and localization

Use name to include values in FormData. Uncontrolled fields follow form reset; reset controlled values in application state. Place controls in [FormField](https://ifhover.github.io/leaf-ui/v/0.6.0/en/components/form.md#formfield-api) for labels, help and errors. [ConfigProvider](https://ifhover.github.io/leaf-ui/v/0.6.0/en/components/config-provider.md) supplies regional themes and translated built-in UI. Application labels and options are your responsibility.

## Surfaces and rich content

Radio and RadioGroup support icons, descriptions and status tags. RadioGroup variant="card" arranges cards; variant="list" creates grouped rows. description and extra are accessible descriptions; avoid buttons or links in extra. Groups retain native arrow keys, disabled-option skipping and form submission.

## RadioOption

| Property      | Type        | Default | Description                                               |
| ------------- | ----------- | ------- | --------------------------------------------------------- |
| `label`       | `ReactNode` | —       | Required. Visible label or content.                       |
| `description` | `ReactNode` | —       | Additional description.                                   |
| `icon`        | `ReactNode` | —       | Icon content.                                             |
| `extra`       | `ReactNode` | —       | Supplementary status or tags; avoid interactive controls. |
| `value`       | `string`    | —       | Required. Controlled value.                               |
| `disabled`    | `boolean`   | —       | Disable interaction.                                      |