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/checkbox.md.

Checkbox 复选框

选择一个或多个选项,或确认某项设置。

基础用法

通过文字内容提供选项名称,用户可独立切换选中状态。

basic.tsx
import { Checkbox } from '@ifhover/leaf-ui';

export function CheckboxBasic() {
  return <Checkbox>接收项目动态</Checkbox>;
}

受控使用时传入 checked,在 onChange 中从 event.target.checked 读取布尔值。

示例

选项组

使用 CheckboxGroup 管理多个选项。与单个复选框不同,组的 value 和 onChange 使用字符串数组。

订阅内容
group.tsx
import { CheckboxGroup } from '@ifhover/leaf-ui';

export function CheckboxGroupDemo() {
  return (
    <CheckboxGroup
      legend="订阅内容"
      defaultValue={['design']}
      options={[
        { value: 'design', label: '设计更新' },
        { value: 'product', label: '产品动态' },
        { value: 'weekly', label: '每周摘要' },
      ]}
    />
  );
}

禁用状态

设置 disabled 后,选中状态仍可显示,但不能由用户切换。

未选中
已选中
disabled.tsx
import { Checkbox, Flex, Grid, Text } from '@ifhover/leaf-ui';

export function CheckboxDisabled() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      <Text tone="muted">未选中</Text>
      <Flex align="center" wrap>
        <Checkbox disabled>接收项目动态</Checkbox>
      </Flex>
      <Text tone="muted">已选中</Text>
      <Flex align="center" wrap>
        <Checkbox disabled defaultChecked>
          接收项目动态
        </Checkbox>
      </Flex>
    </Grid>
  );
}

全选与半选

indeterminate 表示部分选中,不改变 checked 或提交值。子选项和全选逻辑由应用维护。

已选择 1 项
check-all.tsx
import { Checkbox, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const options = ['设计更新', '产品动态', '每周摘要'];

export function CheckboxCheckAll() {
  const [selected, setSelected] = useState<string[]>(['设计更新']);
  const allChecked = selected.length === options.length;
  return (
    <Flex direction="column" gap="md" align="start">
      <Checkbox
        checked={allChecked}
        indeterminate={selected.length > 0 && !allChecked}
        onChange={(event) => setSelected(event.target.checked ? [...options] : [])}
      >
        订阅全部
      </Checkbox>
      <Flex direction="column" gap="sm" align="start">
        {options.map((option) => (
          <Checkbox
            key={option}
            checked={selected.includes(option)}
            onChange={(event) =>
              setSelected(
                event.target.checked
                  ? [...selected, option]
                  : selected.filter((item) => item !== option),
              )
            }
          >
            {option}
          </Checkbox>
        ))}
      </Flex>
      <Text tone="muted" role="status">
        已选择 {selected.length} 项
      </Text>
    </Flex>
  );
}

卡片选项

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

连接服务
surfaces.tsx
import { CheckboxGroup } from '@ifhover/leaf-ui';
import { HardDrive, Mail, MessageSquare } from 'lucide-react';

export function CheckboxCards() {
  return (
    <CheckboxGroup
      variant="card"
      legend={'连接服务'}
      defaultValue={['mail']}
      options={[
        {
          value: 'mail',
          label: '邮件',
          description: '读取与整理邮件',
          icon: <Mail />,
        },
        {
          value: 'drive',
          label: '云端文件',
          description: '查找与整理文件',
          icon: <HardDrive />,
        },
        {
          value: 'chat',
          label: '团队沟通',
          description: '当前不可用',
          icon: <MessageSquare />,
          disabled: true,
        },
      ]}
    />
  );
}

成组选项

使用 CheckboxGroup variant="list" 展示成组列表。extra 只放状态标签等非交互内容,不放按钮或链接。

邮件权限
list.tsx
import { CheckboxGroup, Tag } from '@ifhover/leaf-ui';

export function CheckboxList() {
  return (
    <CheckboxGroup
      variant="list"
      legend={'邮件权限'}
      defaultValue={['read']}
      options={[
        { value: 'read', label: '读取邮件', description: 'mail.readonly' },
        {
          value: 'send',
          label: '发送邮件',
          description: 'mail.send',
          extra: (
            <Tag color="warning" size="sm">
              {'需审批'}
            </Tag>
          ),
        },
        {
          value: 'delete',
          label: '删除邮件',
          description: 'mail.modify',
          extra: <Tag size="sm">{'已限制'}</Tag>,
          disabled: true,
        },
      ]}
    />
  );
}

表单提交与重置

设置 name 后,只有已勾选且未禁用的选项参与提交。选项组按同一个字段名提交多个值,可用 FormData.getAll(name) 读取。

非受控字段在表单重置时恢复 defaultChecked 或 defaultValue;受控字段需要同步重置应用状态。

API

Checkbox API

支持 name、value、required、form 等原生 checkbox 属性。没有文字标签时提供 aria-label;className 和 style 作用于标签容器。

属性类型默认值说明
size'sm' | 'md' | 'lg''md'复选框尺寸
variant'plain' | 'card''plain'普通选项或整块可点击的卡片选项。
descriptionReactNode—补充说明。
iconReactNode—图标内容。
extraReactNode—补充状态文字或标签;不要放置交互控件。
indeterminatebooleanfalse半选状态
checkedboolean—受控的勾选状态。
defaultCheckedboolean—非受控模式的初始勾选状态。
onChangeChangeEventHandler<HTMLInputElement>—从 event.target.checked 读取选中状态。
disabledbooleanfalse禁用交互。
childrenReactNode—可点击的选项标签。
refRef<HTMLInputElement>—复选框引用

CheckboxGroupProps API

统一管理一组选项和值的参数。

属性类型默认值说明
optionsreadonly (CheckboxOption | string)[]必填可用选项
valuereadonly string[]—受控值
defaultValuereadonly string[][]初始值;非受控表单 reset 时恢复
onChange(values: string[]) => void—值变化回调
legendReactNode—字段组名称
size'sm' | 'md' | 'lg'—复选框尺寸。
variant'plain' | 'card' | 'list''plain'普通排列、卡片网格或带分隔线的成组列表。
requiredboolean—要求整体值非空,复合控件只校验一次。
direction'horizontal' | 'vertical''horizontal'选项的排列方向。

CheckboxOption API

通过复选框组 options 提供的选项数据。

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