ProHeroUI Pro is live - Components, templates & AI tooling

v3.2.4

Web

Native

CheckboxGroupUpdated

A checkbox group component for managing multiple checkbox selections

Storybook React Aria Source Styles source

Usage

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

Select your interestsChoose all that apply

CodingLove building software

DesignEnjoy creating beautiful interfaces

WritingPassionate about content creation

Anatomy

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

Examples

In Surface

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

Select your interestsChoose all that apply

CodingLove building software

DesignEnjoy creating beautiful interfaces

WritingPassionate about content creation

Disabled

FeaturesFeature selection is temporarily disabled

Feature 1This feature is coming soon

Feature 2This feature is coming soon

Indeterminate

Select all

Coding

Design

Writing

Controlled

Your skills

Coding

Design

Writing

Selected: coding, design

Validation

Features and Add-ons Example

Notification preferencesChoose how you want to receive updates

Email NotificationsReceive updates via email

SMS AlertsGet instant SMS notifications

Push NotificationsBrowser and mobile push alerts

import {Bell, Comment, Envelope} from "@gravity-ui/icons";
import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";

With Custom Indicator

FeaturesSelect the features you want

Email notificationsReceive updates via email

NewsletterGet weekly newsletters

Render Function

Select your interestsChoose all that apply

CodingLove building software

DesignEnjoy creating beautiful interfaces

WritingPassionate about content creation

"use client";

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

export function RenderFunction() {

Customization

Tailwind CSS

Notification channelsChoose how we should reach you for account updates.

SMS

Push

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

const controlClassName = "bg-success-soft before:bg-success";
const indicatorClassName =
  "**:data-[slot=checkbox-default-indicator--checkmark]:text-success-foreground";

Global CSS

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

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

Styling Reference

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):

Base Classes

.checkbox-group - Base checkbox group container

API Reference

CheckboxGroup

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.

Render Props

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

Checkbox

Label

Fieldset

Checkbox

Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected.

Chip

Small informational badges for displaying labels, statuses, and categories

CheckboxGroupUpdated

On this page