Checkbox Group

Grouped checkboxes for selecting multiple related options.

Installation

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

File Structure

Usage

"use client";

import { useState } from "react";
import {
  CheckboxGroup,
  CheckboxGroupItem,
} from "@/components/ui/b-checkbox-group";

export function CheckboxGroupPreview() {
  const [value, setValue] = useState<string[]>(["email"]);

  return (
    <CheckboxGroup
      aria-label="Notification preferences"
      className="w-[min(100%,28rem)]"
      name="notifications"
      onChange={setValue}
      value={value}
    >
      <CheckboxGroupItem
        description="Release notes and changelog digests."
        label="Email updates"
        value="email"
      />
      <CheckboxGroupItem
        description="Feature launches and roadmap highlights."
        label="Product news"
        value="news"
      />
      <CheckboxGroupItem
        description="Critical patches and account notices."
        label="Security alerts"
        value="security"
      />
    </CheckboxGroup>
  );
}

Props

Props
Description

CheckboxGroupItem

label

Primary copy shown for the row.

Type React.ReactNode

value

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

Type string

id

Optional stable id used for label and description associations. Falls back to a generated id when omitted.

Type string

description

Optional secondary text rendered below the label and linked through aria-describedby.

Type React.ReactNode

disabled

Disables this row only. Use CheckboxGroupSection disabled to disable an entire section.

Type boolean

disabledReason

Optional explainer rendered below disabled rows and linked through aria-describedby.

Type string

readOnly

Shows this row without allowing toggles and keeps it checked. Pair with CheckboxGroup value for mixed read-only and interactive rows.

Type boolean

CheckboxGroupSection

label

Optional section heading rendered as a fieldset legend. Required for maxVisible section collapse.

Type string

disabled

Disables every checkbox row inside this section and applies native fieldset disabled semantics.

Type boolean·Default false

children

CheckboxGroupItem elements to render inside the section.

Type React.ReactNode

CheckboxGroupOption

label

Primary copy shown for the row.

Type React.ReactNode

value

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

Type string

id

Optional stable id used for label and description associations. Falls back to a generated id when omitted.

Type string

description

Optional secondary text rendered below the label and linked through aria-describedby.

Type React.ReactNode

group

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

Type string

disabled

Disables the row button and blocks hover, active, and toggle behavior for that option. Works inside grouped sections as well as flat lists.

Type boolean

disabledReason

Optional explainer rendered below disabled rows and linked through aria-describedby.

Type string

readOnly

Shows the row state without allowing toggles. Useful for locked consent or audit views.

Type boolean

CheckboxGroup

children

Preferred composition API. Pass CheckboxGroupItem rows directly or nest them inside CheckboxGroupSection wrappers.

Type React.ReactNode

options

Legacy array-based configuration. Ignored when children are provided.

Type CheckboxGroupOption[]

value

Controlled selected values. When provided, the parent remains the source of truth while the component renders an immediate optimistic preview after each click.

Type string[]

defaultValue

Initial selected values for uncontrolled usage. Ignored when value is provided.

Type string[]·Default []

onChange

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

Type (value: string[]) => void

name

Forwarded to each hidden checkbox input for native form submission.

Type string

form

Associates the hidden checkbox inputs with a distant form element by id.

Type string

disabled

Disables every row in the group. Prefer CheckboxGroupSection disabled or CheckboxGroupItem disabled for partial disable.

Type boolean·Default false

invalid

Applies destructive border styling and aria-invalid for form validation feedback.

Type boolean·Default false

size

Controls row padding, checkbox box size, and label typography.

Type "sm" | "default" | "lg"·Default "default"

maxVisible

When labeled CheckboxGroupSection children are used, limits how many sections stay visible before a show more control appears.

Type number

showMoreLabel

Button label when grouped sections are collapsed. Appends the hidden section count in parentheses.

Type string·Default "Show more"

showLessLabel

Button label when grouped sections are expanded.

Type string·Default "Show less"

aria-label

Accessible name for the checkbox group when no visible label is present.

Type string

aria-labelledby

Id of an external element that labels the checkbox group.

Type string

aria-describedby

Id of an external element that describes the checkbox group.

Type string

className

Merged onto the root flex column wrapper.

Type string

Motion and accessibility

Base UI supplies role='group', checkbox semantics, and hidden native inputs underneath the animated row shell.

Selection is represented by an SVG checkmark draw instead of a filled checkbox background.

Row hover, active, tap spring, and label fade match the core Iconiq checkbox-group.

Motion honors prefers-reduced-motion for checkmark draw and label fade transitions.

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/checkbox, motion.

Contact

Additionally, if you find any bug or issue, feel free to raise an issue.