Skip to main content
The CheckboxGroup component manages multiple checkbox selections with support for parent-child relationships and nested structures.

Installation

npx shadcn@latest add @eo-n/checkbox-group

Usage

import { CheckboxGroup } from "@/components/ui/checkbox-group";
import { Checkbox } from "@/components/ui/checkbox";
import { Label } from "@/components/ui/label";

export default function Example() {
  return (
    <CheckboxGroup>
      <div className="flex items-center space-x-2">
        <Checkbox value="option1" id="option1" />
        <Label htmlFor="option1">Option 1</Label>
      </div>
      <div className="flex items-center space-x-2">
        <Checkbox value="option2" id="option2" />
        <Label htmlFor="option2">Option 2</Label>
      </div>
    </CheckboxGroup>
  );
}

Examples

Basic Group

<CheckboxGroup>
  <div className="flex items-center space-x-2">
    <Checkbox value="react" id="react" />
    <Label htmlFor="react">React</Label>
  </div>
  <div className="flex items-center space-x-2">
    <Checkbox value="vue" id="vue" />
    <Label htmlFor="vue">Vue</Label>
  </div>
  <div className="flex items-center space-x-2">
    <Checkbox value="svelte" id="svelte" />
    <Label htmlFor="svelte">Svelte</Label>
  </div>
</CheckboxGroup>

Controlled Group

import { useState } from "react";

function ControlledGroup() {
  const [value, setValue] = useState(["option1"]);

  return (
    <CheckboxGroup value={value} onValueChange={setValue}>
      <div className="flex items-center space-x-2">
        <Checkbox value="option1" id="opt1" />
        <Label htmlFor="opt1">Option 1</Label>
      </div>
      <div className="flex items-center space-x-2">
        <Checkbox value="option2" id="opt2" />
        <Label htmlFor="opt2">Option 2</Label>
      </div>
      <div className="flex items-center space-x-2">
        <Checkbox value="option3" id="opt3" />
        <Label htmlFor="opt3">Option 3</Label>
      </div>
    </CheckboxGroup>
  );
}

With Parent Checkbox

<CheckboxGroup>
  <div className="flex items-center space-x-2">
    <Checkbox parent id="parent" />
    <Label htmlFor="parent">Select All</Label>
  </div>
  <CheckboxGroup>
    <div className="flex items-center space-x-2">
      <Checkbox value="child1" id="child1" />
      <Label htmlFor="child1">Child 1</Label>
    </div>
    <div className="flex items-center space-x-2">
      <Checkbox value="child2" id="child2" />
      <Label htmlFor="child2">Child 2</Label>
    </div>
    <div className="flex items-center space-x-2">
      <Checkbox value="child3" id="child3" />
      <Label htmlFor="child3">Child 3</Label>
    </div>
  </CheckboxGroup>
</CheckboxGroup>

Nested Parent Checkboxes

<CheckboxGroup>
  <div className="flex items-center space-x-2">
    <Checkbox parent id="root" />
    <Label htmlFor="root">All Items</Label>
  </div>
  <CheckboxGroup>
    <div className="flex items-center space-x-2">
      <Checkbox parent id="fruits" />
      <Label htmlFor="fruits">Fruits</Label>
    </div>
    <CheckboxGroup>
      <div className="flex items-center space-x-2">
        <Checkbox value="apple" id="apple" />
        <Label htmlFor="apple">Apple</Label>
      </div>
      <div className="flex items-center space-x-2">
        <Checkbox value="banana" id="banana" />
        <Label htmlFor="banana">Banana</Label>
      </div>
    </CheckboxGroup>
  </CheckboxGroup>
</CheckboxGroup>

Disabled Group

<CheckboxGroup disabled>
  <div className="flex items-center space-x-2">
    <Checkbox value="option1" id="d1" />
    <Label htmlFor="d1">Option 1</Label>
  </div>
  <div className="flex items-center space-x-2">
    <Checkbox value="option2" id="d2" />
    <Label htmlFor="d2">Option 2</Label>
  </div>
</CheckboxGroup>

API Reference

CheckboxGroup

Extends all props from @base-ui/react CheckboxGroup component.
value
string[]
The controlled selected values.
defaultValue
string[]
The default selected values when uncontrolled.
onValueChange
function
Callback fired when the selected values change.
(value: string[]) => void
disabled
boolean
Whether all checkboxes in the group are disabled.
className
string
Additional CSS classes to apply.

TypeScript

import { CheckboxGroup as CheckboxGroupPrimitive } from "@base-ui/react";

type CheckboxGroupProps = React.ComponentProps<typeof CheckboxGroupPrimitive>;

Accessibility

  • Parent checkboxes automatically show indeterminate state
  • Keyboard navigation between checkboxes
  • Proper grouping with ARIA attributes
  • Focus management

Build docs developers (and LLMs) love