CheckboxGroup - Heroui

Import

tsx

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

Usage

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 />
    <Checkbox value="option1">
      <Checkbox.Control>
        <Checkbox.Indicator />
      </Checkbox.Control>
      <Checkbox.Content>
        <Label />
        <Description />
      </Checkbox.Content>
    </Checkbox>
    <FieldError />
  </CheckboxGroup>
);

In Surface

When used inside a Surface component, use variant="secondary" to apply the lower emphasis variant suitable for surface backgrounds.

With Custom Indicator

Indeterminate

Controlled

Validation

Disabled

Features and Add-ons Example

Custom Render Function

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.Control className="border-2 border-purple-500 data-[selected=true]:bg-purple-500">
          <Checkbox.Indicator className="text-white" />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Option 1</Label>
        </Checkbox.Content>
      </Checkbox>
    </CheckboxGroup>
  );
}

Customizing the component classes

To customize the CheckboxGroup component classes, you can use the @layer components directive.

Learn more.

css

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

HeroUI follows the BEM 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):

.checkbox-group - Base checkbox group container

API Reference

CheckboxGroup Props

Inherits from React Aria CheckboxGroup.

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