Menu Item

A lightning-menu-item is a menu item within the lightning-button-menu dropdown component. It can hold state such as checked or unchecked, and can contain icons.

Use the class attribute to customize the styling.

When applying Lightning Design System classes or icons, check that they’re available in the Lightning Design System release tied to your org. The Lightning Design System site shows the latest Lightning Design System resources, and these resources become available only when the new release is available in your org.

Here’s an example.

1<template>
2    <lightning-button-menu alternative-text="Toggle menu">
3        <lightning-menu-item
4            label="Menu Item 1"
5            value="menuitem1"
6            icon-name="utility:table"
7        >
8        </lightning-menu-item>
9    </lightning-button-menu>
10</template>

Use lightning-menu-item within lightning-button-menu, which implements the menus blueprint in the Salesforce Lightning Design System (SLDS). The menus adapt to SLDS 1 or SLDS 2 styling based on the org’s theme or the container app that you use.

To implement a multi-select menu, use the checked attribute. The following JavaScript example handles selection via the onselect event on the lightning-button-menu component. Selecting a menu item applies the selected state to that item.

1handleSelect (event) {
2        const selectedItemValue = event.detail.value;
3        const menuItem = this.privateMenuItems.find(function(item) {
4            return item.value === selectedItemValue;
5        });
6
7        menuItem.checked = !menuItem.checked;
8    }

Use the icon-name attribute to add an icon after the text of the menu item. Use the prefix-icon-name attribute to add an icon before the text of the menu item.

This example displays an icon in grayscale before the menu item text.

1<template>
2    <lightning-button-menu>
3        <lightning-menu-item prefix-icon-name="utility:user" label="Menu item">
4        </lightning-menu-item>
5        <lightning-menu-item label="Another menu item"> </lightning-menu-item>
6    </lightning-button-menu>
7</template>

The SLDS action and object icons (standard and custom) have background colors. However, when you use these icons in menu items, the colors aren’t shown by default.

To specify icons with a background color in menu items, use the icon-type attribute. The icon-type attribute accepts two values.

• standard (default): Sets the icon on the menu item in grayscale.
• color: Sets the icon on the menu item with a background color. Action icons and object icons display a white glyph on a colored background that’s defined in SLDS. Doctype and utility icons don’t display with a background color.

To enable colored icons and backgrounds, use the icon-type="color" attribute. In this example, the standard:event icon specifies a background color and the utility:settings icon is in grayscale.

1<template>
2    <lightning-button-menu>
3        <lightning-menu-item
4            prefix-icon-name="standard:event"
5            icon-type="color"
6            label="Standard icon with icon-type color">
7        </lightning-menu-item>
8        <lightning-menu-item
9            icon-name="utility:settings"
10            icon-type="color"
11            label="Utility icon with icon-type color">
12        </lightning-menu-item>
13    </lightning-button-menu>
14</template>

Setting icon-type="color" assigns the menu items with icons using their full color schemes, including any associated background colors. Remember that the appearance of icons can still be subject to the overall theme and styling of your Salesforce org or Lightning application.

You can find a comprehensive list of all available icons and their appearances at the Lightning Design System Icons page.

The href attribute allows you to use the button menu for navigation. This example specifies a URL in the menu item’s href attribute to create a link. The link is applied to the content of the menu item, including text and icons.

1<template>
2    <lightning-button-menu>
3        <lightning-menu-item
4            href="https://www.google.com"
5            label="A linked menu item"
6        >
7        </lightning-menu-item>
8    </lightning-button-menu>
9</template>

If you don’t provide a target, the link opens in the same frame or browser tab where it was clicked, which is the browser’s default behavior. To open the link in a new browser tab, set target="_blank".

1<template>
2    <lightning-button-menu>
3        <lightning-menu-item
4            href="https://www.google.com"
5            target="_blank"
6            label="A linked menu item"
7        >
8        </lightning-menu-item>
9    </lightning-button-menu>
10</template>

Use the is-draft and draft-alternative-text attributes together to indicate that the menu item is in an unsaved state. The draft indicator, an asterisk, is shown for the menu item when is-draft is true. The draft-alternative-text attribute is required to provide text describing the reason the item is considered in a draft state. The draft state can be used to show that there’s’ unsaved state or data that could be lost, for example if there’s a user change in a customizable menu.