# CheckboxGroup · HeroUI

> CheckboxGroup 从 HeroUI v2 到 v3 的迁移指南。

- 页面: https://jiguang132.com/zh/systems/heroui/docs/migration/checkbox-group
- 改编自: HeroUI 文档 (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

> 
  完整的 API 参考、样式指南与高级示例请参阅 [v3 CheckboxGroup 文档](/systems/heroui/docs/components/checkbox-group)。本指南只关注从 HeroUI v2 的迁移。


## 结构变化

在 v2 中，`CheckboxGroup` 是单个组件，通过 `label` prop 描述分组，子项为简单的 `Checkbox`：

```tsx
import { Checkbox, CheckboxGroup } from "@heroui/react";

export default function App() {
  return (
    <CheckboxGroup label="Select interests">
      <Checkbox value="coding">Coding</Checkbox>
      <Checkbox value="design">Design</Checkbox>
      <Checkbox value="writing">Writing</Checkbox>
    </CheckboxGroup>
  );
}
```

在 v3 中，`CheckboxGroup` 仍是单个组件，但改为以 `Label` / `Description` 作为子节点，并使用全新的 Checkbox 复合结构：

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

export default function App() {
  return (
    <CheckboxGroup name="interests">
      <Label>Select interests</Label>
      <Checkbox value="coding">
        <Checkbox.Content>
          <Checkbox.Control>
            <Checkbox.Indicator />
          </Checkbox.Control>
          Coding
        </Checkbox.Content>
      </Checkbox>
      <Checkbox value="design">
        <Checkbox.Content>
          <Checkbox.Control>
            <Checkbox.Indicator />
          </Checkbox.Control>
          Design
        </Checkbox.Content>
      </Checkbox>
      <Checkbox value="writing">
        <Checkbox.Content>
          <Checkbox.Control>
            <Checkbox.Indicator />
          </Checkbox.Control>
          Writing
        </Checkbox.Content>
      </Checkbox>
    </CheckboxGroup>
  );
}
```

## 主要变化

### 1. 组件名称保持一致

**v2：** `CheckboxGroup`（单一组件，通过 `label` prop 描述分组）  
**v3：** `CheckboxGroup`（单一组件，使用 `Label` 组件代替 `label` prop）

### 2. Label prop

**v2：** 在 `CheckboxGroup` 上使用 `label` prop  
**v3：** 改用 `Label` 组件作为 `CheckboxGroup` 的子节点

### 3. Checkbox 结构

**v2：** 简单的 Checkbox 组件，子节点直接作为标签  
**v3：** 复合 Checkbox 组件，由 `Checkbox.Content`、`Checkbox.Control` 与 `Checkbox.Indicator` 组成

### 4. 事件处理函数

**v2：** 使用 `onValueChange` prop  
**v3：** 改用 `onChange` prop（来自 React Aria Components）

### 5. 变体支持

**v3：** 新增 `variant` prop，用于设置分组容器的样式

## 迁移示例

### 受控复选框组


  

#### v2


    ```tsx
    import { useState } from "react";
    import { Checkbox, CheckboxGroup } from "@heroui/react";

    const [selected, setSelected] = useState(["coding"]);

    <CheckboxGroup
      value={selected}
      onValueChange={setSelected}
      label="Select interests"
    >
      <Checkbox value="coding">Coding</Checkbox>
      <Checkbox value="design">Design</Checkbox>
      <Checkbox value="writing">Writing</Checkbox>
    </CheckboxGroup>
    ```
  
  

#### v3


    ```tsx
    import { useState } from "react";
    import { CheckboxGroup, Checkbox, Label } from "@heroui/react";

    const [selected, setSelected] = useState(["coding"]);

    <CheckboxGroup
      name="interests"
      value={selected}
      onChange={setSelected}
    >
      <Label>Select interests</Label>
      <Checkbox value="coding">
        <Checkbox.Content>
          <Checkbox.Control>
            <Checkbox.Indicator />
          </Checkbox.Control>
          Coding
        </Checkbox.Content>
      </Checkbox>
      <Checkbox value="design">
        <Checkbox.Content>
          <Checkbox.Control>
            <Checkbox.Indicator />
          </Checkbox.Control>
          Design
        </Checkbox.Content>
      </Checkbox>
      <Checkbox value="writing">
        <Checkbox.Content>
          <Checkbox.Control>
            <Checkbox.Indicator />
          </Checkbox.Control>
          Writing
        </Checkbox.Content>
      </Checkbox>
    </CheckboxGroup>
    ```
  


## 总结

- 继续使用 `CheckboxGroup`；用 `Label` 子组件取代 `label` prop
- 将 Checkbox 子项更新为复合组件结构（`Checkbox.Content`、`Checkbox.Control`、`Checkbox.Indicator`）
- 将 `onValueChange` 改为 `onChange`
- 添加 `name` prop 以便集成到表单中
- 基于 React Aria Components 构建，更易实现无障碍

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt