CheckboxGroup - Heroui

<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.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Coding</Label>
        </Checkbox.Content>
      </Checkbox>
      <Checkbox value="design">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Design</Label>
        </Checkbox.Content>
      </Checkbox>
      <Checkbox value="writing">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Writing</Label>
        </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.Control, Checkbox.Indicator, and Checkbox.Content

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.Control>
      <Checkbox.Indicator />
    </Checkbox.Control>
    <Checkbox.Content>
      <Label>Coding</Label>
    </Checkbox.Content>
  </Checkbox>
  <Checkbox value="design">
    <Checkbox.Control>
      <Checkbox.Indicator />
    </Checkbox.Control>
    <Checkbox.Content>
      <Label>Design</Label>
    </Checkbox.Content>
  </Checkbox>
  <Checkbox value="writing">
    <Checkbox.Control>
      <Checkbox.Indicator />
    </Checkbox.Control>
    <Checkbox.Content>
      <Label>Writing</Label>
    </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.Control, Checkbox.Indicator, Checkbox.Content)
Change onValueChange to onChange
Add name prop for form integration
Built on React Aria Components for accessibility