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

# Checkbox 复选框

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


## 基础用法

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


接收项目动态

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/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

复制代码

```tsx lineNumbers file="../../src/examples/checkbox/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

复制代码

```tsx lineNumbers file="../../src/examples/checkbox/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

复制代码

```tsx lineNumbers file="../../src/examples/checkbox/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

复制代码

```tsx lineNumbers file="../../src/examples/checkbox/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` 只放状态标签等非交互内容，不放按钮或链接。


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

list.tsx

复制代码

```tsx lineNumbers file="../../src/examples/checkbox/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'` | 普通选项或整块可点击的卡片选项。               |
| `description`    | `ReactNode`                            | —         | 补充说明。                          |
| `icon`           | `ReactNode`                            | —         | 图标内容。                          |
| `extra`          | `ReactNode`                            | —         | 补充状态文字或标签；不要放置交互控件。            |
| `indeterminate`  | `boolean`                              | `false`   | 半选状态                           |
| `checked`        | `boolean`                              | —         | 受控的勾选状态。                       |
| `defaultChecked` | `boolean`                              | —         | 非受控模式的初始勾选状态。                  |
| `onChange`       | `ChangeEventHandler<HTMLInputElement>` | —         | 从 event.target.checked 读取选中状态。 |
| `disabled`       | `boolean`                              | `false`   | 禁用交互。                          |
| `children`       | `ReactNode`                            | —         | 可点击的选项标签。                      |
| `ref`            | `Ref<HTMLInputElement>`                | —         | 复选框引用                          |

### 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'`      | 普通排列、卡片网格或带分隔线的成组列表。 |
| `required`     | `boolean`                                                          | —              | 要求整体值非空，复合控件只校验一次。   |
| `direction`    | `'horizontal' \| 'vertical'`                                       | `'horizontal'` | 选项的排列方向。             |

### CheckboxOption API

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

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