# CheckboxGroup · HeroUI

> A checkbox group component for managing multiple checkbox selections

- Page: https://jiguang132.com/systems/heroui/docs/components/checkbox-group
- Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## Import

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

### Usage


> Example `checkbox-group-basic`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/checkbox-group


### Anatomy

Import the CheckboxGroup component and access all parts using dot notation.

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

export default () => (
  <CheckboxGroup name="interests">
    <Label />
    <Description /> {/* Optional */}
    <Checkbox value="option1">
      <Checkbox.Content>
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        Label {/* plain text — the clickable label */}
      </Checkbox.Content>
      <Description /> {/* Optional per-checkbox help text */}
    </Checkbox>
    <FieldError /> {/* Optional */}
  </CheckboxGroup>
);
```

### In Surface

When used inside a [Surface](/systems/heroui/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds.


> Example `checkbox-group-on-surface`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/checkbox-group


### With Custom Indicator


> Example `checkbox-group-with-custom-indicator`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/checkbox-group


### Indeterminate


> Example `checkbox-group-indeterminate`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/checkbox-group


### Controlled


> Example `checkbox-group-controlled`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/checkbox-group


### Validation


> Example `checkbox-group-validation`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/checkbox-group


### Disabled


> Example `checkbox-group-disabled`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/checkbox-group


### Features and Add-ons Example


> Example `checkbox-group-features-and-addons`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/checkbox-group


### Custom Render Function


> Example `checkbox-group-custom-render-function`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/checkbox-group


## Styling

### Passing Tailwind CSS classes

You can customize the CheckboxGroup component:

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

function CustomCheckboxGroup() {
  return (
    <CheckboxGroup className="gap-4" name="custom">
      <Checkbox value="option1">
        <Checkbox.Content>
          <Checkbox.Control className="border-2 border-purple-500 data-[selected=true]:bg-purple-500">
            <Checkbox.Indicator className="text-white" />
          </Checkbox.Control>
          Option 1
        </Checkbox.Content>
      </Checkbox>
    </CheckboxGroup>
  );
}
```

### Customizing the component classes

To customize the CheckboxGroup component classes, you can use the `@layer components` directive.
  
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

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

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The CheckboxGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/checkbox-group.css)):

- `.checkbox-group` - Base checkbox group container

## API Reference

### CheckboxGroup Props

Inherits from [React Aria CheckboxGroup](https://react-spectrum.adobe.com/react-aria/CheckboxGroup.html).

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string[]` | - | The current selected values (controlled) |
| `defaultValue` | `string[]` | - | The default selected values (uncontrolled) |
| `onChange` | `(value: string[]) => void` | - | Handler called when the selected values change |
| `isDisabled` | `boolean` | `false` | Whether the checkbox group is disabled |
| `isRequired` | `boolean` | `false` | Whether the checkbox group is required |
| `isReadOnly` | `boolean` | `false` | Whether the checkbox group is read only |
| `isInvalid` | `boolean` | `false` | Whether the checkbox group is in an invalid state |
| `name` | `string` | - | The name of the checkbox group, used when submitting an HTML form |
| `children` | `React.ReactNode \| (values: CheckboxGroupRenderProps) => React.ReactNode` | - | Checkbox group content or render prop |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxGroupRenderProps>` | - | Overrides the default DOM element with a custom render function.|

### CheckboxGroupRenderProps

When using the render prop pattern, these values are provided:

| Prop | Type | Description |
|------|------|-------------|
| `value` | `string[]` | The currently selected values |
| `isDisabled` | `boolean` | Whether the checkbox group is disabled |
| `isReadOnly` | `boolean` | Whether the checkbox group is read only |
| `isInvalid` | `boolean` | Whether the checkbox group is in an invalid state |
| `isRequired` | `boolean` | Whether the checkbox group is required |

---

Index of all JGuang resources: https://jiguang132.com/llms.txt