Skip to content
On this page
You're viewing the docs for the main branch of Codex, which may contain features that have not been released yet. Codex users should visit the official docs.

Menu

A contextual list of selectable options, often triggered by a control or an input.

Designed for use in components, like Select and Lookup, that display a menu below another element (for example, a text input). This component renders a list of items, manages which item is selected, highlighted, and active, and handles keyboard navigation. It does not display the selected item or manage an input; the parent component needs to do that.

The selected and expanded props must be bound with v-model, even if the parent component doesn't use them. Without these v-model bindings, the menu won't function correctly.

The menu itself is not focusable; for keyboard navigation to work, the parent component needs to provide a focusable element, listen for keydown events on that element, and pass those events to the menu by calling the delegateKeyNavigation method.

WARNING

This is not a standalone component. It's intended for use inside other components, mainly within Codex. For example, the Select and Lookup components use this component internally.

Demos

Simple menu with input

NameValue
View
Reading direction

With custom menu item display

Use the footer prop to add a special menu item that will appear at the end of the menu. When scrolling is enabled, the footer item is pinned to the bottom of the menu (see the next demo). The footer item can be customized via the default slot, just like regular menu items.

See the TypeaheadSearch demos for a real-world example.

With scrolling enabled

In the Menu component, all menu items will be shown by default and the height of the menu will grow to accommodate the menu items. To limit the number of menu items shown at once and enable scrolling within the menu, set the visibleItemLimit prop to a positive number.

Although the default behavior in the Menu component is to show all menu items, some components that use the Menu component have a default visibleItemLimit prop set.

This demo includes a footer item, which is "sticky" to the bottom of the menu.

With no results message

If the no-results slot is populated, the Menu component will automatically display it when there are zero menu items.

Pending state

Pending state indicators can be displayed to indicate that menu items are being fetched. Set the pending prop to true to show the inline progress bar and "pending" message, which can be populated via the pending slot. See TypeaheadSearch for a real-world implementation of this.

When there are no menu items (e.g. on an initial search), the inline progress bar and the "pending" message will display.

When there are menu items, only the inline progress bar will display.

Usage

Props

Prop nameDescriptionTypeDefault
menuItems(required)Menu items. See the MenuItemData type.MenuItemData[]
footerInteractive footer item.

This is a special menu item which is pinned to the bottom of the menu. When scrolling is enabled within the menu, the footer item will always be visible at the bottom of the menu. When scrolling is not enabled, the footer item will simply appear as the last menu item.

The footer item is selectable, like other menu items.
MenuItemDatanull
selected(required)Value of the selected menu item, or undefined if no item is selected.

Must be bound with v-model:selected.

The property should be initialized to null rather than using a falsy value.
string|number|null
expanded(required)Whether the menu is expanded. Must be bound with v-model:expanded.boolean
showPendingWhether to display pending state indicators. Meant to indicate that new menu items are being fetched or computed.

When true, the menu will expand if not already expanded, and an inline progress bar will display. If there are no menu items yet, a message can be displayed in the pending slot, e.g. "Loading results".
booleanfalse
visibleItemLimitLimit the number of menu items to display before scrolling.

Setting this prop to anything falsy will show all menu items.

By default, all menu items are shown.
number|nullnull
showThumbnailWhether menu item thumbnails (or a placeholder icon) should be displayed.booleanfalse
boldLabelWhether to bold menu item labels.booleanfalse
hideDescriptionOverflowWhether to hide description text overflow via an ellipsis.booleanfalse
searchQueryThe search query to be highlighted within the menu items' titles.string''
showNoResultsSlotWhether to show the no-results slot content.

The Menu component automatically shows this slot when there is content in the no-results slot and there are zero menu items. However, some components may need to customize this behavior, e.g. to show the slot even when there is at least one menu item. This prop can be used to override the default Menu behavior.

Possible values: null (default): the no-results slot will display only if there are zero menu items. true: the no-results slot will display, regardless of number of menu items. false: the no-results slot will not display, regardless of number of menu items.
boolean|nullnull

Methods

Method nameDescriptionSignature
getHighlightedMenuItemGet the highlighted menu item, if any.Returns: MenuItemDataWithId|null The highlighted menu item, or null if no item is highlighted.
getHighlightedViaKeyboardGet whether the last highlighted item was highlighted via the keyboard.Returns: boolean Whether the last highlighted menu item was highlighted via keyboard.
clearActiveEnsure no menu item is active. This unsets the active item if there is one.Returns: void
delegateKeyNavigationHandles all necessary keyboard navigation.

The parent component should listen for keydown events on its focusable element, and pass those events to this method. Events for arrow keys, tab and enter are handled by this method. If a different key was pressed, this method will return false to indicate that it didn't handle the event.
Params:
  • event KeyboardEvent - Keydown event object
  • prevent boolean - If false, do not call e.preventDefault() or e.stopPropagation()
Returns: boolean Whether the event was handled

Events

Event namePropertiesDescription
menu-item-clickmenuItem MenuItemDataWithId - The menu item that was clickedWhen a menu item is clicked.

Typically, components with menus will respond to the selected value change, but occasionally, a component might want to react specifically when a menu item is clicked.
update:selectedselectedValue string|number|null - The .value property of the selected menu item, or null if no item is selected.When the selected menu item changes.
update:expandednewValue boolean - The new expanded state (true for open, false for closed)When the menu opens or closes.
menu-item-keyboard-navigationhighlightedMenuItem MenuItemDataWithId - The menu item was highlightedWhen a menu item is highlighted via keyboard navigation.
load-moreWhen the user scrolls towards the bottom of the menu.

If it is possible to add or load more menu items, then now would be a good moment so that the user can experience infinite scrolling.

Slots

NameDescriptionBindings
pendingMessage to indicate pending state.
no-resultsMessage to show if there are no menu items to display.
defaultDisplay of an individual item in the menu
active boolean - Whether the current item is visually active