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.

This component implements styling from menus in the Lightning Design System.

When applying Lightning Design System classes or icons, check that they are 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 become available only when the new release is available in your org.

Here is an example.

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.

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.

The SLDS action and object icons (standard and custom) are defined with color backgrounds. However, when you use these icons in menu items, the colors aren't displayed by default.

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

• standard (default): Displays the icon on the menu item in grayscale.
• color: Displays 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 is displayed with a background color and the utility:settings icon is displayed in grayscale.

Setting icon-type="color" displays the menu items with icons using their full color schemes, including any associated background colors. Remember that the appearance of icons may 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.

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".

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 might be used to show there is unsaved state or data that could be lost, for example if there's a user change in a customizable menu.

Component styling hooks use the --slds-c-* prefix and change styling for specific elements or properties of a component. Component-specific styling isn’t recommended, because it’s unsupported for SLDS 2, but existing customizations still work with the original SLDS. If you use component styling hooks, limit the components to SLDS themes until SLDS 2 and the Salesforce Cosmos theme become generally available. See Menus: Styling Hooks Overview for documentation on component-specific hooks for this component.

For more information, see Style Components Using Lightning Design System Styling Hooks in the Lightning Web Components Developer Guide.