Checkbox Group

Grouped checkboxes for selecting multiple related options.

Installation

npx shadcn@latest add @iconiq/b-checkbox-group

Props

CheckboxGroupOption

Each option row is described with a plain object and rendered as an animated button.

labelstring

Required

Primary copy shown for the row.

valuestring

Required

Stable identifier used when checking whether the row is selected and when producing the next selection array.

descriptionstring

Optional secondary text rendered below the label.

groupstring

Optional section label used to chunk long lists into named groups when adjacent options share the same value.

disabledboolean

Disables the row button and blocks hover, active, and toggle behavior for that option.

disabledReasonstring

Optional explainer rendered below disabled rows so users understand why the choice is unavailable.

CheckboxGroup

Animated multi-select list with optimistic toggle feedback, stable output ordering, and optional disclosure for longer option sets.

optionsCheckboxGroupOption[]

Required

Array of rows to render, in display order.

valuestring[]

Default []

Current selected values. The prop remains the source of truth, while the component renders an immediate optimistic preview after each click.

onChange(value: string[]) => void

Receives the next selected values array after a row is toggled, normalized back into the original display order.

classNamestring

Merged onto the root flex column wrapper.

maxVisiblenumber

Optional progressive-disclosure cap. When provided, the list initially renders up to this many rows and reveals the rest with a built-in toggle.

showMoreLabelstring

Optional label prefix for the disclosure button shown when maxVisible hides rows.

showLessLabelstring

Optional label used when the disclosure button collapses the list back down.

The component previews the next state immediately after a click, then re-syncs with whatever value the parent sends back.

If a selected option would be hidden by maxVisible, the list stays expanded so users do not lose track of active choices.

This Base UI version keeps checkbox-group semantics and hidden form inputs through the underlying Base UI primitives, while preserving the same visible row motion.

Motion and accessibility

The component leans on hover surfaces and AnimatePresence rather than native checkbox UI.

Selection is still represented by a Lucide Check icon instead of a filled checkbox background.

The hover surface, tap spring, check icon entrance, and disclosure behavior match the original checkbox-group motion exactly.

Base UI supplies the checkbox and group semantics underneath the same animated shell.

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: @base-ui/react, motion, lucide-react.

This page documents the Base UI install only, because Radix UI does not ship a dedicated checkbox-group primitive.

The generated registry file is /r/b-checkbox-group.json.