Skip to content

MenuItem

A MenuItem is a selectable option within a Menu.

WARNING

This is not a standalone component, nor will it typically be directly used. It's intended for use by the Menu component, which will provide it with props and menu state information. See Menu for more details.

Guidelines

Using menu items

MenuItem is an “internal” component, used exclusively to represent content within a Menu. It cannot be used by itself.

MenuItems contain text, and supporting media (icons or thumbnails) that represent an available choice for users.

Specifications

Specification of MenuItem.

Each menu item may include the following elements:

  1. Visual element (optional)
    An icon or thumbnail can be included in order to provide more context about the menu item content.
  2. Label
    A clear and descriptive title for the menu item.
  3. Supporting text (optional)
    Optional and subtle text that supports or explains the label.
  4. Match text (optional)
    In the context of a search suggestions menu, this optional text displays the alternative label of an item that matches the search query (e.g. an alias).
  5. Description (optional)
    Optional and subtle descriptive text that provides additional information about the menu item.

Menu items have no minimum or maximum character requirement, although concise text is recommended. If the label is multiline, the supporting text will be positioned next to the last line of the label.

Refer to the MenuItem component in Codex Figma.

Interaction states

Menu items have the following visually separate states:

Interaction states of MenuItem: default, hover, active, selected, selected-hover, and disabled.

  1. Default
  2. Hover
  3. Active
  4. Selected
  5. Selected hover
  6. Disabled

Best practices

Consider the following recommendations when using menu items within menus.

Icon, label, and description

A MenuItem featuring a simple icon and concise label and description.

Do:
  • Use icons to emphasize the meaning of the label, adapting them as needed for each project.
  • Keep the label and optional description concise to enhance menu scannability and readability.

A MenuItem featuring a complex icon, a label, and a lengthy description.

Don't:
  • Use icons that are difficult to understand or do not clearly convey their purpose.
  • Overcrowd menu items with lengthy labels and descriptions.

Supporting text

A MenuItem featuring supporting text within brackets.

Do:
  • Include supporting text within brackets to explain where a search result is redirected from.

A MenuItem featuring supporting text without brackets.

Don't:
  • Include supporting text without brackets. It should always be enclosed within brackets to differentiate it from the item label.

Demos

Note that these demos do not properly show some interactive states of menu items (like active or hovered/highlighted), since they display menu items as standalone or as part of an always-expanded, detached menu. To see the full interactivity of menu items, check out a component that contains a menu, like Select, Lookup, or TypeaheadSearch.

Configurable

Note that manually hovering over or selecting this menu item is disabled, the configuration options to set these states should be used.

  • Item labelDescription text
NameValue
Props
disabled
selected
active
highlighted
label
match
supportingText
icon
description
searchQuery
boldLabel
hideDescriptionOverflow
View
Reading direction
Note: For icon properties, the relevant icon also needs to be imported from the @wikimedia/codex-icons package. See the usage documentation for more information.

Default

With description and bold label

If a url property is included, the menu item will be wrapped in an anchor tag.

With icon

With thumbnail

With search query highlighted

When a menu item displays a search result, the current search query can be provided (along with the highlightQuery prop) and it will be visually differentiated within the menu item's title. The search query text will have a normal font weight, while the rest of the title will be bold, which is meant to bring attention to the available suggestions based on the current search query.

In the example below, the search query is "Co".

With search query match

For search results, a match property may be included that represents the text related to that item that matched the search query (e.g. a Wikidata alias). The match will be displayed after the label. In the example below, the search query is "felis margarita," an alias of the Wikidata item "sand cat."

With supporting text

Text that supports or explains the label can be added via the supportingText prop. This text will be displayed after the label in a more subtle color.

The example below shows a result for the search term "Corn," which redirects to the article for "Maize" on English Wikipedia.

With multiple languages

Individual lang attributes can be set for the label, description, match, and supportingText props via the language prop, which is an object of lang attributes for those props.

The example below demonstrates a search result in a Greek interface for the English word "moon."

With long title and search query highlighted

With description text overflow hidden

Within a list

With graphemes

Vue usage

A value must be provided, and various optional elements can be displayed:

  • A human-readable label
  • A description
  • A thumbnail or icon

Alternately, the entire content and layout of the menu item can be customized via the default slot.

For search results, the search query can be visually differentiated within the result title.

Props

Prop nameDescriptionTypeDefault
id(required)ID for HTML id attribute.string
value(required)The value provided to the parent menu component when this menu item is selected.string|number
disabledWhether the menu item is disabled.booleanfalse
selectedWhether this menu item is selected.booleanfalse
activeWhether this menu item is being pressed.booleanfalse
highlightedWhether this menu item is visually highlighted due to hover or keyboard navigation.booleanfalse
labelLabel for the menu item. If this isn't provided, the value will be displayed instead.string''
matchText that matches current search query. Only used for search results and will be displayed after the label.string''
supportingTextText that supports the label. Supporting text will appear next to the label in a more subtle color.string''
urlURL for the menu item. If provided, the content of the menu item will be wrapped in an anchor tag.string''
iconIcon for the menu item.Icon''
showThumbnailWhether a thumbnail (or a placeholder icon) should be displayed.booleanfalse
thumbnailThumbnail for the menu item.Thumbnail|nullnull
descriptionDescription of the menu item.string|null''
searchQueryThe search query to be highlighted within the menu item's title.string''
boldLabelWhether to bold menu item labels.booleanfalse
hideDescriptionOverflowWhether to hide description text overflow via an ellipsis.booleanfalse
languageOptional language codes for label, match, supporting text, and description.

If included, that language code will be added as a lang attribute to the element wrapping that text node.
MenuItemLanguageData() => { return {}; }

Events

Event namePropertiesDescription
changemenuState MenuState - State to change setState boolean - Whether to set that state to this menu itemEmitted when the menu item becomes selected, active or highlighted in response to user interaction. Handled in the Menu component.

Slots

NameDescriptionBindings
defaultCustom menu item content.