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.

Used inside <hy-menu> — it only means something as part of it.

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).

The check/minus glyph is the row's own (the icon family of the design system). Checked/indeterminate state is also announced via aria-checked on the item's button.

When not to use

• Exactly one option of a set active at a time: hy-menu-item-radio, with the same name on each.
• A row that runs a command or navigates: hy-menu-item.
• An option a form submits: hy-checkbox in the form.

Accessibility: your part

• Put related checkbox items in an hy-menu-group with a label, so the set is announced as one setting.
• Label the item with the option it turns on ("Word wrap"), not with an action ("Toggle word wrap").

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.
description	description	string	''	A second line under the label — forwarded to the inner hy-menu-item.
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 coloring.
size	size	'small' | 'medium'	'medium'	Density variant, forwarded to the inner hy-menu-item. Inside an hy-menu the menu's size wins (it writes this property).
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
trailing	Trailing indicator / shortcut hint.

CSS Custom Properties

The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.

Property	Default	Description
--hy-menu-item-checkbox-foreground-brand-rest	var(--hy-foreground-brand-rest)	Glyph color in the rest state.
--hy-menu-item-checkbox-foreground-default-disabled	var(--hy-foreground-default-disabled)	Glyph color when the host is 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).