---
title: 复选框 Checkbox
url: https://ui.zhaozimin.cn/components/checkbox/
markdown: https://ui.zhaozimin.cn/components/checkbox.md
group: 组件
origin: 提炼层组件（src/extracted），本仓库是唯一源头
source:
  - src/extracted/Checkbox.jsx  # https://ui.zhaozimin.cn/src/extracted/Checkbox.jsx
  - src/extracted/extracted.css  # https://ui.zhaozimin.cn/src/extracted/extracted.css
version: v0.2.0  # 设计系统版本，发布于 2026-09-23
scope: .zzm-v4   # 根节点必须带这个类，否则样式不生效
css: https://ui.zhaozimin.cn/v/0.2.0/zzm.css   # 锁版本地址，本仓库再改也不影响你
---

# 复选框 Checkbox

> 16px 方框、圆角 4。选中是墨底白勾，未选是 1.5px 描边；文字随状态从灰变深。

### 样张 · 点一下试试

React：

```jsx
import { useState } from 'react'
import { Checkbox } from './extracted/Checkbox.jsx'

export default function CheckboxDemo() {
  const [a, setA] = useState(true)
  const [b, setB] = useState(false)
  return (
    <div style={{ display: 'flex', gap: 24, flexWrap: 'wrap', alignItems: 'center' }}>
      <Checkbox checked={a} onChange={setA} label="已选复选框" />
      <Checkbox checked={b} onChange={setB} label="未选" />
    </div>
  )
}
```

HTML（构建时由上面的 React 渲染得到，可直接粘贴）：

```html
<div style="display: flex; gap: 24px; flex-wrap: wrap; align-items: center">
  <button
    type="button"
    role="checkbox"
    aria-checked="true"
    class="zzm-check"
    style="
      display: inline-flex;
      align-items: center;
      gap: 8px;
      padding: 0;
      border: 0;
      border-radius: 4px;
      background: transparent;
      font-family: inherit;
      cursor: pointer;
    "
  >
    <span
      style="
        width: 16px;
        height: 16px;
        border-radius: 4px;
        background: #1d1d1b;
        display: flex;
        align-items: center;
        justify-content: center;
        flex: none;
      "
    >
      <svg width="10" height="10" viewBox="0 0 12 12" aria-hidden="true">
        <path
          d="M2 6.2 L4.8 9 L10 3.4"
          stroke="#FFFFFF"
          stroke-width="1.8"
          fill="none"
          stroke-linecap="round"
          stroke-linejoin="round"
        ></path>
      </svg>
    </span>
    <span style="font-size: 12.5px; color: #3f3f3b">已选复选框</span>
  </button>
  <button
    type="button"
    role="checkbox"
    aria-checked="false"
    class="zzm-check"
    style="
      display: inline-flex;
      align-items: center;
      gap: 8px;
      padding: 0;
      border: 0;
      border-radius: 4px;
      background: transparent;
      font-family: inherit;
      cursor: pointer;
    "
  >
    <span
      style="
        width: 16px;
        height: 16px;
        border-radius: 4px;
        border: 1.5px solid rgba(0, 0, 0, 0.25);
        flex: none;
      "
    ></span>
    <span style="font-size: 12.5px; color: #8b8b85">未选</span>
  </button>
</div>
```

### 样张 · 两种状态

React：

```jsx
import { Checkbox } from './extracted/Checkbox.jsx'

export function States() {
  return (
    <>
      <Checkbox checked label="已选复选框" />
      <Checkbox label="未选" />
    </>
  )
}
```

HTML（构建时由上面的 React 渲染得到，可直接粘贴）：

```html
<button
  type="button"
  role="checkbox"
  aria-checked="true"
  class="zzm-check"
  style="
    display: inline-flex;
    align-items: center;
    gap: 8px;
    padding: 0;
    border: 0;
    border-radius: 4px;
    background: transparent;
    font-family: inherit;
    cursor: pointer;
  "
>
  <span
    style="
      width: 16px;
      height: 16px;
      border-radius: 4px;
      background: #1d1d1b;
      display: flex;
      align-items: center;
      justify-content: center;
      flex: none;
    "
  >
    <svg width="10" height="10" viewBox="0 0 12 12" aria-hidden="true">
      <path
        d="M2 6.2 L4.8 9 L10 3.4"
        stroke="#FFFFFF"
        stroke-width="1.8"
        fill="none"
        stroke-linecap="round"
        stroke-linejoin="round"
      ></path>
    </svg>
  </span>
  <span style="font-size: 12.5px; color: #3f3f3b">已选复选框</span>
</button>
<button
  type="button"
  role="checkbox"
  aria-checked="false"
  class="zzm-check"
  style="
    display: inline-flex;
    align-items: center;
    gap: 8px;
    padding: 0;
    border: 0;
    border-radius: 4px;
    background: transparent;
    font-family: inherit;
    cursor: pointer;
  "
>
  <span
    style="
      width: 16px;
      height: 16px;
      border-radius: 4px;
      border: 1.5px solid rgba(0, 0, 0, 0.25);
      flex: none;
    "
  ></span>
  <span style="font-size: 12.5px; color: #8b8b85">未选</span>
</button>
```

## 属性

| 属性 | 取值 | 默认 | 说明 |
|---|---|---|---|
| `checked` | boolean | false | 是否选中（受控） |
| `onChange` | (next: boolean) => void | — | 切换回调 |
| `label` | string | — | 右侧文字；整行都是点击目标 |
| `disabled` | boolean | false | 禁用 |

## 本页用到的 CSS

按样张里出现的类名，从源文件原样裁出（完整版见 zzm.css）：

```css
/* extracted.css */

.zzm-v4 .zzm-switch:focus-visible,
.zzm-v4 .zzm-check:focus-visible,
.zzm-v4 .zzm-tab:focus-visible,
.zzm-v4 .zzm-page:focus-visible,
.zzm-v4 .zzm-sort:focus-visible {
  outline: none;
  box-shadow: 0 0 0 3px rgba(166, 64, 47, .2);
}
```

---

上一页：[开关](https://ui.zhaozimin.cn/components/switch.md) · 下一页：[徽章与档位](https://ui.zhaozimin.cn/components/badge.md) · 全站目录：https://ui.zhaozimin.cn/llms.txt