CheckboxGroup

Grouped checkboxes with optional master checkbox.

Status: stable. Group: form. Markdown version: /design-system/components/checkbox-group.md

When to use

CheckboxGroup renders a set of related checkboxes under one fieldset legend, with an optional master select-all checkbox that shows the indeterminate state while the set is mixed. It reports the full selected-value array on every change.

When not to use

Do not render a CheckboxGroup with one option. It's an awkward master + one row; collapse to a single Checkbox.
Do not nest a CheckboxGroup inside another CheckboxGroup. AT navigation becomes ambiguous; flatten the option list.
Do not rely on the master label translation key without testing the i18n fallback. The component falls back to the literal "All" if the key isn't resolved; tests must verify the resolved label they expect.
Do not use it for exclusive choices; that is RadioGroup.

Look-alikes

Button: Do not use Button for an on/off state; use Switch. For multi-select within a group, use Checkbox or CheckboxGroup.
RadioGroup: Do not use it for exclusive choices; that is RadioGroup.
SelectableCard: For bare text options without supporting content, use RadioGroup or CheckboxGroup.
SelectableCardGroup: Do not use rich cards when plain RadioGroup or CheckboxGroup labels communicate the choices clearly.

Props

CheckboxGroup props
Prop	Type	Default	Description	Required
`id`	`string`	none	Base id for the checkbox inputs. Without one, the group generates a unique base id, so two groups on a page never share checkbox ids.	No
`label`	`string`	none	Legend text for the group.	Yes
`className`	`string`	none	Additional CSS classes on the group.	No
`options`	`{ label: string; value: string }[]`	`[]`	Checkbox options (label, value)	Yes
`showMasterCheckbox`	`boolean`	`true`	Shows the select-all master checkbox. Defaults to true.	No
`masterLabel`	`string`	none	Label for the select-all master checkbox.	No
`hideLegend`	`boolean`	`false`	Keeps the legend as the accessible name but hides it visually, for a group whose section heading already names it.	No
`defaultSelected`	`string[]`	none	Initially selected option values (uncontrolled)	No
`onChange`	`(selectedOptions: string[]) => void`	none	No description in the contract.	No

Variants

No variant dimensions and no props with a fixed set of values.

Invalid combinations

The contract records no invalid combinations.

Keyboard

CheckboxGroup keyboard behaviour
Key	Behaviour
Space	Activates or toggles the focused control. (standard)
Tab	Moves focus to the control and on to the next focusable element. (standard)

Rows marked (standard) name a key the contract lists without a description; the behaviour shown is the usual one for that key.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

CheckboxGroup rules
Level	Rule	How it is checked
MUST	ARIA: Fieldset legend.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Group checkbox associations.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	Required stories produce no axe violations at the configured severity.	Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8.
MUST	The accessibility tree (role, name, state) matches the committed snapshot for every required story.	Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2.
MUST	The component remains legible and operable under a real browser forced-colors: active pass.	Automated by `npm run test:stories:hc`.
MUST	Every documented keyboard interaction works as specified.	Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2.
MUST	A human completed an end-to-end accessibility review of this component.	Manual review, last on 2026-11-04.
SHOULD	Use it when several checkboxes answer one question; the label becomes the fieldset legend every control announces.	Not stated in the contract.
SHOULD	ShowMasterCheckbox is on by default; pass false for short sets where select-all is not a plausible intent.	Not stated in the contract.
SHOULD	Keep option labels parallel in wording so the set scans as one family.	Not stated in the contract.
SHOULD	Seed defaultSelected with the common case instead of forcing users to re-pick standard options.	Not stated in the contract.
SHOULD NOT	Do not mix unrelated decisions into one group; the legend must truthfully name every option.	Not stated in the contract.

Install and import

Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
Import: import { CheckboxGroup } from "@digitaltableteur/react";
Entry point: @digitaltableteur/react/forms exports it too.
Styles: import @digitaltableteur/react/style.css once at the app boundary.
Also available as the custom element <dt-checkbox-group>; see the custom elements manifest.