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

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

# Radio 单选框

用于从一组选项中选择一项。

## 分组选项

通过 `options` 设置选项，`label` 为选项分组提供名称。


选择项目外观浅色深色跟随系统自定义（暂不可用）

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' },
        { label: '自定义（暂不可用）', value: 'custom', disabled: true },
      ]}
    />
  );
}
```

展开代码

## 受控与纵向排列

通过 value / onChange 管理选择结果，direction="vertical" 设置纵向排列。


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

controlled.tsx

复制代码

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

展开代码

## 卡片选项

用图标和说明帮助用户选择一个方案。


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

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 />,
        },
      ]}
    />
  );
}
```

展开代码

## 成组选项

同组选项放在一个列表中，保留原生方向键操作。


访问策略只读访问允许读取，保留变更审批推荐每次审批每次操作都由负责人确认

surfaces.tsx

复制代码

```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={'访问策略'}
      defaultValue="readonly"
      options={[
        {
          value: 'readonly',
          label: '只读访问',
          description: '允许读取，保留变更审批',
          icon: <ShieldCheck />,
          extra: (
            <Tag color="success" size="sm">
              {'推荐'}
            </Tag>
          ),
        },
        {
          value: 'review',
          label: '每次审批',
          description: '每次操作都由负责人确认',
        },
      ]}
    />
  );
}
```

展开代码

## RadioGroup API

| 属性             | 类型                                           | 默认值            | 说明                           |
| -------------- | -------------------------------------------- | -------------- | ---------------------------- |
| `options`      | `readonly `[`RadioOption`](#radiooption)`[]` | 必填             | 必需。选项列表                      |
| `value`        | `string`                                     | —              | 受控值 / 非受控初始值                 |
| `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>`                   | —              | 分组引用                         |

## Radio API

| 属性               | 类型                                      | 默认值       | 说明                  |
| ---------------- | --------------------------------------- | --------- | ------------------- |
| `size`           | `'sm' \| 'md' \| 'lg'`                  | `'md'`    | 单选框尺寸               |
| `variant`        | `'plain' \| 'card'`                     | `'plain'` | 普通选项或整块可点击的卡片选项。    |
| `description`    | `ReactNode`                             | —         | 补充说明。               |
| `icon`           | `ReactNode`                             | —         | 图标内容。               |
| `extra`          | `ReactNode`                             | —         | 补充状态文字或标签；不要放置交互控件。 |
| `checked`        | `boolean`                               | —         | 受控选中状态 / 非受控初始状态    |
| `defaultChecked` | `boolean`                               | —         | 受控选中状态 / 非受控初始状态    |
| `value`          | `string \| number \| readonly string[]` | —         | 受控值。                |
| `name`           | `string`                                | —         | 原生 FormData 中的字段名。  |
| `onChange`       | `ChangeEventHandler<HTMLInputElement>`  | —         | 值发生变化时调用。           |
| `disabled`       | `boolean`                               | `false`   | 禁用交互。               |
| `required`       | `boolean`                               | `false`   | 要求整体值非空，复合控件只校验一次。  |
| `children`       | `ReactNode`                             | —         | 子内容；嵌套数据类型表示子节点。    |
| `ref`            | `Ref<HTMLInputElement>`                 | —         | 单选框引用               |

支持其他 radio 属性。`className` 和 `style` 作用于标签容器。

RadioGroup 的 label、aria-label 或 aria-labelledby 应至少提供一种分组名称。选项 label 与 value 建议保持稳定；value 使用不重复的字符串。

## 类型

[`RadioProps`](#radio-api) 和 [`RadioGroupProps`](#radiogroup-api) 用于定义组件属性。单独组装选项列表时，可以使用 [`RadioOption`](#radiooption)：

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

const options: RadioOption[] = [
  { label: '浅色', value: 'light' },
  { label: '深色', value: 'dark' },
];
```

### RadioOption

| 属性         | 类型        | 默认值     | 说明         |
| ---------- | --------- | ------- | ---------- |
| `label`    | `string`  | 必填      | 选项文字       |
| `value`    | `string`  | 必填      | 选项值，同组内应唯一 |
| `disabled` | `boolean` | `false` | 禁用该选项      |

## 外观与丰富内容

Radio 和 RadioGroup 支持图标、补充说明与状态标签。RadioGroup 的 variant="card" 自动排列卡片，variant="list" 使用成组列表。description 与 extra 作为辅助描述，extra 不应包含按钮或链接。单选组保留方向键切换、禁用选项跳过与原生表单提交。

## RadioOption

| 属性            | 类型          | 默认值 | 说明                  |
| ------------- | ----------- | --- | ------------------- |
| `label`       | `ReactNode` | —   | 必需。展示文字或内容。         |
| `description` | `ReactNode` | —   | 补充说明。               |
| `icon`        | `ReactNode` | —   | 图标内容。               |
| `extra`       | `ReactNode` | —   | 补充状态文字或标签；不要放置交互控件。 |
| `value`       | `string`    | —   | 必需。受控值。             |
| `disabled`    | `boolean`   | —   | 禁用交互。               |