---
title: CheckboxGroup 复选框组
description: 用于管理多个复选框选择的复选框组组件
icon: updated
links:
  rac: CheckboxGroup
  source: checkbox-group/checkbox-group.tsx
  styles: checkbox-group.css
  storybook: Components/Forms/CheckboxGroup
---

## 用法

```tsx
import { CheckboxGroup, Checkbox, Label, Description } from '@heroui/react';
```

<ComponentPreview
  name="checkbox-group-basic"
/>

## 组件结构

```tsx
import {CheckboxGroup, Checkbox, Label, Description, FieldError} from '@heroui/react';

export default () => (
  <CheckboxGroup name="interests">
    <Label />
    <Description /> {/* 可选 */}
    <Checkbox value="option1">
      <Checkbox.Content>
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        Label {/* 纯文本 — 可点击标签 */}
      </Checkbox.Content>
      <Description /> {/* 可选 — 单个 Checkbox 的帮助文本 */}
    </Checkbox>
    <FieldError /> {/* 可选 */}
  </CheckboxGroup>
);
```

## 示例

### 表面样式

在 [Surface](/docs/components/surface) 组件内使用时，请使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。

<ComponentPreview
  name="checkbox-group-on-surface"
/>

### 禁用

<ComponentPreview
  name="checkbox-group-disabled"
/>

### 半选状态

<ComponentPreview
  name="checkbox-group-indeterminate"
/>

### 受控组件

<ComponentPreview
  name="checkbox-group-controlled"
/>

### 表单校验

<ComponentPreview
  name="checkbox-group-validation"
/>

### 功能扩展示例

<ComponentPreview
  name="checkbox-group-features-and-addons"
/>

### 自定义指示器

<ComponentPreview
  name="checkbox-group-with-custom-indicator"
/>

### 渲染函数

<ComponentPreview
  name="checkbox-group-render-function"
/>

## 自定义样式

### Tailwind CSS

<ComponentPreview name="checkbox-group-custom-styles" />

### 全局 CSS

可使用 `@layer components` 指令自定义 CheckboxGroup 组件类。
[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

```css
@layer components {
  .checkbox-group {
    @apply flex flex-col gap-2;
  }
}
```

## 样式参考

HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

### CSS 类

CheckboxGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/checkbox-group.css)）：

#### 基础类 [!toc]

- `.checkbox-group` - 复选框组根容器

## API 参考

### CheckboxGroup

继承自 [React Aria CheckboxGroup](https://react-spectrum.adobe.com/react-aria/CheckboxGroup.html)。

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `value` | `string[]` | - | 当前选中值（受控） |
| `defaultValue` | `string[]` | - | 默认选中值（非受控） |
| `onChange` | `(value: string[]) => void` | - | 选中值变化时的回调 |
| `isDisabled` | `boolean` | `false` | 是否禁用 |
| `isRequired` | `boolean` | `false` | 是否必填 |
| `isReadOnly` | `boolean` | `false` | 是否只读 |
| `isInvalid` | `boolean` | `false` | 是否处于无效状态 |
| `name` | `string` | - | 提交 HTML 表单时复选框组的名称 |
| `children` | `React.ReactNode \| (values: CheckboxGroupRenderProps) => React.ReactNode` | - | 内容或 render prop |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxGroupRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 |

### Render Props

使用 render prop 模式时，提供以下值：

| Prop | 类型 | 描述 |
|------|------|------|
| `value` | `string[]` | 当前选中值 |
| `isDisabled` | `boolean` | 是否禁用 |
| `isReadOnly` | `boolean` | 是否只读 |
| `isInvalid` | `boolean` | 是否处于无效状态 |
| `isRequired` | `boolean` | 是否必填 |

## 相关组件

<RelatedComponents component="checkboxgroup" />