Checkbox Group

Group independent checkbox choices and derive the aggregate selection state.

<hui-checkbox-group>View source View spec

Interactive

Try it

disabled, aria-label

Push

SMS

Markup

State

Events

<hui-checkbox-group id="playground-checkbox-group" aria-label="Notification preferences">
  <hui-checkbox name="notifications" value="email" checked>Email</hui-checkbox>
  <hui-checkbox name="notifications" value="push">Push</hui-checkbox>
  <hui-checkbox name="notifications" value="sms">SMS</hui-checkbox>
</hui-checkbox-group>

data-state: Waiting for enhancement

No component events yet.

Usage

Use hui-checkbox-group to semantically contain related independent hui-checkbox elements. It applies role="group" when no role is supplied and derives a group data-state from its members.

Do not use it for a single checkbox, mutually exclusive choices, or a binary setting. The group does not replace a visible group label; provide aria-label or aria-labelledby.

Anatomy

Host: hui-checkbox-group
Group semantics: role="group" (defaulted by the component)
Members: slotted hui-checkbox elements
Content: default slot
State mirror: host data-state="checked|unchecked|indeterminate"

Examples

Fixture exampleSource-backed

<section aria-labelledby="basic-h">
    <h2 id="basic-h">Basic</h2>
    <hui-checkbox name="notify" value="yes">
      <b>Email</b> me about updates
    </hui-checkbox>

    <hui-checkbox name="tos" value="accepted" checked>
      I accept the terms
    </hui-checkbox>

    <hui-checkbox name="waitlist" value="join" indeterminate>
      Join waitlist
    </hui-checkbox>

    <hui-checkbox name="locked" value="admin" disabled>
      Admin access
    </hui-checkbox>
  </section>

  <section aria-labelledby="group-h">
    <h2 id="group-h">Group</h2>
    <hui-checkbox-group id="toppings" aria-label="Toppings" name="toppings">
      <hui-checkbox name="toppings" value="avocado" checked>Avocado</hui-checkbox>
      <hui-checkbox name="toppings" value="bacon">Bacon</hui-checkbox>
      <hui-checkbox name="toppings" value="tomato">Tomato</hui-checkbox>
    </hui-checkbox-group>
  </section>

API reference

The group has no value-management prop of its own. It observes slotted hui-checkbox members and reacts to projection, member additions/removals, and member state events.

role: preserved when supplied; otherwise defaults to group.
aria-label / aria-labelledby: recommended accessible naming API.
data-state: derived state mirror; do not use it as the source of truth.

States and styling

State	Contract and styling guidance
Default / unchecked	No checked members; `data-state="unchecked"`.
Hover	Style the member checkbox, not the group state.
Active	Style the member checkbox, not the group state.
Focus	Focus remains on the native member input; preserve a visible member focus ring.
Checked	All members are checked; `data-state="checked"` when the group is non-empty.
Indeterminate	Mixed or indeterminate member state; `data-state="indeterminate"`.
Disabled	Each member owns its native disabled state; the group has no group-level disabled behavior.
Error	No built-in error state. Pair an `aria-invalid` convention and an associated error message at the application level.

State channel

Attributes are the source of truth. Style derived state with data-state, ARIA attributes, and the --hui-* token aliases.

Accessibility and keyboard support

Each member remains a native checkbox with its own label and form behavior. Use the group label to give the set an accessible name.

SSR and forms

Checkbox Group preserves source-of-truth attributes and accessible state in server-rendered light-DOM markup. Use stable IDs when the component generates relationships; client enhancement adds interaction without changing the public contract.

Code

<hui-checkbox-group aria-labelledby="toppings-label">
  <span id="toppings-label">Toppings</span>
  <hui-checkbox name="toppings" value="avocado">Avocado</hui-checkbox>
  <hui-checkbox name="toppings" value="bacon">Bacon</hui-checkbox>
  <hui-checkbox name="toppings" value="tomato">Tomato</hui-checkbox>
</hui-checkbox-group>

<hui-checkbox-group id="playground-checkbox-group" aria-label="Notification preferences">
  <hui-checkbox name="notifications" value="email" checked>Email</hui-checkbox>
  <hui-checkbox name="notifications" value="push">Push</hui-checkbox>
  <hui-checkbox name="notifications" value="sms">SMS</hui-checkbox>
</hui-checkbox-group>