> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt.

# Checkbox

数据录入`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

选择一个或多个相互独立的布尔选项。

## 何时使用

独立选择使用 Checkbox；从一组选项中多选时使用 CheckboxGroup。

**推荐**

- 标签应准确描述选中后的状态。
- 相关选项使用 CheckboxGroup 组织。

**避免**

- 只能选一个选项时不要使用 CheckboxGroup，应改用 RadioGroup。

## 代码演示


### 基础用法
```tsx preview
import { Checkbox, CheckboxGroup, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';

function CheckboxExample() {
  const [updates, setUpdates] = useState(true);
  const [channels, setChannels] = useState(['email', 'push']);

  return (
    <Stack gap="md">
      <Checkbox
        checked={updates}
        onChange={(event) => setUpdates(event.target.checked)}
      >
        Send product updates
      </Checkbox>
      <CheckboxGroup
        value={channels}
        onChange={setChannels}
        options={[
          { label: 'Email', value: 'email' },
          { label: 'Push', value: 'push' },
          { label: 'SMS', value: 'sms', disabled: true },
        ]}
      />
    </Stack>
  );
}

export default CheckboxExample;
```

### 独立状态
```tsx preview
import { Checkbox, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';

function CheckboxStates() {
  const [unchecked, setUnchecked] = useState(false);
  const [checked, setChecked] = useState(true);
  const [mixed, setMixed] = useState(false);

  return (
    <Stack direction="horizontal" gap="lg" style={{ flexWrap: 'wrap' }}>
      <Checkbox
        checked={unchecked}
        onChange={(event) => setUnchecked(event.target.checked)}
      >
        Unchecked
      </Checkbox>
      <Checkbox
        checked={checked}
        onChange={(event) => setChecked(event.target.checked)}
      >
        Checked
      </Checkbox>
      <Checkbox
        checked={mixed}
        indeterminate={!mixed}
        onChange={(event) => setMixed(event.target.checked)}
      >
        Indeterminate
      </Checkbox>
      <Checkbox disabled>Disabled</Checkbox>
      <Checkbox checked disabled onChange={() => {}}>
        Checked disabled
      </Checkbox>
    </Stack>
  );
}

export default CheckboxStates;
```

### 纵向选项组
```tsx preview
import { CheckboxGroup, FormField } from '@rockshin/tao-ui';
import { useState } from 'react';

function VerticalCheckboxGroup() {
  const [value, setValue] = useState(['email']);

  return (
    <FormField label="Notifications">
      <CheckboxGroup
        direction="vertical"
        value={value}
        onChange={setValue}
        options={[
          { label: 'Email updates', value: 'email' },
          { label: 'Push notifications', value: 'push' },
          { label: 'SMS alerts', value: 'sms', disabled: true },
        ]}
      />
    </FormField>
  );
}

export default VerticalCheckboxGroup;
```

### 受控复选框
onChange 提供原生事件，从 target.checked 读取新值。
```tsx preview
import { useState } from 'react';
import { Checkbox, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [checked, setChecked] = useState(false);
  return (
    <Stack direction="vertical">
      <Checkbox
        checked={checked}
        onChange={(e) => setChecked(e.target.checked)}
      >
        Receive updates
      </Checkbox>
      <output>{checked ? 'Subscribed' : 'Not subscribed'}</output>
    </Stack>
  );
}
```

### 全选与半选
由当前选项数量计算半选状态，避免分别维护互相矛盾的状态。
```tsx preview
import { useState } from 'react';
import { Checkbox, CheckboxGroup, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [values, setValues] = useState<string[]>(['Read']);
  return (
    <Stack direction="vertical">
      <Checkbox
        checked={values.length === 3}
        indeterminate={values.length > 0 && values.length < 3}
        onChange={(e) =>
          setValues(e.target.checked ? ['Read', 'Write', 'Share'] : [])
        }
      >
        Select all
      </Checkbox>
      <CheckboxGroup
        options={['Read', 'Write', 'Share']}
        value={values}
        onChange={setValues}
      />
      <output>{values.join(', ') || 'None selected'}</output>
    </Stack>
  );
}
```

### 垂直排列与禁用选项
对象形式的 options 可单独禁用选项，direction 控制排列方向。
```tsx preview
import { CheckboxGroup } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <CheckboxGroup
      direction="vertical"
      options={[
        { label: 'Email', value: 'email' },
        { label: 'SMS', value: 'sms' },
        { label: 'Phone (unavailable)', value: 'phone', disabled: true },
      ]}
      defaultValue={['email']}
    />
  );
}
```

### 原生表单值
将受控选项写入隐藏输入，再通过 FormData 读取。
```tsx preview
import { useState } from 'react';
import { CheckboxGroup, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [values, setValues] = useState<string[]>(['email']);
  const [result, setResult] = useState('');
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        setResult(
          new FormData(e.currentTarget).getAll('channel').join(', ') || 'None',
        );
      }}
    >
      <Stack direction="vertical">
        <CheckboxGroup
          options={['email', 'sms']}
          value={values}
          onChange={setValues}
        />
        {values.map((value) => (
          <input key={value} type="hidden" name="channel" value={value} />
        ))}
        <Button type="submit">Read values</Button>
        <output>{result}</output>
      </Stack>
    </form>
  );
}
```

### 尺寸与共享禁用
局部 Provider 统一尺寸，也可统一禁用一组控件。
```tsx preview
import { Checkbox, TaoProvider, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack direction="vertical">
      {(['small', 'medium', 'large'] as const).map((size) => (
        <TaoProvider key={size} size={size}>
          <Checkbox>{size}</Checkbox>
        </TaoProvider>
      ))}
      <TaoProvider disabled>
        <Checkbox defaultChecked>Disabled by provider</Checkbox>
      </TaoProvider>
    </Stack>
  );
}
```

## API


### [#](#checkboxgroup)CheckboxGroup



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| disabled | 是否禁用 | `boolean | undefined` | `-` |



### [#](#checkbox)Checkbox



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| disabled | 是否禁用 | `boolean | undefined` | `-` |
| required | Require a checked value when submitting a native form. | `boolean | undefined` | `-` |

