HyMenuItem

Usage examples on this page are written for Lit / plain HTML (<hy-menu-item>). The same component ships as HyMenuItem 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 row inside an hy-menu. Renders a role="menuitem" button (or an <a> when href is set) with optional leading icon, trailing indicator, and shortcut hint.

The item emits select on activation. When href is set, the event fires synchronously before navigation; calling event.preventDefault() on the select event cancels the link follow. This matches native <a> + click semantics and lets consumers gate navigation (e.g. unsaved changes prompts).

Focus is driven by the parent hy-menu via roving tabindex on the shadow button — the item does not manage its own focusedness.

Examples

Items with shortcut hints and a danger action

<hy-menu-item value="cut" label="Cut" shortcut="⌘X"></hy-menu-item>
<hy-menu-item value="copy" label="Copy" shortcut="⌘C"></hy-menu-item>
<hy-menu-item value="paste" label="Paste" shortcut="⌘V" disabled></hy-menu-item>
<hy-menu-item value="delete" label="Delete" variant="danger"></hy-menu-item>

Link item with a leading icon

<hy-menu-item value="docs" href="/docs" label="Documentation">
  <hy-icon slot="leading" name="information" decorative></hy-icon>
</hy-menu-item>

API

Properties

Property	Attribute	Type	Default	Description
value	value	string	''	Identifier used in the select event detail.
label	label	string	''	Label text. When empty, the default slot is rendered instead.
shortcut	shortcut	string	''	Keyboard shortcut hint (plain string; platform formatting is the consumer's job).
disabled	disabled	boolean	false	Disables the item — skipped in keyboard navigation, no select emission.
variant	variant	'default' | 'danger'	'default'	Visual variant. danger signals a destructive action.
size	size	'small' | 'medium'	'medium'	Density variant. small matches hy-list size="small" density for overflow menus / compact triggers. Usually set by a parent hy-menu or hy-menu-button rather than per-item.
href	href	string	''	When set, renders as an anchor. select still fires before navigation.
target	target	string	''	Anchor target — only meaningful when href is set.
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[active] and so consumer CSS can highlight the current item. Managed by the parent hy-menu — do not set manually.

Events

Event	Detail	Description
select	—	{ value, item, originalEvent } — bubbles to parent menu.

Slots

Slot	Description
default	Default label content when the label prop is empty.
leading	Leading icon or avatar.
trailing	Trailing indicator (check, chevron, badge). The shortcut text takes this spot when no trailing slot is provided.

CSS Parts

Part	Description
base	The interactive button/anchor element.
prefix	The leading slot container.
label	The label text container.
suffix	The trailing slot container.
shortcut	The shortcut hint text.

CSS Custom Properties

Property	Description
--hy-menu-item-background-rest	—
--hy-menu-item-background-hover	—
--hy-menu-item-background-danger-tint-hover	—
--hy-menu-item-foreground-default-rest	—
--hy-menu-item-foreground-subtle-rest	—
--hy-menu-item-foreground-danger-rest	—
--hy-menu-item-foreground-disabled	—
--hy-menu-item-gap	—
--hy-menu-item-padding-block	—
--hy-menu-item-padding-inline	—
--hy-menu-item-radius	—

Methods

focus()

Imperative focus — called by the parent menu's roving tabindex logic.

setTabIndex()

Sets the internal button/anchor's tabindex AND mirrors the tab-stop state to the host's reflected [active] attribute so the focus trap can see which item is the current tab stop. Called by the parent menu's roving-tabindex controller.