`<bmx-menu-item>`

One entry of a bmx-menu, written in markup rather than passed as data. It renders nothing at all: the menu reads these elements once, turns them into the same array its items property takes, and draws the menu itself.

10 properties · 0 events · 0 methods · 0 parts

Example

Column to the left

Written in markup rather than passed as data — the menu reads these once and draws the list itself. A nested bmx-menu-item becomes a submenu, and one with no label takes its own text.

Show markup

<div class="row">
  <bmx-button id="ex-menu-item-trigger" haspopup="menu" variant="outline" tone="neutral">Insert</bmx-button>
  <bmx-menu trigger="#ex-menu-item-trigger" label="Insert">
    <bmx-menu-item value="row" label="Row above" shortcut="⌥⌘I"></bmx-menu-item>
    <bmx-menu-item value="column">Column to the left</bmx-menu-item>
    <bmx-menu-item separator></bmx-menu-item>
    <bmx-menu-item label="Chart">
      <bmx-menu-item value="bar" label="Bar"></bmx-menu-item>
      <bmx-menu-item value="line" label="Line"></bmx-menu-item>
      <bmx-menu-item value="pie" label="Pie" disabled></bmx-menu-item>
    </bmx-menu-item>
    <bmx-menu-item separator></bmx-menu-item>
    <bmx-menu-item value="clear" label="Clear the sheet" danger></bmx-menu-item>
  </bmx-menu>
  <span class="note">
    Written in markup rather than passed as data — the menu reads these once and draws the list itself. A nested
    <code>bmx-menu-item</code> becomes a submenu, and one with no <code>label</code> takes its own text.
  </span>
</div>

The same arrangement as bmx-option, and for a related reason. A menu draws its items inside a surface in the browser's top layer; an element sitting in the light DOM cannot be in two places at once, so either the menu renders the item or the author does - and an author rendering their own items gets none of the roving tabindex, the typeahead or the cascade that the menu exists to provide.

So this is the declarative front door, for markup a person writes by hand and for the plain-HTML case the library promises to support. Anything generated from data belongs in the items property, which is also the only way to reach icon.

The two are not mixed: a menu with a non-empty items property ignores its children entirely, because two sources of truth for one list is how a menu ends up showing something the application does not think is there.

Submenus nest. A bmx-menu-item containing other bmx-menu-item elements is a parent, and its children become its submenu - which is the shape a person writing HTML expects, and it needs no separate wrapper element to express.

<bmx-menu trigger="#file">
  <bmx-menu-item value="new" label="New"></bmx-menu-item>
  <bmx-menu-item label="Open recent">
    <bmx-menu-item value="a" label="Accounts.xlsx"></bmx-menu-item>
  </bmx-menu-item>
  <bmx-menu-item separator></bmx-menu-item>
  <bmx-menu-item value="close" label="Close" danger></bmx-menu-item>
</bmx-menu>

Properties

Property	Attribute	Type	Default	Description
`checked`	`checked`	`boolean`	`false`	The state of a `checkbox` or `radio` item.
`danger`	`danger`	`boolean`	`false`	Paint it in the danger tone.
`description`	`description`	`string`	—	Secondary text, under the label.
`disabled`	`disabled`	`boolean`	`false`	Whether it can be chosen.
`group`	`group`	`string`	—	Which radio set this belongs to. Radio items sharing one are exclusive.
`kind`	`kind`	`'action' \| 'checkbox' \| 'radio'`	`'action'`	What kind of control this is: an action, or something that carries a state.
`label`	`label`	`string`	—	What the user reads. Falls back to the element's own text.
`separator`	`separator`	`boolean`	`false`	Draw a divider instead of an item. Every other property is ignored.
`shortcut`	`shortcut`	`string`	—	A keyboard hint, right-aligned. Display only - the menu does not bind it.
`value`	`value`	`string`	—	Reported in the menu's selection event. Falls back to the label.

Slots

Slot	Description
`(default)`	The item's label, when the `label` property is not set. Nested `bmx-menu-item` elements here become the item's submenu.