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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/radio.md.

Radio 单选框

从一组选项中选择一项。

基础用法

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

选择项目外观
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
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
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
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
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'普通选项或整块可点击的卡片选项。
descriptionReactNode—补充说明。
iconReactNode—图标内容。
extraReactNode—补充状态文字或标签;不要放置交互控件。
checkedboolean—受控的选中状态。
defaultCheckedboolean—非受控模式的初始选中状态。
valuestring | number | readonly string[]—该单选框在表单中提交的值,不是选中状态;选中状态使用 checked。
namestring—原生 FormData 中的字段名。
onChangeChangeEventHandler<HTMLInputElement>—从 event.target.value 读取所选值。
disabledbooleanfalse禁用交互。
requiredbooleanfalse要求同名的单选框中至少选中一项。
childrenReactNode—可点击的选项标签。
refRef<HTMLInputElement>—单选框引用

RadioGroup API

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

属性类型默认值说明
optionsreadonly RadioOption[]必填选项列表
valuestring—受控的选中项 value;省略时使用内部非受控值。
defaultValuestring—非受控模式的初始选中值;支持表单重置。
namestring自动生成同组的字段名;提交表单时建议指定
labelReactNode—分组名称
size'sm' | 'md' | 'lg''md'同组控件尺寸
variant'plain' | 'card' | 'list''plain'普通排列、卡片网格或带分隔线的成组列表。
direction'horizontal' | 'vertical''horizontal'排列方向
requiredbooleanfalse要求整体值非空,复合控件只校验一次。
onChangeChangeEventHandler<HTMLInputElement>—从 event.target.value 读取所选值
disabledbooleanfalse禁用交互。
refRef<HTMLFieldSetElement>—分组引用

RadioOption

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

属性类型默认值说明
labelReactNode必填选项的显示内容。
descriptionReactNode—选项下方的补充说明。
iconReactNode—选项前的图标内容。
extraReactNode—补充状态文字或标签;不要放置交互控件。
valuestring必填选项值;同一组内应唯一。
disabledbooleanfalse禁用该选项。