HyToggleGroup

Usage examples on this page are written for Lit / plain HTML (<hy-toggle-group>). The same component ships as HyToggleGroup 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 form-associated container component that manages a group of toggle buttons. Provides centralized selection state management, keyboard navigation, accessibility features, and form integration via ElementInternals API.

Supports two selection modes:

• Single mode (default): Radio-group pattern — one toggle selected at a time. Arrow keys move focus and select. Uses role="radiogroup".
• Multiple mode: Toolbar pattern — multiple toggles can be selected. Arrow keys move focus only. Space/Enter toggles selection. Uses role="toolbar".

Form Integration

Implements Form-Associated Custom Elements API via ElementInternals. In single mode, submits a single string value. In multiple mode, submits pipe-delimited values (e.g. "bold|italic").

Keyboard Navigation

• Single mode: Arrow keys move focus and auto-select. Space selects focused item.
• Multiple mode: Arrow keys move focus only. Space/Enter toggles focused item.
• Home/End: Move focus to first/last item.
• Tab: Enters/exits the group (roving tabindex).

Examples

Basic single selection

<hy-toggle-group value="center" label="Text alignment">
  <hy-toggle value="left">Left</hy-toggle>
  <hy-toggle value="center">Center</hy-toggle>
  <hy-toggle value="right">Right</hy-toggle>
</hy-toggle-group>

Inline layout

<div style="--hy-toggle-group-label-column-width: 6rem;">
  <hy-toggle-group layout="inline" label="Alignment" value="left">
    <hy-toggle value="left">Left</hy-toggle>
    <hy-toggle value="center">Center</hy-toggle>
    <hy-toggle value="right">Right</hy-toggle>
  </hy-toggle-group>
</div>

API

Properties

Property	Attribute	Type	Default	Description
selectionMode	selection-mode	'single' | 'multiple'	'single'	Selection mode: 'single' (radio-like) or 'multiple' (checkbox-like).
value	value	string	''	The currently selected value(s). In single mode: a single string value. In multiple mode: pipe-delimited string (e.g. "bold|italic").
orientation	orientation	'horizontal' | 'vertical'	'horizontal'	Layout direction of the toggle items.
size	size	'small' | 'medium' | 'large'	'medium'	Size of all toggle items in the group.
variant	variant	'neutral' | 'brand'	'neutral'	Visual style (role) of the toggle items.
emphasis	emphasis	'solid' | 'soft' | 'outlined'	'soft'	Visual chrome weight propagated to every child toggle. Orthogonal to variant (role).
disabled	disabled	boolean	false	Disables all toggle items in the group.
required	required	boolean	false	At least one value must be selected for form validation.
disallowEmpty	disallow-empty	boolean	false	Prevents deselecting the last selected item.
name	name	string	''	Form submission name.
label	label	string	''	Visible group label (also sets the accessible name via aria-labelledby).
helpText	help-text	string	''	Helper text below the toggle list. Hidden when errorMessage is shown.
errorMessage	error-message	string	''	Error message below the toggle list — shown when invalid.
invalid	invalid	boolean	false	Visually marks the group as invalid.
layout	layout	'block' | 'inline'	'block'	Row layout: block (default) stacks label above the toggle list; inline puts label on the left and list on the right. Helper/error always sit under the list (col 2–end), never under the label. Set --hy-toggle-group-label-column-width on a wrapping container so stacked groups align.
fullWidth	full-width	boolean	false	Stretch the group to fill its container's inline size, distributing the toggle segments equally (flex: 1 each) — a true segmented control rather than a content-width strip. Off by design; opt in for full-bleed rows.
loop	loop	boolean	true	Whether keyboard navigation wraps around at the edges.
form	—	HTMLFormElement | null	—	Returns the form element this group is associated with.
validity	—	ValidityState	—	Returns the ValidityState for this group.
validationMessage	—	string	—	Returns the validation message for this group.

Events

Event	Detail	Description
change	—	Fired when selection changes. Detail: { selectedValues: string[], reason: 'user' | 'programmatic', name: string }
input	—	Standard form input event

Slots

Slot	Description
default	hy-toggle elements

CSS Parts

Part	Description
base	Outer wrapper containing label, toggle list, and helper/error text
label	The visible group label element
toggle-list	The container that holds the toggle items (role=radiogroup|toolbar)
helper-text	Helper text below the list
error-message	Error message below the list

CSS Custom Properties

Property	Description
--hy-toggle-group-child-radius	Border radius for child toggle items (defaults to --hy-radius-action-md, the same family hy-toggle reads)
--hy-toggle-group-gap-print	Gap between toggle items in print
--hy-toggle-group-label-column-width	Width of the label column in layout="inline" mode. No default — set on a wrapping container so stacked groups align.

Methods

checkValidity()

Checks validity against constraints.

reportValidity()

Checks validity and shows browser validation UI if invalid.

setCustomValidity()

Sets a custom validation message.

focus()

Sets focus on the selected toggle, or the first toggle if none selected.