---
title: CheckboxGroup
description: Migration guide for CheckboxGroup from HeroUI v2 to v3
---

<Callout type="info">
  Refer to the [v3 CheckboxGroup documentation](/docs/react/components/checkbox-group) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
</Callout>

## Structure Changes

In v2, `CheckboxGroup` was a separate component with a `label` prop and simple `Checkbox` children:

```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>
  );
}
```

In v3, `CheckboxGroup` is still a separate component but uses `Label`/`Description` as children and the new compound Checkbox structure:

```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>
  );
}
```

## Key Changes

### 1. Same Component Name

**v2:** `CheckboxGroup` (separate import with `label` prop)  
**v3:** `CheckboxGroup` (separate import; use `Label` component instead of `label` prop)

### 2. Label Prop

**v2:** Used `label` prop on `CheckboxGroup`  
**v3:** Use `Label` component as a child of `CheckboxGroup`

### 3. Checkbox Structure

**v2:** Simple Checkbox components with children as labels  
**v3:** Compound Checkbox components with `Checkbox.Content`, `Checkbox.Control`, and `Checkbox.Indicator`

### 4. Event Handler

**v2:** Used `onValueChange` prop  
**v3:** Uses `onChange` prop (from React Aria Components)

### 5. Variant Support

**v3:** New `variant` prop for styling the group container

## Migration Examples

### Controlled CheckboxGroup

<Tabs items={["v2", "v3"]}>
  <Tab value="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>
    ```
  </Tab>
  <Tab value="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>
    ```
  </Tab>
</Tabs>

## Summary

- Keep using `CheckboxGroup`; replace `label` prop with `Label` component as a child
- Update Checkbox children to use compound component structure (`Checkbox.Content`, `Checkbox.Control`, `Checkbox.Indicator`)
- Change `onValueChange` to `onChange`
- Add `name` prop for form integration
- Built on React Aria Components for accessibility
