HyMenuItemCheckbox

Usage examples on this page are written for Lit / plain HTML (<hy-menu-item-checkbox>). The same component ships as HyMenuItemCheckbox 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 checkable row inside an hy-menu. Composition wrapper around hy-menu-item that adds checked / indeterminate state, a leading check/minus glyph, and a change event.

Follows the same composition pattern as hy-color-slider → hy-slider: this element renders an inner hy-menu-item, forwards base props, listens to its select event to toggle state, and publishes its own change event. The inner select continues bubbling so the parent hy-menu sees the composite as the selected item (target retargeting).

When the consumer slots a leading icon, the default check/minus glyph is suppressed so the consumer icon takes precedence. Checked/indeterminate state is still announced via aria-checked on the host.

Examples

Checkable view options inside a menu group

<hy-menu-group label="View">
  <hy-menu-item-checkbox value="word-wrap" label="Word wrap" checked></hy-menu-item-checkbox>
  <hy-menu-item-checkbox value="minimap" label="Minimap"></hy-menu-item-checkbox>
</hy-menu-group>

Reacting to state changes

<hy-menu-item-checkbox value="word-wrap" label="Word wrap"></hy-menu-item-checkbox>
<script>
document.querySelector('hy-menu-item-checkbox').addEventListener('change', (e) => {
console.log(e.detail.checked, e.detail.value);
});
</script>

API

Properties

Property	Attribute	Type	Default	Description
checked	checked	boolean	false	Checked state.
indeterminate	indeterminate	boolean	false	Indeterminate state — renders a minus glyph.
value	value	string	''	Identifier used in select / change events.
label	label	string	''	Label text. When empty, the default slot is rendered.
shortcut	shortcut	string	''	Keyboard shortcut hint.
disabled	disabled	boolean	false	Disables the item — skipped in keyboard nav, no activation.
variant	variant	'default' | 'danger'	'default'	Visual variant — danger paints destructive colouring.
size	size	'small' | 'medium'	'medium'	Density variant, forwarded to the inner hy-menu-item.
active	active	boolean	false	Whether this item currently owns the tab stop in its menu's roving tabindex. Reflected so the modal focus trap can match hy-menu-item-checkbox[active]. Managed by the parent hy-menu.

Events

Event	Detail	Description
change	—	{ checked, indeterminate, value, reason } when the checked state changes.
select	—	Relayed from inner hy-menu-item; target retargets to this composite.

Slots

Slot	Description
default	Default label content when label prop is empty.
leading	Overrides the default check/minus glyph.
trailing	Trailing indicator / shortcut hint.

CSS Custom Properties

Property	Description
--hy-menu-item-checkbox-glyph-color	Glyph color in the rest state. Defaults to --hy-foreground-brand-rest.
--hy-menu-item-checkbox-glyph-color-disabled	Glyph color when the host is disabled. Defaults to --hy-foreground-default-disabled.

Methods

focus()

Imperative focus — forwards to the inner hy-menu-item.

setTabIndex()

Called by parent hy-menu roving-tabindex logic. Forwards to the inner hy-menu-item and mirrors the tab-stop state on the host's reflected [active] attribute (focus trap discovery + CSS hook).