Checkbox Group

A labelled set of checkboxes that share one value, the list of checked options, with an optional Select All.

Stable

Web

iOS

Android

@advui/core

Source

Labels and descriptions

Preview

Code

Daily backupsKept for 30 days.

Usage analyticsPage views, without cookies.

Single sign-onOn the Team plan.

Installation

Package

CLI (copy source)

pnpm

pnpm add @advui/core

npm

npm install @advui/core

Usage

import { CheckboxGroup, Field } from '@advui/core'

<Field label="Notifications">
  <CheckboxGroup value={channels} onValueChange={setChannels}>
    <CheckboxGroup.SelectAll label="All channels" />
    <CheckboxGroup.Item value="email" label="Email" />
    <CheckboxGroup.Item value="sms" label="SMS" description="Standard rates apply." />
  </CheckboxGroup>
</Field>

Examples

Select All

Checks or clears every item, and shows a mixed state while only some are checked.

Preview

Code

All channels

SMS

Push notifications

1 of 3 selected

In a Field

The field names the group and shows its error; the items sit in a row that wraps.

API reference

CheckboxGroup

A View with `role="group"`. Lay items out freely inside it (in a nested stack, beside other content); they find the group through context.

Prop	Type	Default	Description
`value`	`string[]`	—	The checked items’ values, when you control it.
`defaultValue`	`string[]`	`[]`	Starting `value` when uncontrolled.
`onValueChange`	`(value: string[]) => void`	—	Called with the new list when an item or Select All is toggled. A checked item is added at the end.
`orientation`	`'vertical' \| 'horizontal'`	`'vertical'`	`horizontal` puts the items in a row that wraps.
`size`	`'sm' \| 'md'`	`'md'`	Checkbox size for every item: 16 or 20px.
`gap`	`SpaceTokens`	`'3'; horizontal: '5' between items, '3' between rows`	Space between items, and between rows when a horizontal group wraps.
`disabled`	`boolean`	`false`	Disables every item. Also on inside a disabled Field or Form.
`invalid`	`boolean`	`false`	Error border and `aria-invalid` on every item. On inside a Field with an `error`.
`name`	`string`	—	Field name for a native form: each checked item submits its `value` under it.Web only.
`aria-label`	`string`	—	Names the group. Inside a Field, the field’s label names it instead.

CheckboxGroup.Item

A Checkbox; other Checkbox props (`id`, `aria-label`, style props) go to it.

Prop	Type	Default	Description
`value` required	`string`	—	Added to the group’s value while checked.
`label`	`ReactNode`	—	Text beside the checkbox; pressing it toggles the checkbox. Without one, give the item an `aria-label` or your own `Label htmlFor`.
`description`	`ReactNode`	—	Smaller text under the label, linked as the checkbox’s description.
`size`	`'sm' \| 'md'`	`the group’s`	16 or 20px.
`disabled`	`boolean`	`false`	Disables this item. Select All leaves it as it is.

CheckboxGroup.SelectAll

A Checkbox that is checked when every item is, mixed when some are. It is not part of the value.

Prop	Type	Default	Description
`label`	`ReactNode`	—	Text beside the checkbox.
`description`	`ReactNode`	—	Smaller text under the label.
`size`	`'sm' \| 'md'`	`the group’s`	16 or 20px.
`disabled`	`boolean`	`false`	Disables it. It is also disabled when every item is.

Accessibility

role="group", named by aria-label or, inside a Field, by the field’s label (aria-labelledby). The field’s help and error text describe the group.
Each item is a checkbox named by its label, with its description linked through aria-describedby. Pressing the label toggles it.
Select All is aria-checked="mixed" while only some items are checked, and lists the items in aria-controls.
Every checkbox stays a Tab stop, as in the WAI-ARIA checkbox pattern. Space toggles the focused one.
A Field’s required adds the marker to its label, but a group has no required state for screen readers: say what is required in the help or error text.

Keyboard interactions
Key	Action
`Tab`	Moves to the next checkbox.
`Space`	Toggles the focused checkbox.

Platform notes

Web

A div with role="group"; each checked item has a hidden <input type="checkbox"> for form submission.

iOS

VoiceOver has no group names, so each item reads the group’s name and help text as its hint, after its own description. The visible label and description are hidden from VoiceOver, since the checkbox already reads them.