ToggleGroup

At a glance

• API — qzToggleGroup type="single" | "multiple" with qzToggleItem
• Focus — One tab stop; arrows move focus without selecting; disabled items are skipped
• ARIA — role="group" with per-item aria-pressed (not a radio group)
• Forms — ToggleGroupControlDirective: scalar/null (single) or array (multiple)
• CLI — pnpm quartz add toggle-group

Imports

import { ToggleGroupDirective, ToggleItemDirective } from '@quartz-headless/primitives';
import { ToggleGroupControlDirective } from '@quartz-headless/primitives/forms'; // optional

Minimal template

<div
  qzToggleGroup
  [(value)]="align"
  aria-label="Text alignment"
  (valueChangeCommitted)="saved($event)"
>
  <button qzToggleItem="left">Left</button>
  <button qzToggleItem="center">Center</button>
  <button qzToggleItem="right" [qzToggleItemDisabled]="true">Right</button>
</div>

Inputs and outputs

Selection behaviour

• Single: pressing an item selects it (replacing the previous one); pressing the pressed item clears it unless allowDeselection is false. Empty = null.
• Multiple: pressing toggles membership and emits a new array in press order; empty = []. null is treated as empty.
• Controlled: aria-pressed always reflects value; the mode decides how it is read (an array in single mode, or a scalar in multiple mode, shows nothing pressed).
• Dynamic items: removing a pressed item or reordering never rewrites value (no phantom updates); a value with no matching item simply shows nothing pressed.
• A disabled item or group ignores pointer and keyboard activation.

Keyboard

Moving focus never changes the selection.

Accessibility

The group is role="group": give it an accessible name (aria-label/aria-labelledby). Items are buttons with aria-pressed. A ToggleGroup is deliberately not a RadioGroup: there is no required selection and no arrow-selects behaviour. As of 0.11 the group no longer renders aria-orientation (it is not allowed on role="group"; axe flags it) — use data-qz-orientation.

Angular Forms

ToggleGroupControlDirective. Single: the item value or null. Multiple: an array. null / undefined (e.g. reset()) show nothing pressed in both modes and the control keeps that null until the user commits again. writeValue is silent, onChange fires once per activation, touched fires when focus leaves the group, setDisabledState disables the group.

Styling hooks

Group: data-qz-orientation, data-qz-disabled. Item: data-qz-state="on|off", data-qz-disabled, aria-pressed.

Known limitations

Buttons only; no vertical RTL special-casing beyond the axis keys; the single-mode value type is the item value type (arrays are not supported as single values).

Migration from 0.10

Additive: allowDeselection (default true keeps the old deselect-on-repress behaviour), valueChangeCommitted, isDisabled, setFormDisabled(), the Forms adapter. Behaviour changes: isPressed is now mode-aware (previously any array value pressed items even in single mode) and the redundant aria-orientation attribute was removed from the group.

Playground

Live examples