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

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

# Radio 单选框

从一组选项中选择一项。


## 基础用法

通过 `RadioGroup.options` 定义选项，使用 `label`、`aria-label` 或 `aria-labelledby` 为分组提供名称。选中边框使用主题色，按下时保持控件尺寸；选中圆点默认以 300ms 过渡显示。


选择项目外观浅色深色跟随系统

basic.tsx

复制代码

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

export function RadioBasic() {
  return (
    <RadioGroup
      label="选择项目外观"
      name="appearance"
      defaultValue="light"
      options={[
        { label: '浅色', value: 'light' },
        { label: '深色', value: 'dark' },
        { label: '跟随系统', value: 'system' },
      ]}
    />
  );
}
```

展开代码


## 示例

### 受控选择

通过 `value` 控制选中的字符串，在 `onChange` 中读取 `event.target.value`。


提醒频率每天每周仅重要消息当前选择：daily

controlled.tsx

复制代码

```tsx lineNumbers file="../../src/examples/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="提醒频率"
        value={value}
        onChange={(event) => setValue(event.target.value)}
        options={[
          { label: '每天', value: 'daily' },
          { label: '每周', value: 'weekly' },
          { label: '仅重要消息', value: 'important' },
        ]}
      />
      <Text tone="muted" role="status">
        当前选择：{value}
      </Text>
    </Flex>
  );
}
```

展开代码

### 纵向排列

设置 `direction="vertical"` 纵向排列选项。


提醒频率每天每周仅重要消息

vertical.tsx

复制代码

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

export function RadioVertical() {
  return (
    <RadioGroup
      label="提醒频率"
      direction="vertical"
      defaultValue="daily"
      options={[
        { label: '每天', value: 'daily' },
        { label: '每周', value: 'weekly' },
        { label: '仅重要消息', value: 'important' },
      ]}
    />
  );
}
```

展开代码

[](#)
### 卡片选项

设置 `variant="card"`，展示包含图标和说明的选项。


备份方式云端备份在你的设备间同步本地备份保存在当前设备

surfaces.tsx

复制代码

```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={'备份方式'}
      defaultValue="cloud"
      options={[
        {
          value: 'cloud',
          label: '云端备份',
          description: '在你的设备间同步',
          icon: <Cloud />,
        },
        {
          value: 'local',
          label: '本地备份',
          description: '保存在当前设备',
          icon: <HardDrive />,
        },
      ]}
    />
  );
}
```

展开代码

### 成组选项

使用 `variant="list"` 展示成组列表。`extra` 只放非交互状态，不放按钮或链接。


访问策略只读访问变更需审批推荐每次审批每次操作都由负责人确认

list.tsx

复制代码

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

export function RadioList() {
  return (
    <RadioGroup
      variant="list"
      label={'访问策略'}
      defaultValue="readonly"
      options={[
        {
          value: 'readonly',
          label: '只读访问',
          description: '变更需审批',
          extra: (
            <Tag color="success" size="sm">
              {'推荐'}
            </Tag>
          ),
        },
        {
          value: 'review',
          label: '每次审批',
          description: '每次操作都由负责人确认',
        },
      ]}
    />
  );
}
```

展开代码

#### 表单提交与重置

通过 `name` 提交选中项的 `value`，未选中或禁用的选项不提交。单独组合 `Radio` 时，同组使用相同的 `name` 和互不重复的值。

非受控选项组在表单重置时恢复 `defaultValue`；受控组需要同步重置应用状态。


## API

### Radio API

配置单个单选框的选中状态、提交值和禁用状态。

单个 `Radio` 支持原生 radio 属性。`className` 和 `style` 作用于标签容器。

| 属性               | 类型                                      | 默认值       | 说明                                  |
| ---------------- | --------------------------------------- | --------- | ----------------------------------- |
| `size`           | `'sm' \| 'md' \| 'lg'`                  | `'md'`    | 单选框尺寸                               |
| `variant`        | `'plain' \| 'card'`                     | `'plain'` | 普通选项或整块可点击的卡片选项。                    |
| `description`    | `ReactNode`                             | —         | 补充说明。                               |
| `icon`           | `ReactNode`                             | —         | 图标内容。                               |
| `extra`          | `ReactNode`                             | —         | 补充状态文字或标签；不要放置交互控件。                 |
| `checked`        | `boolean`                               | —         | 受控的选中状态。                            |
| `defaultChecked` | `boolean`                               | —         | 非受控模式的初始选中状态。                       |
| `value`          | `string \| number \| readonly string[]` | —         | 该单选框在表单中提交的值，不是选中状态；选中状态使用 checked。 |
| `name`           | `string`                                | —         | 原生 FormData 中的字段名。                  |
| `onChange`       | `ChangeEventHandler<HTMLInputElement>`  | —         | 从 event.target.value 读取所选值。         |
| `disabled`       | `boolean`                               | `false`   | 禁用交互。                               |
| `required`       | `boolean`                               | `false`   | 要求同名的单选框中至少选中一项。                    |
| `children`       | `ReactNode`                             | —         | 可点击的选项标签。                           |
| `ref`            | `Ref<HTMLInputElement>`                 | —         | 单选框引用                               |

### RadioGroup API

管理一组选项的单选值和选项布局。

| 属性             | 类型                                           | 默认值            | 说明                           |
| -------------- | -------------------------------------------- | -------------- | ---------------------------- |
| `options`      | `readonly `[`RadioOption`](#radiooption)`[]` | 必填             | 选项列表                         |
| `value`        | `string`                                     | —              | 受控的选中项 value；省略时使用内部非受控值。    |
| `defaultValue` | `string`                                     | —              | 非受控模式的初始选中值；支持表单重置。          |
| `name`         | `string`                                     | 自动生成           | 同组的字段名；提交表单时建议指定             |
| `label`        | `ReactNode`                                  | —              | 分组名称                         |
| `size`         | `'sm' \| 'md' \| 'lg'`                       | `'md'`         | 同组控件尺寸                       |
| `variant`      | `'plain' \| 'card' \| 'list'`                | `'plain'`      | 普通排列、卡片网格或带分隔线的成组列表。         |
| `direction`    | `'horizontal' \| 'vertical'`                 | `'horizontal'` | 排列方向                         |
| `required`     | `boolean`                                    | `false`        | 要求整体值非空，复合控件只校验一次。           |
| `onChange`     | `ChangeEventHandler<HTMLInputElement>`       | —              | 从 `event.target.value` 读取所选值 |
| `disabled`     | `boolean`                                    | `false`        | 禁用交互。                        |
| `ref`          | `Ref<HTMLFieldSetElement>`                   | —              | 分组引用                         |

### RadioOption

传入选项组的单个选项，包含提交值与显示内容。

| 属性            | 类型          | 默认值     | 说明                  |
| ------------- | ----------- | ------- | ------------------- |
| `label`       | `ReactNode` | 必填      | 选项的显示内容。            |
| `description` | `ReactNode` | —       | 选项下方的补充说明。          |
| `icon`        | `ReactNode` | —       | 选项前的图标内容。           |
| `extra`       | `ReactNode` | —       | 补充状态文字或标签；不要放置交互控件。 |
| `value`       | `string`    | 必填      | 选项值；同一组内应唯一。        |
| `disabled`    | `boolean`   | `false` | 禁用该选项。              |
