Web

Native

CheckboxGroup

A checkbox group component for managing multiple checkbox selections

Storybook React Aria Source Styles source

Import

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

Usage

Select your interestsChoose all that apply

CodingLove building software

DesignEnjoy creating beautiful interfaces

WritingPassionate about content creation

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

export function Basic() {
  return (
    <CheckboxGroup name="interests">

Anatomy

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

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

export default () => (
  <CheckboxGroup name="interests">
    <Label />
    <Description /> {/* Optional */}
    <Checkbox value="option1">
      <Checkbox.Control>
        <Checkbox.Indicator />
      </Checkbox.Control>
      <Checkbox.Content>
        <Label />
        <Description /> {/* Optional */}
      </Checkbox.Content>
    </Checkbox>
    <FieldError /> {/* Optional */}
  </CheckboxGroup>
);

On Surface

When used inside a Surface component, CheckboxGroup automatically applies on-surface styling.

Select your interestsChoose all that apply

CodingLove building software

DesignEnjoy creating beautiful interfaces

WritingPassionate about content creation

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

export function OnSurface() {
  return (
    <Surface className="w-full rounded-3xl p-6">

With Custom Indicator

FeaturesSelect the features you want

Email notificationsReceive updates via email

NewsletterGet weekly newsletters

"use client";

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

export function WithCustomIndicator() {

Indeterminate

Select all

Coding

Design

Writing

"use client";

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

Controlled

Your skills

Coding

Design

Writing

Selected: coding, design

"use client";

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

Validation

"use client";

import {Button, Checkbox, CheckboxGroup, FieldError, Form, Label} from "@heroui/react";

export function Validation() {

Disabled

FeaturesFeature selection is temporarily disabled

Feature 1This feature is coming soon

Feature 2This feature is coming soon

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

export function Disabled() {
  return (
    <CheckboxGroup isDisabled name="disabled-features">

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";
import clsx from "clsx";

export function FeaturesAndAddOns() {

Related Components

Checkbox

Label

Fieldset

Styling

Passing Tailwind CSS classes

You can customize the CheckboxGroup component:

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.

@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

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

Checkbox

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

DateField

Date input field with labels, descriptions, and validation built on React Aria DateField

CheckboxGroup

Related Components

On this page

Related Components