Checkbox Group

Typed multi-select group of native checkboxes with an optional tri-state select-all parent.


Package	`@vizejs/ui/checkbox-group`
Maturity	stable
Own the source	`vize lib pull checkbox-group`
Requires	context, controllable-state
Aliases	checkbox list, multi-select checkboxes, select all, tri-state checkbox
Covers	HTML checkbox, WAI-ARIA Checkbox (tri-state), React Aria CheckboxGroup, Reka UI CheckboxGroup

Usage

import { CheckboxGroup, CheckboxGroupItem, CheckboxGroupSelectAll } from "@vizejs/ui/checkbox-group";

Or copy the source into your project with vize lib pull checkbox-group (see Source Distribution).

API

`CheckboxGroup<Value>`

Source: src/families/selection/checkbox-group/checkbox-group.vue

Props

Prop	Type	Default	Description
`options` (required)	`readonly Value[]`	`required`	Every selectable value, in display order. Infers the group's value type.
`modelValue`	`readonly Value[]`	`undefined`	Controlled selected values. `undefined` selects uncontrolled behavior.
`defaultValue`	`readonly Value[]`	`[]`	Initial uncontrolled selection, also restored by form reset.
`by`	`(value: Value) => CheckboxGroupKey`	`Object.is identity`	Identity key for comparing selected values with options, for example `(user) => user.id` when the model holds fresh object copies.
`getFormValue`	`(value: Value, index: number) => string`	`String(value) for primitives, else the option index`	Native form value submitted for an option.
`isOptionDisabled`	`(value: Value, index: number) => boolean`	`undefined`	Disable individual options. Disabled options keep their selection when select-all toggles.
`name`	`string`	`undefined`	Native form field name shared by every item checkbox.
`form`	`string`	`undefined`	Id of a form owner outside the component tree.
`disabled`	`boolean`	`false`	Disable every checkbox in the group.
`required`	`boolean`	`false`	Require at least one selection for native constraint validation.
`orientation`	`CheckboxGroupOrientation`	`"vertical"`	Layout direction published through `data-orientation`.
`ariaLabel`	`string`	`undefined`	Accessible name when no label or `aria-labelledby` supplies one.
`ariaLabelledby`	`string`	`undefined`	Space-separated ids that label the group.
`ariaDescribedby`	`string`	`undefined`	Space-separated ids that describe the group and every checkbox.
`ariaErrormessage`	`string`	`undefined`	Id of the validation error message used while invalid.
`ariaInvalid`	`CheckboxGroupAriaInvalid`	`false`	Invalid state announced on every checkbox.

Events

Event	Payload	Description
`update:modelValue`	`[value: readonly Value[]]`	Fired when the selection requests new values (in option order).
`change`	`[value: readonly Value[], toggled: Value \| null, selected: boolean]`	Fired after a user or API change with the next values, the toggled value (or `null` for select-all), and its new state.

Slots

Slot	Slot props	Description
`default`	`CheckboxGroupSlotState<Value>`	Renders items and the optional select-all parent with the selection summary.

Exposed

Member	Type	Description
`values`	`readonly Value[]`	Selected values in option order.
`options`	`readonly Value[]`	Every option, in order.
`allSelected`	`boolean`	Whether every enabled option is selected.
`someSelected`	`boolean`	Whether at least one but not every enabled option is selected.
`disabled`	`boolean`	Whether the whole group is disabled.
`state`	`CheckboxGroupState`	Selection summary.
`root`	`HTMLDivElement \| null`	Rendered group element.
`isSelected`	`(value: Value) => boolean`	Whether an option value is selected.
`setSelected`	`(value: Value, selected: boolean) => boolean`	Select or clear one option; returns whether the selection changed.
`setAll`	`(selected: boolean) => boolean`	Select or clear every enabled option; returns whether the selection changed.
`reset`	`() => boolean`	Restore the default selection; returns whether it changed.

`CheckboxGroupItem<Value>`

Source: src/families/selection/checkbox-group/checkbox-group-item.vue

Props

Prop	Type	Default	Description
`value` (required)	`Value`	`required`	Option this checkbox toggles; must be one of the group's `options` (by identity).
`id`	`string`	`undefined`	Native id, typically referenced by a `<label for>`.
`disabled`	`boolean`	`false`	Disable this checkbox in addition to group and `isOptionDisabled` rules.
`ariaLabel`	`string`	`undefined`	Accessible name when no wrapping or associated label supplies one.
`ariaLabelledby`	`string`	`undefined`	Space-separated ids that label this checkbox.

Events

Event	Payload	Description
`change`	`[checked: boolean, nativeEvent: Event]`	Fired after the user toggles this checkbox, with its new checked state and native `Event`.

`CheckboxGroupSelectAll`

Source: src/families/selection/checkbox-group/checkbox-group-select-all.vue

Props

Prop	Type	Default	Description
`id`	`string`	`undefined`	Native id, typically referenced by a `<label for>`.
`ariaLabel`	`string`	`undefined`	Accessible name when no wrapping or associated label supplies one.
`ariaLabelledby`	`string`	`undefined`	Space-separated ids that label the parent checkbox.

Events

Event	Payload	Description
`change`	`[selected: boolean, nativeEvent: Event]`	Fired after the user toggles every enabled option, with the requested state and native `Event`.

Behavior

Normative state x input -> outcome table for checkbox-group.vue, checkbox-group-item.vue, and checkbox-group-select-all.vue (@vizejs/ui/checkbox-group). The group is generic: options: readonly Value[] infers Value, so v-model is readonly Value[] for strings, unions, or objects. The select-all parent follows the WAI-ARIA APG tri-state checkbox. Every row is proven by the named test in checkbox-group.test.ts or checkbox-group-ssr.test.ts; inference and misuse are pinned in checkbox-group.types.test-d.ts.

#	State	Input	Outcome	Proven by
C1	named, seeded	render	labelled `role="group"` of native checkboxes sharing `name`; primitive options submit `String(value)`; summary `data-state` and slot state	`renders a labelled group of named native checkboxes with typed values`
C2	uncontrolled objects	toggle items	values stay in option order, `update:modelValue` then `change(values, toggled, selected)`; object options submit their index by default	`toggling items updates values in option order and emits changes`
C3	partial selection	select-all	parent is `mixed`/indeterminate while some enabled options are selected; toggling selects or clears enabled options and keeps disabled selections	`select-all is tri-state and toggles every enabled option`
C4	controlled with `by`	toggle	fresh object copies match options by key; `getFormValue` controls submitted values; the controlled value wins until accepted	controlled values win and `by` matches fresh object copies
C5	in a form, `required`	submit / toggle / reset	submits every selected value; every box is `required` only while nothing is selected; form reset restores `defaultValue`	`submits selected values, requires one selection, and restores defaults on reset`
C6	disabled group	toggle / API	every checkbox (and select-all) is natively disabled, `aria-disabled` on the group, and no changes are emitted	`disabled groups disable every checkbox and ignore toggles`
C7	imperative	expose	`isSelected`, `setSelected` (unknown values ignored), `setAll`, `reset`, and the selection summary	`exposes isSelected, setSelected, setAll, reset, and the selection summary`
C8	part without provider	setup	throws the stable `VIZE_UI_CONTEXT_MISSING: CheckboxGroup` diagnostic	`items and select-all require a CheckboxGroup provider`
C9	SSR / hydration	isolated requests	byte-identical markup (checked + `aria-checked="mixed"`), hydration applies `indeterminate` and stays interactive	`renders byte-identical checkbox group markup and hydrates without mismatches`

Public extension contract

Surface	Contract
Parts	`root` (group), `item`, `select-all` (native checkboxes; wrap them in `<label>` for names).
Data attributes	`data-vize-ui`, root `data-state` (`all`/`some`/`none`/`disabled`), `data-orientation`; item `data-index`/`data-state`.
Identity	Items resolve `value` to an option by identity (through reactive proxies); `by` compares model values with options.

The subpath is tree-shakable and ships no CSS; those package contracts are pinned by distribution.test.ts, check:size, and check:tree-shaking.