# CheckboxGroup **Category**: react **URL**: https://heroui.com/en/docs/react/components/checkbox-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(forms)/checkbox-group.mdx > A checkbox group component for managing multiple checkbox selections *** ## Usage ```tsx import { CheckboxGroup, Checkbox, Label, Description } from '@heroui/react'; ``` ```tsx import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; export function Basic() { return ( Choose all that apply Coding Love building software Design Enjoy creating beautiful interfaces Writing Passionate about content creation ); } ``` ## Anatomy ```tsx import {CheckboxGroup, Checkbox, Label, Description, FieldError} from '@heroui/react'; export default () => ( ); ``` ## Examples ### In Surface When used inside a [Surface](/docs/react/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds. ```tsx import {Checkbox, CheckboxGroup, Description, Label, Surface} from "@heroui/react"; export function OnSurface() { return ( Choose all that apply Coding Love building software Design Enjoy creating beautiful interfaces Writing Passionate about content creation ); } ``` ### Disabled ```tsx import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; export function Disabled() { return ( Feature selection is temporarily disabled Feature 1 This feature is coming soon Feature 2 This feature is coming soon ); } ``` ### Indeterminate ```tsx "use client"; import {Checkbox, CheckboxGroup} from "@heroui/react"; import {useState} from "react"; export function Indeterminate() { const [selected, setSelected] = useState(["coding"]); const allOptions = ["coding", "design", "writing"]; return (
0 && selected.length < allOptions.length} isSelected={selected.length === allOptions.length} name="select-all" onChange={(isSelected: boolean) => { setSelected(isSelected ? allOptions : []); }} > Select all
Coding Design Writing
); } ``` ### Controlled ```tsx "use client"; import {Checkbox, CheckboxGroup, Label} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const [selected, setSelected] = useState(["coding", "design"]); return ( Coding Design Writing ); } ``` ### Validation ```tsx "use client"; import {Button, Checkbox, CheckboxGroup, FieldError, Form, Label} from "@heroui/react"; export function Validation() { return (
{ e.preventDefault(); const formData = new FormData(e.currentTarget); const values = formData.getAll("preferences"); alert(`Selected preferences: ${values.join(", ")}`); }} > Email notifications SMS notifications Push notifications Please select at least one notification method.
); } ``` ### Features and Add-ons Example ```tsx import {Bell, Comment, Envelope} from "@gravity-ui/icons"; import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; import clsx from "clsx"; export function FeaturesAndAddOns() { const addOns = [ { description: "Receive updates via email", icon: Envelope, title: "Email Notifications", value: "email", }, { description: "Get instant SMS notifications", icon: Comment, title: "SMS Alerts", value: "sms", }, { description: "Browser and mobile push alerts", icon: Bell, title: "Push Notifications", value: "push", }, ]; return (
Choose how you want to receive updates
{addOns.map((addon) => (
{addon.title} {addon.description}
))}
); } ``` ### With Custom Indicator ```tsx "use client"; import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; export function WithCustomIndicator() { return ( Select the features you want {({isSelected}) => isSelected ? ( ) : null } Email notifications Receive updates via email {({isSelected}) => isSelected ? ( ) : null } Newsletter Get weekly newsletters ); } ``` ### Render Function ```tsx "use client"; import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; export function RenderFunction() { return (
}> Choose all that apply Coding Love building software Design Enjoy creating beautiful interfaces Writing Passionate about content creation ); } ``` ## Customization ### Tailwind CSS ```tsx 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"; const channels = [ {label: "Email", value: "email"}, {label: "SMS", value: "sms"}, {label: "Push", value: "push"}, ] as const; export function CustomStyles() { return ( Choose how we should reach you for account updates. {channels.map(({label, value}) => ( {label} ))} ); } ``` ### Global CSS 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; } } ``` ## Styling Reference HeroUI follows the [BEM](https://bem.info/en/methodology/) 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)): #### Base Classes [!toc] - `.checkbox-group` - Base checkbox group container ## API Reference ### CheckboxGroup 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` | - | 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 | ## Related Components ## Related Components - **Checkbox**: Binary choice input control - **Label**: Accessible label for form controls - **Fieldset**: Group related form controls with legends