HyMenuItemRadio

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

Grouping

Radios that share a name in the same menu form one set: checking one unchecks the others, wherever they sit in that menu — a hy-menu-group neither creates the set nor narrows it (its role="radiogroup" is semantics only). A submenu is a menu of its own, so its radios never exclude the parent menu's. The menu re-emits the pick as an aggregated change with { selectedValue, name, reason } — matching hy-radio-group's API.

Radios without a name are standalone: each checks on activation, none unchecks another, and the menu emits no change for them.

When not to use

• Options that switch on and off independently: hy-menu-item-checkbox.
• A command with no lasting selection: hy-menu-item.
• A choice a form submits: hy-radio-group or hy-select.

Accessibility: your part

• Wrap each set in hy-menu-group role="radiogroup" with a label that names the choice.
• Keep exactly one item of each group checked.

Examples

Radio rows sharing a name

<hy-menu-item-radio name="zoom" value="zoom-50" label="50%"></hy-menu-item-radio>
<hy-menu-item-radio name="zoom" value="zoom-100" label="100%" checked></hy-menu-item-radio>
<hy-menu-item-radio name="zoom" value="zoom-150" label="150%"></hy-menu-item-radio>

In a labeled section

<hy-menu-group label="Density" role="radiogroup">
  <hy-menu-item-radio name="density" value="compact" label="Compact"></hy-menu-item-radio>
  <hy-menu-item-radio name="density" value="comfort" label="Comfort" checked></hy-menu-item-radio>
</hy-menu-group>

API

Properties

Property	Attribute	Type	Default	Description
checked	checked	boolean	false	Checked state.
value	value	string	''	Identifier used in select / change events.
name	name	string	''	Group identifier. Radios sharing a name in one menu exclude one another — the parent hy-menu clears the others on selection and aggregates the change as a menu-level change event. Groups play no part. Empty: a standalone radio.
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.
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-radio[active]. Managed by the parent hy-menu.

Events

Event	Detail	Description
change	—	{ checked, value, name, reason } when this radio toggles. Stops at the parent hy-menu, which re-emits an aggregated change.
select	—	Relayed from inner hy-menu-item.

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-radio-foreground-brand-rest	var(--hy-foreground-brand-rest)	Glyph color in the rest state.
--hy-menu-item-radio-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).