# auro-menu The `auro-menu` element provides users a way to select from a list of options. ## Properties | Property | Attribute | Modifiers | Type | Default | Description | |----------------------------|----------------------------|-----------|-----------------------|-------------|--------------------------------------------------| | [allowDeselect](#allowDeselect) | `allowDeselect` | | `boolean` | false | Allows deselecting an already selected option when clicked again in single-select mode. | | [currentLabel](#currentLabel) | | readonly | `string` | | | | [disabled](#disabled) | `disabled` | | `boolean` | | When true, the entire menu and all options are disabled. | | [hasLoadingPlaceholder](#hasLoadingPlaceholder) | `hasLoadingPlaceholder` | | `boolean` | | Indicates whether the menu has a loadingIcon or loadingText to render when in a loading state. | | [index](#index) | | | `number` | | | | [items](#items) | | readonly | `HTMLElement[]` | | | | [loading](#loading) | `loading` | | `boolean` | false | When true, displays a loading state using the loadingIcon and loadingText slots if provided. | | [matchWord](#matchWord) | `matchword` | | `string` | "undefined" | Specifies a string used to highlight matched string parts in options. | | [multiSelect](#multiSelect) | `multiselect` | | `boolean` | false | When true, the selected option can be multiple options. | | [noCheckmark](#noCheckmark) | `nocheckmark` | | `boolean` | false | When true, selected option will not show the checkmark. | | [optionActive](#optionActive) | `optionactive` | | `object` | "undefined" | Specifies the current active menuOption. | | [optionSelected](#optionSelected) | `optionSelected` | | `object` | "undefined" | An array of currently selected menu options, type `HTMLElement` by default. In multi-select mode, `optionSelected` is an array of HTML elements. | | [options](#options) | | readonly | `array` | | Available menu options | | [selectAllMatchingOptions](#selectAllMatchingOptions) | `selectAllMatchingOptions` | | `boolean` | false | When true, selects all options that match the provided value/key when setting value and multiselect is enabled. | | [selectedOption](#selectedOption) | | readonly | `HTMLElement \| null` | | Gets the first selected option, or null if none. | | [selectedOptions](#selectedOptions) | | readonly | `HTMLElement[]` | | Gets the currently selected options. | | [value](#value) | `value` | | `string` | "undefined" | The value of the selected option. In multi-select mode, this is a JSON stringified array of selected option values. | ## Methods | Method | Type | Description | |----------------------|-------------------------------|--------------------------------------------------| | [reset](#reset) | `(): void` | Resets the menu to its initial state.
This is the only way to return value to undefined. | | [updateActiveOption](#updateActiveOption) | `(option: HTMLElement): void` | Updates the currently active option in the menu.

**option**: The option to set as active. | ## Events | Event | Type | Description | |-------------------------------|--------------------------------------------------|--------------------------------------------------| | `auroMenu-activatedOption` | `CustomEvent` | Notifies that a menuoption has been made `active`. | | `auroMenu-customEventFired` | `CustomEvent` | Notifies that a custom event has been fired. | | `auroMenu-loadingChange` | `CustomEvent<{ loading: boolean; hasLoadingPlaceholder: boolean; }>` | Notifies when the loading attribute is changed. | | `auroMenu-optionsChange` | `CustomEvent<{ options: any; }>` | | | `auroMenu-selectValueFailure` | `CustomEvent` | Notifies that an attempt to select a menuoption by matching a value has failed. | | `auroMenu-selectValueReset` | `CustomEvent` | Notifies that the component value has been reset. | | `auroMenu-selectedOption` | `CustomEvent` | Notifies that a new menuoption selection has been made. | ## Slots | Name | Description | |---------------|---------------------------------------------| | | Slot for insertion of menu options. | | [loadingIcon](#loadingIcon) | Icon to show while loading attribute is set | | [loadingText](#loadingText) | Text to show while loading attribute is set | # auro-menuoption The `auro-menuoption` element provides users a way to define a menu option. ## Properties | Property | Attribute | Modifiers | Type | Default | Description | |---------------|------------|-----------|-----------|---------|--------------------------------------------------| | [disabled](#disabled) | `disabled` | | `boolean` | false | When true, disables the menu option. | | [iconTag](#iconTag) | | | `string` | | | | [isActive](#isActive) | | readonly | `boolean` | | Returns whether the menu option is currently active and selectable.
An option is considered active if it is not hidden, not disabled, and not static. | | [key](#key) | `key` | | `string` | | Allows users to set a unique key for the menu option for specified option selection. If no key is provided, the value property will be used. | | [selected](#selected) | `selected` | | `boolean` | false | Specifies that an option is selected. | | [tabIndex](#tabIndex) | `tabIndex` | | `number` | | Specifies the tab index of the menu option. | | [unsubscribe](#unsubscribe) | | | | null | | | [value](#value) | `value` | | `string` | | Specifies the value to be sent to a server. | ## Methods | Method | Type | Description | |-----------------------|-------------------------------|--------------------------------------------------| | [attachTo](#attachTo) | `(service: Object): void` | Attaches this menu option to a menu service and subscribes to its events.
This method enables the option to participate in menu selection and highlighting logic.

**service**: The menu service instance to attach to. | | [bindEvents](#bindEvents) | `(): void` | Sets up event listeners for user interaction with the menu option.
This function enables click and mouse enter events to trigger selection and highlighting logic. | | [handleMenuChange](#handleMenuChange) | `(event: Object): void` | Handles changes from the menu service and updates the option's state.
This function synchronizes the option's properties and selection/highlight state with menu events.

**event**: The event object from the menu service. | | [setInternalSelected](#setInternalSelected) | `(isSelected: boolean): void` | Updates the internal selected state of the menu option bypassing 'updated' and triggers custom events if selected.
This function ensures the option's selection state is synchronized with menu logic and notifies listeners.

**isSelected**: Whether the option should be marked as selected. | | [setSelected](#setSelected) | `(isSelected: boolean): void` | Sets the selected state of the menu option.
This function updates whether the option is currently selected.

**isSelected**: Whether the option should be marked as selected. | | [updateActive](#updateActive) | `(isActive: boolean): void` | Updates the active state and visual highlighting of the menu option.
This function toggles the option's active status and applies or removes the active CSS class.

**isActive**: Whether the option should be marked as active. | ## Events | Event | Type | |----------------------------|---------------------| | `auroMenuOption-click` | `CustomEvent` | | `auroMenuOption-mouseover` | `CustomEvent` | ## Basic
Stops Price Duration Departure Arrival
See code ```html Stops Price Duration Departure Arrival ``` ## Property & Attribute Examples ### Deselect Option When set, the `allowDeselect` attribute allows the user to click on a selected menu option again to deselect it when the menu is not in multi-select mode. When the menu is in multi-select mode, this attribute has no effect and the user will be able to deselect the last remaining selected option.
Stops Price Duration Departure Arrival
See code ```html Stops Price Duration Departure Arrival ``` ### Disabled The `auro-menu` element with `disabled` will mark all `auro-menuoption` elements as disabled.
New tab New window Open file Open location
Close window Close tab Save page as...
Share
Print
See code ```html New tab New window Open file Open location
Close window Close tab Save page as...
Share
Print ``` #### Single Disabled Option The `auro-menuoption` element supports the placement of the `disabled` attribute per option. A fully disabled list would be managed in an outer wrapping drop down menu element.
New tab New window Open file Open location
Close window Close tab Save page as...
Share
Print
See code ```html New tab New window Open file Open location
Close window Close tab Save page as...
Share
Print ``` ### Keys When setting the `value` property, matches are actually performed on the value of the `key` property of the `auro-menuoption` and not the `value` property. By default, the value of `key` is equal to the value of the `value` property. However, for advanced use cases, the `key` value can be overriden to allow for more specific matches. In the below example, there is a list of "popular" options at the top, with the same values repeated underneath. To allow more specific selections, we can add a `key` attribute to the top options to allow them to be more specifically selected, or to prevent them from interfering with matches on the lower options. In the below example, setting the value of the menu `'stops'` will select the bottom-most option with the value `'stops'`, and setting the value of menu to `'stops-top'` will select the top-most option with the value `'stops'` since the key now differs from the value. In either case, the resulting value of the menu will be `'stops'` because the resulting value of the menu is based on the `value` property and not the `key` property. Due to a limitation with Lit change detection to the `value` property, if multiple options with the same exist and one is selected, you must first clear the current value before attempting to select another option with the same value, even if the keys are unique. See code example below. _Note: Since the value passed to the `value` property when programmatically setting it is overwritten with the proper derived value once the menu has updated, note that it will take one lifecycle before the `value` property is updated to the value that represents the actual menu state._
Call `menu.value = 'stops-top'` Call `menu.value = 'stops'` Stops Price
Duration Departure Arrival Stops Price

See code ```html Call `menu.value = 'stops-top'` Call `menu.value = 'stops'` Stops Price
Duration Departure Arrival Stops Price

``` ```js export function initKeysExample() { const menu = document.getElementById('keys-menu'); const stopsButton = document.getElementById('stopsButton'); const stopsTopButton = document.getElementById('stopsTopButton'); const output = document.getElementById('output'); const createConsoleEntry = (message) => { const node = document.createElement('span'); node.innerHTML = message; output.appendChild(node); output.appendChild(document.createElement('br')); }; const resetConsole = () => { output.innerHTML = ''; }; const updateMenuValue = (value) => { resetConsole(); createConsoleEntry(`Setting menu.value: "${value}"`); menu.value = ''; menu.value = value; createConsoleEntry(`menu.value before next lifecycle: "${menu.value}"`); setTimeout(() => { createConsoleEntry(`menu.value after lifecycle: "${menu.value}"`); }); }; stopsButton.addEventListener('click', () => { updateMenuValue('stops'); }); stopsTopButton.addEventListener('click', () => { updateMenuValue('stops-top'); }); }; ``` ### Loading While content is loading, the menu can either remain empty or display a loading placeholder
Toggle Loading
Spinner + Text Text Only Spinner Only None
Loading... Stops Price Duration Departure Arrival Loading... Stops Price Duration Departure Arrival Stops Price Duration Departure Arrival Stops Price Duration Departure Arrival
See code ```html Toggle Loading
Spinner + Text Text Only Spinner Only None
Loading... Stops Price Duration Departure Arrival Loading... Stops Price Duration Departure Arrival Stops Price Duration Departure Arrival Stops Price Duration Departure Arrival
``` ```js export function auroMenuLoadingExample() { document.querySelector("#loadingExampleToggleButton").addEventListener("click", () => { document.querySelectorAll("#loadingExampleTable auro-menu").forEach(menu => menu.toggleAttribute("loading")); }); } ``` ### Match Word Use the `matchWord` attribute to highlight string parts of each menuoption that are equal to `matchWord`. The matching algorithm is case insensitive (e.g., `n` matches `N`).
Enter a value to match in the menu
Stops Price Duration Departure Apples Oranges Peaches Arrival
See code ```html Enter a value to match in the menu
Stops Price Duration Departure Apples Oranges Peaches Arrival ``` ```js function updateMatch() { let matchWordMenu = document.querySelector('#matchWordMenu'); matchWordMenu.matchWord = matchWordInput.value; } export function auroMenuMatchWordExample() { let matchWordInput = document.querySelector('#matchWordInput'); matchWordInput.addEventListener('keyup', updateMatch); } ``` ### Multi-Select The `auro-menu` supports a multi-select option. To use, place the `multiselect` attribute on the `` element tag or update the `multiselect` property programmatically. In multi-select mode, the `value` property will always return a valid JSON string that contains an array of selected values, e.g. `'["stops","duration","arrival"]'`, when accessed. The value of the menu may be set via multiple methods when in multi-select mode: - Programmatically or via attribute by passing a valid JSON string that can be parsed using `JSON.parse`. - Programmatically or via attribute by passing a single matching value in a string, e.g. `"stops"`. - Programmatically by passing an array of string values, e.g. `["stops","duration","arrival"]`. _Note: Other methods of setting the value may work but are not officially supported and may stop working unexpectedly._
Stops Price Duration Departure Arrival
See code ```html Stops Price Duration Departure Arrival ``` ### No Checkmark Applying the `noCheckmark` attribute will prevent the check icon from being shown on the selected option. The left padding to reserve space for the checkmark is also removed.
Stops Price Duration
Apples Oranges Pears Grapes Kiwi
Person Woman Man Camera TV
Departure Arrival
Cars Trucks Boats Planes Motorcycles
See code ```html Stops Price Duration
Apples Oranges Pears Grapes Kiwi
Person Woman Man Camera TV
Departure Arrival
Cars Trucks Boats Planes Motorcycles ``` ### Select All Matching Options Use the `selectAllMatchingOptions` attribute to enable selecting all options with matching keys when `value` is set programmatically. If not set, only the first matching option will be selected.

With selectAllMatchingOptions enabled:

Set menu.value to 'stops' Reset Menu Stops Price
Duration Departure Arrival Stops Price


Without selectAllMatchingOptions enabled:

Set menu.value to 'stops' Reset Menu Stops Price
Duration Departure Arrival Stops Price
See code ```html

With selectAllMatchingOptions enabled:

Set menu.value to 'stops' Reset Menu Stops Price
Duration Departure Arrival Stops Price


Without selectAllMatchingOptions enabled:

Set menu.value to 'stops' Reset Menu Stops Price
Duration Departure Arrival Stops Price ``` ```js export const initSelectAllMatchingOptionsExample = () => { const selectAllBtn = document.getElementById('selectAllBtn'); const selectAllMenu = document.getElementById('selectAllMenu'); const selectFirstBtn = document.getElementById('selectFirstBtn'); const selectFirstMenu = document.getElementById('selectFirstMenu'); const resetAllBtn = document.getElementById('resetAllBtn'); const resetFirstBtn = document.getElementById('resetFirstBtn'); selectAllBtn.addEventListener('click', () => { selectAllMenu.value = 'stops'; }); resetAllBtn.addEventListener('click', () => { selectAllMenu.reset(); }); selectFirstBtn.addEventListener('click', () => { selectFirstMenu.value = 'stops'; }); resetFirstBtn.addEventListener('click', () => { selectFirstMenu.reset(); }); }; ``` ### Preselect Option The `auro-menu` element supports a pre-selected option via the `selected` attribute on the `auro-menuoption` element.
New tab New window Open file Open location
Close window Close tab Save page as...
Share
Print
See code ```html New tab New window Open file Open location
Close window Close tab Save page as...
Share
Print ``` ## Common Usage Patterns & Functional Examples ### Scroll When setting the `max-height` of `auro-menu`, all of the overflowing content can be accessed via a scrollbar.
Stops Price Duration
Apples Oranges Pears Grapes Kiwi
Person Woman Man Camera TV
Departure Arrival
Cars Trucks Boats Planes Motorcycles
See code ```html Stops Price Duration
Apples Oranges Pears Grapes Kiwi
Person Woman Man Camera TV
Departure Arrival
Cars Trucks Boats Planes Motorcycles ``` ### Options with Horizontal Separator To create a natural separation between options, simply use a `
` element.
New tab New window Open file Open location
Close window Close tab Save page as...
Share
Print
See code ```html New tab New window Open file Open location
Close window Close tab Save page as...
Share
Print ``` ### Submenu / Nested Menu The `auro-menu` element supports the placement of an `auro-menu` inside of another `auro-menu`. There is no technical limit to the level of nesting.
Stops Price Duration
Apples Oranges Pears Grapes Kiwi
Person Woman Man Camera TV
Departure Arrival
Cars Trucks Boats Planes Motorcycles
See code ```html Stops Price Duration
Apples Oranges Pears Grapes Kiwi
Person Woman Man Camera TV
Departure Arrival
Cars Trucks Boats Planes Motorcycles ``` ### Restricted Width and Long Option The `auro-menu` element supports scenarios where the outer parent element of the menu constrains its width and there are options with text longer than the pull down menu will support. Truncated content will be illustrated with an ellipsis.
New tab New window Open file Open location
Close window Close tab Save page as 'option_10_redevelopment_hover_scenario.png'
Share
Print
See code ```html New tab New window Open file Open location
Close window Close tab Save page as 'option_10_redevelopment_hover_scenario.png'
Share
Print ``` #### Hidden Options The `auro-menuoption` element supports scenarios where the menu option needs to be hidden. e.g. the only visible menu options contain the `matchWord`.
New tab New window Open file Open location
Close window Save page as...
Share
Print
See code ```html New tab New window Open file Open location
Close window Save page as...
Share
Print ``` ### Reset Menu Selection State The `auro-menu` may be reset to a state with no menuoption selected by setting the `value` to `undefined`.
Stops Price Duration Departure Arrival

RESET
See code ```html Stops Price Duration Departure Arrival

RESET ``` ```js export function auroMenuResetExample() { const resetExampleBtnElem = document.querySelector('#resetExampleBtn'); const resetExampleElem = document.querySelector('#resetExample'); if (resetExampleElem && resetExampleBtnElem) { resetExampleBtnElem.addEventListener('click', () => { resetExampleElem.reset(); }); } } ```