Forms & choicesBrick 0.1.2

Checkbox Group

CheckboxGroup coordinates related Checkbox-style items, optional item text, and an aggregate parent control.

Live example

Built from the published package

Interactive

Choose with confidence

Know when Checkbox Group is the right part

Use it when

Use it when several submitted choices share group state or a select-all parent.

Choose another path when

Use standalone Checkbox for independent choices and RadioGroup for exactly one choice. The group does not own business validation or persistence.

Installation and imports

tsx

import { CheckboxGroup } from "@flowstack-ui/brick/checkbox-group";
import "@flowstack-ui/brick/styles.css";

The complete stylesheet above is the recommended default. For a measured route-aware build, replace it with the shared foundation and this component's stylesheet:

tsx

import "@flowstack-ui/brick/styles/core.css"; // once at the application root
import "@flowstack-ui/brick/styles/checkbox-group.css";

Add the modular stylesheet for every other Brick component the route renders. Do not combine modular styles with styles.css or tokens.css.

Quick start

tsx

<CheckboxGroup.Root aria-label="Features" defaultValue={["search"]}>
  <CheckboxGroup.Item value="search">
    <CheckboxGroup.ItemLabel>Search</CheckboxGroup.ItemLabel>
  </CheckboxGroup.Item>
</CheckboxGroup.Root>

Visual recipes and states

Root size cascades shared row/control geometry. Orientation arranges Items. Atom owns item checked/mixed state, aggregate Parent state, values, disabled/ invalid state, and form behavior.

Examples

tsx

<CheckboxGroup.Root value={value} onValueChange={setValue}>
  <CheckboxGroup.Parent allValues={["email", "sms"]}>Select all</CheckboxGroup.Parent>
  <CheckboxGroup.Item value="email">Email</CheckboxGroup.Item>
  <CheckboxGroup.Item value="sms">SMS</CheckboxGroup.Item>
</CheckboxGroup.Root>

Public contract

API

Start with the public parts and root options below. Components with multiple parts separate each area into its own named subsection.

Public exports are CheckboxGroup, CheckboxGroupRoot, CheckboxGroupItem, CheckboxGroupItemLabel, CheckboxGroupItemDescription, CheckboxGroupParent, and their corresponding CheckboxGroupRootProps, CheckboxGroupItemProps, CheckboxGroupItemLabelProps, CheckboxGroupItemDescriptionProps, and CheckboxGroupParentProps.

Root prop	Values	Default
`size`	`sm`, `md`, `lg`	`md`
`orientation`	`vertical`, `horizontal`	`vertical`
`asChild`	`boolean`	`false`

Root inherits Atom group value/defaultValue/change, orientation, disabled, invalid, required, name/form, and relationship props and adds the shared size recipe. Item requires Atom value. Parent inherits Atom aggregate behavior including allValues. Label and Description require children. Every part uses the discriminated asChild or render composition contract.

Shared responsibility

Accessibility

Give Root a group name or compose it inside Fieldset with a Legend. Atom owns item/parent semantics, state, form participation, and generated item relationships. Parent labels must explain the aggregate action.

Responsive behavior

Vertical groups stack; horizontal groups can wrap under constraint. Item text may wrap while controls retain target geometry. Logical layout supports RTL.

Stable visual contract

Styling and tokens

Customization

Use Root size/orientation and Atom state props first, then public group and Checkbox tokens. Customize public parts with composition or part-level class/ style without replacing private marks.

Tokens and CSS hooks

Stable classes/slots cover group, item, label, description, and parent with Atom state/value/orientation attributes and Root data-size. Public group token is --brick-checkbox-group-gap; public Checkbox tokens style the shared visual. Internal mark DOM is not composable.

Advanced reference

Open these details only when you need to inspect DOM ownership, native forwarding, or lower-level composition.

Maintainer resources

Tests, playground evidence, source notes, and release history remain available without crowding the plug-and-play guide.

Source docs Changelog Playground