HyToggle

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

An individual toggle button used within an hy-toggle-group. Represents a single selectable option that can be pressed (selected) or unpressed.

Key Features

• Pressed/unpressed visual state
• Prefix and suffix slots for icons
• Size and variant inherited from parent group
• Full keyboard and accessibility support

Accessibility Features

• Role switches between radio (single mode) and button (multiple mode)
• aria-checked or aria-pressed based on selection mode
• Focus delegation via delegatesFocus — parent group manages host tabindex
• High contrast mode support
• Reduced motion support

Examples

Basic usage within a toggle group

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

With icon

<hy-toggle value="bold">
  <hy-icon slot="prefix" name="bold"></hy-icon>
  Bold
</hy-toggle>

API

Properties

Property	Attribute	Type	Default	Description
value	value	string	''	Unique value for this toggle item. Used by the parent group to track selection.
pressed	pressed	boolean	false	Whether this toggle is currently pressed/selected. Managed by parent group.
disabled	disabled	boolean	false	Whether this toggle is disabled.
size	size	'small' | 'medium' | 'large'	'medium'	Size of the toggle button. Typically inherited from the parent group.
variant	variant	'neutral' | 'brand'	'neutral'	Visual variant (role). Typically inherited from the parent group.
emphasis	emphasis	'solid' | 'soft' | 'outlined'	'soft'	Visual chrome weight on top of the role. Typically inherited from the parent toggle group.
selectionMode	selection-mode	'single' | 'multiple'	'single'	Selection mode. Inherited from the parent toggle group.
autofocus	autofocus	boolean	false	Marks this toggle as the auto-focus target. Read by hy-dialog (and other overlay containers) on show to choose initial focus. Also focuses on first connect when used outside an overlay, mirroring native HTML autofocus but routed through JS so SSR'd HTML doesn't pull focus during hydration.

Slots

Slot	Description
default	Button content (text, icons, or both)
prefix	Content before the default slot (e.g. icon)
suffix	Content after the default slot

CSS Parts

Part	Description
base	The button element
prefix	Prefix slot wrapper
suffix	Suffix slot wrapper

CSS Custom Properties

Property	Description
--hy-toggle-border-radius	Border radius (all four corners; set by hy-toggle-group for connected appearance)
--hy-toggle-border-radius-top-start	Top-start corner radius override. Set per first/last-child by hy-toggle-group to compose connected button-group corners. Cascades through --hy-toggle-border-radius.
--hy-toggle-border-radius-top-end	Top-end corner radius override. See top-start.
--hy-toggle-border-radius-bottom-start	Bottom-start corner radius override. See top-start.
--hy-toggle-border-radius-bottom-end	Bottom-end corner radius override. See top-start.
--hy-toggle-text-transform	Text transform for toggle label
--hy-toggle-font-family	Font family override for toggle label
--hy-toggle-height-sm	Outer height for small size variant. Per-component override in the form-control height contract (see .claude/rules/control-heights.md). Default: var(--hy-control-height-sm)
--hy-toggle-height-md	Outer height for medium size variant. Default: var(--hy-control-height-md)
--hy-toggle-height-lg	Outer height for large size variant. Default: var(--hy-control-height-lg)
--hy-toggle-hover-duration	Transition duration for hover and focus state feedback
--hy-toggle-hover-easing	Transition easing for hover and focus state feedback

Methods

focus()

Sets focus on the underlying button element.

blur()

Removes focus from the underlying button element.