> Leaf UI 0.6.0 · Package: @ifhover/leaf-ui · Source: b30c3d3a8fa9c5e15d0d0522cebfbd33f60c6b06
> Browser documentation: https://ifhover.github.io/leaf-ui/v/0.6.0/components/checkbox.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.

# Checkbox 复选框

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

## 基础用法


接收项目动态接收每周摘要暂不可用已锁定

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/checkbox/basic.tsx"
import { Checkbox, Space } from '@ifhover/leaf-ui';

export function CheckboxBasic() {
  return (
    <Space wrap>
      <Checkbox defaultChecked>接收项目动态</Checkbox>
      <Checkbox>接收每周摘要</Checkbox>
      <Checkbox disabled>暂不可用</Checkbox>
      <Checkbox disabled defaultChecked>
        已锁定
      </Checkbox>
    </Space>
  );
}
```

展开代码

## 全选与半选

indeterminate 表示部分选中，用于汇总子选项。它只影响显示与辅助技术识别；全选和提交值由 checked 决定。


订阅全部

设计更新产品动态每周摘要

已选择 1 项

check-all.tsx

复制代码

```tsx lineNumbers file="../../src/examples/checkbox/check-all.tsx"
import { Checkbox, Flex, Space, 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 (
    <Space direction="vertical" align="stretch">
      <Checkbox
        checked={allChecked}
        indeterminate={selected.length > 0 && !allChecked}
        onChange={(event) => setSelected(event.target.checked ? [...options] : [])}
      >
        订阅全部
      </Checkbox>
      <Flex gap="md" align="center" wrap justify="center">
        {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">已选择 {selected.length} 项</Text>
    </Space>
  );
}
```

展开代码

## 扩展用法


选择 1–2 个兴趣设计开发摄影

extensions.tsx

复制代码

```tsx lineNumbers file="../../src/examples/checkbox/extensions.tsx"
import { CheckboxGroup } from '@ifhover/leaf-ui';

export function ExtensionDemo() {
  return (
    <CheckboxGroup
      legend="选择 1–2 个兴趣"
      options={['设计', '开发', '摄影']}
      defaultValue={['设计']}
      minCount={1}
      maxCount={2}
    />
  );
}
```

展开代码

## 卡片选项

卡片整块可点击，适合包含图标和说明的选项。


连接服务邮件读取与整理邮件云端文件查找与整理文件团队沟通当前不可用全部服务部分服务已启用

surfaces.tsx

复制代码

```tsx lineNumbers file="../../src/examples/checkbox/surfaces.tsx"
import { Checkbox, CheckboxGroup, Space } from '@ifhover/leaf-ui';

import { HardDrive, Mail, MessageSquare } from 'lucide-react';

export function CheckboxCards() {
  
  return (
    <Space direction="vertical" align="stretch">
      <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,
          },
        ]}
      />
      <Checkbox
        variant="card"
        indeterminate
        description={'部分服务已启用'}
      >
        {'全部服务'}
      </Checkbox>
    </Space>
  );
}
```

展开代码

## 成组选项

相关选项共用边框和行分隔线；状态标签放在右侧。


邮件权限读取邮件mail.readonly发送邮件mail.send需要审批删除邮件mail.modify策略限制

surfaces.tsx

复制代码

```tsx lineNumbers file="../../src/examples/checkbox/surfaces.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,
        },
      ]}
    />
  );
}
```

展开代码

## Checkbox API

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

name、value、required、form 等原生属性可直接使用。只有已勾选且未禁用的复选框参与原生表单提交。没有文字标签时必须提供 aria-label。className 与 style 作用于标签容器。

## 类型

可导入 [`CheckboxProps`](#checkbox-api) 定义组件属性，或使用尺寸类型：

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

## 扩展类型

```ts
import type { CheckboxGroupProps, CheckboxOption } from '@ifhover/leaf-ui';
```

## CheckboxGroupProps API

| 属性             | 类型                                                                 | 默认值            | 说明                   |
| -------------- | ------------------------------------------------------------------ | -------------- | -------------------- |
| `options`      | `readonly (`[`CheckboxOption`](#checkboxoption-api)` \| string)[]` | 必填             | 必需。可用选项              |
| `value`        | `readonly string[]`                                                | —              | 受控值                  |
| `defaultValue` | `readonly string[]`                                                | `[]`           | 初始值；非受控表单 reset 时恢复  |
| `onChange`     | `(values: string[]) => void`                                       | —              | 值变化回调                |
| `legend`       | `ReactNode`                                                        | —              | 字段组名称                |
| `size`         | `'sm' \| 'md' \| 'lg'`                                             | —              | 尺寸或间距预设              |
| `variant`      | `'plain' \| 'card' \| 'list'`                                      | `'plain'`      | 普通排列、卡片网格或带分隔线的成组列表。 |
| `minCount`     | `number`                                                           | `0`            | 最少勾选数量               |
| `maxCount`     | `number`                                                           | `Infinity`     | 最多勾选或展示数量            |
| `required`     | `boolean`                                                          | —              | 要求整体值非空，复合控件只校验一次。   |
| `direction`    | `'horizontal' \| 'vertical'`                                       | `'horizontal'` | 排列方向或移动方向            |

## CheckboxOption API

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

## 外观与丰富内容

Checkbox 的 variant="card" 让标签整体成为可点击卡片；CheckboxGroup 的 variant="card" 自动排列卡片，variant="list" 使用成组列表。description 与 extra 会作为辅助描述，icon 为装饰内容。extra 适合状态标签，不应包含按钮或链接。原生 name、value、form、表单重置与键盘操作保持可用。