Picker Menu

import "@taprootio/espalier/pickers/menu";

label

label has a default value of "".

An accessible label for the listbox, typically passed from the parent picker's placeholder or form-item label.

multi-select

multi-select has a default value of false.

Whether the menu is in multi or single selection mode.

Single selection:

Multi-selection:

loading

loading has a default value of false.

When true, the menu shows a "Searching..." indicator instead of the item list. Used by typeahead mode during remote fetch.

empty-message

empty-message has a default value of "".

Message to display when the item list is empty (e.g. "No matches"). When empty string, no message is shown.

resetHighlight

Reset the highlight index, clearing any visual highlight. Called when the menu is opened to start fresh.

getHighlightedElement

Returns the esp-picker-item DOM element at the current highlightIndex, or null if no element is rendered at that index. Used by the parent picker to set ariaActiveDescendantElement.

requestDismiss

Request an owner-coordinated close, with a standalone self-close fallback.

positionSelf

Position the picker menu above or below the given element depending on whether or not there is more room above or below the element. Uses the Popover API to render in the top layer, escaping any ancestor overflow: hidden clipping.

updatePosition

Lightweight position update for scroll tracking. Only updates the coordinates — and recalculates max-height only when the viewport height itself has changed (e.g. mobile keyboard), not on every scroll tick where only the trigger's rect shifts.

hideMenu

Hide the picker menu popover.

doKeyboardNav

Used to perform keyboard actions on the menu. ArrowDown and ArrowUp change the focused item in the menu. Enter toggles selection of the focused item.

Focus the input and use ArrowDown, ArrowUp, and Enter to interact with the menu.

esp-picker-menu-selection-changed

esp-picker-menu-selection-changed is of type CustomEvent<Array<PickerItem>>.

Emitted when the user changes the selected item(s). If there are initially selected items, emitted on first update.

esp-picker-menu-close-requested

esp-picker-menu-close-requested is of type CustomEvent<Array<PickerItem>>.

Emitted when the menu should close after a single-select choice. Bubbles and is composed so parent pickers can observe it across shadow boundaries.

esp-picker-menu-dismiss-requested

esp-picker-menu-dismiss-requested is of type CustomEvent<void>.

Emitted when the mobile dismiss affordance requests a close without changing selection. Bubbles, is composed, and is cancelable so an owner can coordinate state before closing; an uncanceled request closes the standalone menu directly.

esp-picker-menu-range-changed

esp-picker-menu-range-changed is of type CustomEvent<{ first: number; last: number; items: Array<PickerItem> }>.

Emitted when the virtualized visible item range changes. Standalone menus do not render owner chrome. Call the public requestDismiss() method from a consumer-provided close affordance. updatePosition() repositions an already-open standalone menu but does not open one; standalone consumers retain explicit ownership of that lifecycle.

--esp-color-picker-bg

The background color of the picker menu items.

--esp-color-picker-bg-alt

The alternate background color for picker menu items.

--esp-color-picker-bg-hover

The hover background color of regular picker menu items.

--esp-color-picker-bg-alt-hover

The hover background color of alternating picker menu items.