Checkbox Group

Use CheckboxGroup for several independent choices that share a label. Use RadioGroup when only one choice is valid.

Installation

Need	Choose
Choose several values	CheckboxGroup groups independent choices.
Choose one value	RadioGroup keeps one active choice.

Install the local ghost-kit source bundle while the registry runs at localhost:3110. It contains this component and its source dependencies. Prepare the local registry first so token dependencies also resolve locally.

Install

npx shadcn@latest add http://localhost:3110/r/ghost-kit.json

Basic usage

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

<CheckboxGroup aria-label="Notifications" defaultValue={["email"]}>
  <CheckboxGroup.Rows>
    <Checkbox.Row><Checkbox.Root value="email" aria-label="Email"><Checkbox.Indicator /></Checkbox.Root>Email</Checkbox.Row>
  </CheckboxGroup.Rows>
</CheckboxGroup>

Structures

Examples

Interactive style

Use variant="interactive" to add row hover feedback and an inner control fill. Both styles fill the core control on hover. The default keeps the row and text unchanged. Set the variant on the group to style all its rows. Keyboard focus remains visible in both styles.

Parent checkbox

Apples selects or clears every variety. A partial selection gives the parent a mixed state.

Nested parent checkbox

User permissions groups View dashboard and Manage users. Each parent reflects its descendants.

API reference

variant accepts "default" | "interactive" and defaults to "default". Set it on CheckboxGroup to style its rows and controls. Use the group variant for shared-background lists. Group controls align with the group label in both styles.

For inherited behavior and additional part properties, see the Base UI Checkbox Group API.

CheckboxGroup properties
Prop	Type	Default	Description
`className`	`string \| ((state: CheckboxGroupState) => string)`		CSS class applied to the element, or a function that returns a class based on the component's state.
`defaultValue`	`string[]`		Names of the checkboxes in the group that should be initially ticked. To render a controlled checkbox group, use the `value` prop instead.
`style`	`CSSProperties \| ((state: CheckboxGroupState) => React.CSSProperties)`		Style applied to the element, or a function that returns a style object based on the component's state.
`disabled`	`boolean`	`false`	Whether the component should ignore user interaction.
`value`	`string[]`		Names of the checkboxes in the group that should be ticked. To render an uncontrolled checkbox group, use the `defaultValue` prop instead.
`render`	`ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, CheckboxGroupState>`		Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`onValueChange`	`((value: string[], eventDetails: CheckboxGroupChangeEventDetails) => void)`		Event handler called when a checkbox in the group is ticked or unticked. Provides the new value as an argument.
`allValues`	`string[]`		Names of all checkboxes in the group. Use this when creating a parent checkbox.

Preview

Design guidance