HyCheckboxGroup

Usage examples on this page are written for Lit / plain HTML (<hy-checkbox-group>). The same component ships as HyCheckboxGroup in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A set of checkboxes with one name, one value and one message line — "pick all that apply". The group submits one form entry per checked box under its name, owns required (at least one checked), and shows its helper, error or warning once, under the set; every box paints the error or warning.

Group, radio group or multi-combobox?

A handful of options people pick several of, all visible: a checkbox group. One of a few: hy-radio-group. Many options, or a long list to search: hy-multi-combobox. A single yes / no is one hy-checkbox.

Value

value is a string[] (a property, not an attribute). In markup, check the children with state="checked"; the group reads them on its first render. From then on the group owns the value and writes each child's state. Give every child a value — a box without one submits "on".

Select all

select-all draws a parent box above the children. Its state is derived — all checked, none, or the dash for some — and a click checks every enabled child, or clears them when all are checked. Disabled children are left out and never change. It has no value of its own and never counts for required.

Events

One change and one input per user change, with the whole value; the children's own events stop at the group, so a listener on it never sees two events with differently typed detail.value.

When to use

• A question where several answers apply: interests, notification channels, days of the week.
• Up to about ten options people should see at once.

Do

• Ask one question in the label; each checkbox is one answer.
• Offer select-all when people often pick most of the options.

When not to use

• A single setting that takes effect the moment it changes: hy-switch.
• Options that do not answer one question: separate hy-checkbox elements, not a group.

Choice cards

The items can be cards instead of checkboxes: a hy-card with a value inside the group is a choice card — it draws its own stretched native checkbox, so a click anywhere on it toggles it, and the group owns the value, the form entries, the message line and required as with checkboxes. A group holds checkboxes or cards, not both.

Accessibility: your part

• Give each hy-checkbox a label that makes sense read on its own; name a choice card from its own heading (aria-labelledby) or aria-label.

Examples

Pick all that apply

<form>
  <hy-checkbox-group name="topics" label="Topics" helper-text="Pick all that apply" required>
    <hy-checkbox value="design" label="Design"></hy-checkbox>
    <hy-checkbox value="engineering" label="Engineering" state="checked"></hy-checkbox>
    <hy-checkbox value="research" label="Research"></hy-checkbox>
  </hy-checkbox-group>
</form>

With select all

<hy-checkbox-group name="notify" label="Notify me by" select-all>
  <hy-checkbox value="email" label="Email" state="checked"></hy-checkbox>
  <hy-checkbox value="sms" label="SMS"></hy-checkbox>
  <hy-checkbox value="push" label="Push"></hy-checkbox>
</hy-checkbox-group>

API

Properties

Property	Attribute	Type	Default	Description
label	label	string	''	The group's name, above the list. Or aria-label / aria-labelledby on the host.
helperText	helper-text	string	''	Help under the list; replaced by an error or warning message.
name	name	string	''	Form key: one entry per checked box. The children's own names are cleared.
value	—	string[]	[]	The checked children's values, in DOM order. A property (an array is no attribute); in markup, check the children with state="checked".
required	required	boolean	false	At least one box must be checked (valueMissing). Draws the required marker.
disabled	disabled	boolean	false	Disables every box and grays the group's own label and message line; re-enabling restores exactly what each box had. A <fieldset disabled> around the group does the same without setting this attribute (React HyCheckboxGroup follows the fieldset too).
size	size	'small' | 'medium' | 'large'	'medium'	Size of every box, over its own size.
orientation	orientation	'horizontal' | 'vertical'	'vertical'	vertical (default) or horizontal, which falls back to vertical below 30rem.
layout	layout	'block' | 'inline'	'block'	block (default) or inline (label on the left, list on the right).
error	error	boolean	false	Not accepted: every box paints the error, error-message shows once.
errorMessage	error-message	string	''	The error line. Setting it raises error.
warning	warning	boolean	false	Accepted but worth a look: every box paints the warning. Never invalid.
warningMessage	warning-message	string	''	The warning line. Setting it raises warning.
selectAll	select-all	boolean	false	Draws a "select all" box above the children, owned by the group.
selectAllLabel	select-all-label	string	'Select all'	The "select all" box's label.
ariaDescribedby	aria-describedby	string	''	Extra ids that describe the group, after its message line.
form	—	HTMLFormElement | null	—	—
validity	—	ValidityState | undefined	—	—
validationMessage	—	string	—	—

Events

Event	Detail	Description
change	—	The value changed by a user action. Detail: CheckboxGroupChangeDetail
input	—	Fired with every user change, as on the other form controls

Slots

Slot	Description
default	The hy-checkbox children (a wrapper element for columns works)

CSS Parts

Part	Description
base	The group's base wrapper
label	The group label
checkbox-list	The container for the checkboxes (the group role)
select-all	The "select all" box
helper-text	The helper text
error-message	The error message (shown while error is set)
warning-message	The warning message (shown while warning is set and error is not)
message-icon	The icon starting the error or warning message

CSS Custom Properties

The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.

Property	Default	Description
--hy-checkbox-group-foreground-danger-hover	var(--hy-foreground-danger-hover)	Required marker (*) color.
--hy-checkbox-group-foreground-danger-rest	var(--hy-foreground-danger-rest)	Error message text and icon color.
--hy-checkbox-group-foreground-warning-rest	var(--hy-foreground-warning-rest)	Warning message text and icon color.
--hy-checkbox-group-gap-layout-2xs	var(--hy-gap-layout-2xs)	Gap between the message icon and its text.
--hy-checkbox-group-label-column-width	—	Width of the label column in layout="inline" mode. No default — set on a wrapping container so stacked groups align.
--hy-checkbox-group-field-gap-form-sm	var(--hy-gap-form-sm)	Gap between the group's parts: the label, the list and the message line.
--hy-checkbox-group-stack-gap-form-sm	var(--hy-gap-form-sm)	Gap between stacked checkboxes (vertical). The rows are content-sized, so the group owns the rhythm.

Methods

setCustomValidity()

A custom validity message (a rule like "no more than three"); empty clears it.

focus()

Focuses the first enabled box.