Button Menu

A lightning-button-menu component represents a button that displays a dropdown menu of actions or functions when you click it.

The menu closes when you click away from it, and it also closes and puts the focus back on the button when you select a menu item.

Use lightning-menu-item components nested in lightning-button-menu to specify the menu items for the button menu.

This example shows how to create a dropdown button menu with three items.

To add a text label to the button before the icon, use the label attribute.

The lightning-button-menu component supports several variants that change the look of the button. You can use a combination of the variant, icon-name, and icon-size attributes to customize the button and icon styles.

For more information, see the Component Styling section.

You can create menu items that can be checked or unchecked using the checked attribute in the lightning-menu-item component, toggling it as needed. To enable toggling of a menu item, you must set an initial value on the checked attribute, specifying either true or false.

Use the lightning-menu-divider component to create a dividing line after a menu item.

Use the lightning-menu-subheader component to create subheadings in the list of menu items.

This example creates a button menu with several items during initialization. The items array definition uses the @track decorator to track mutations in the array. If the value of items changes, the component's template rerenders.

Define items and handle the select event in your JavaScript code.

The is-loading attribute enables you to show an activity indicator while the menu is loading. You can use this attribute, for example, to inform users that the menu is working while generating a large list of menu items. When is-loading is true, the menu shows a spinner.

Use loading-state-alternative-text along with is-loading to specify explanatory text such as "Loading menu..." or "Please wait while items load".

Use the is-draft and draft-alternative-text attributes together to indicate that the button menu is in an unsaved state. The draft indicator, an asterisk, is shown for the button menu when is-draft is true. The draft-alternative-text attribute is required to provide text describing the reason the menu is considered in a draft state. The button menu draft state can 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.

lightning-button-menu implements the menus blueprint in the Salesforce Lightning Design System (SLDS).

Use a combination of the icon-name, icon-size, and variant attributes to customize the button and icon styles.

By default, the button displays a utility icon to indicate the dropdown function. Use the icon-name attribute to specify an optional utility icon to display in front of the utility icon. Use the icon-size attribute to change the icon size from the default size of medium.

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

Use the variant attribute with one of these values to apply styling.

• border - Shows a gray border around the button's down arrow symbol. The area inside the border is transparent and clickable. This is the default variant and doesn't need to be specified.
• border-inverse - Same as the border variant except the down arrow is white so it's visible on dark backgrounds.
• border-filled - Same as the border variant, except the area inside the border is filled with white.
• container - Shows only the down arrow, without a visible border. The clickable area surrounding the down arrow is the same size as the default border variant and is transparent.
• bare - Same as the container variant, except the clickable area surrounding the down arrow is smaller than the default.
• bare-inverse - Same as the bare variant except the down arrow is white so it's visible on dark backgrounds.

Adjust the button and icon sizes using the size attribute with one of these values.

For bare and bare-inverse variants:

• medium is the default size, which creates a 14px by 14px icon
• small creates a 12px by 12px icon
• x-small creates a 8px by 8px icon
• large creates a 24px by 24px icon

For other variants:

• medium is the default size, which creates a 32px by 32px button enclosing a 14px by 14px icon.
• small creates a 24px by 24px button enclosing a 14px by 14px icon
• x-small creates a 20px by 20px button enclosing a 12px by 12px icon
• xx-small creates a 16px by 16px button enclosing a 8px by 8px icon

To apply additional styling, use the SLDS utility classes with the class attribute.

This example adds padding around the button menu using an SLDS class.

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 Buttons: Styling Hooks Overview for documentation on component-specific hooks for this component.lightning-button-menu contains the same customizable elements as lightning-button, which supports --slds-c-button-* custom properties. Custom properties for button menus work only with particular lightning-button-menu variants.

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

Icons are not available in Lightning Out, but they are available in Lightning Components for Visualforce and other experiences.

This component's menu items are created only if the button is triggered. You can't reference the menu items during initialization or if the button isn't triggered yet.

In Lightning Experience, a button menu that's opened overlays the record edit page or modal, the global header, and record form footer when scrolling.

You can customize the alignment of the dropdown menu relative to the button using menu-alignment. If you are using lightning-button-menu in a container that specifies the overflow:hidden CSS property, setting menu-alignment="auto" ensures that the dropdown menu is not hidden from view when the menu is toggled. For mobile devices, set menu-alignment="auto" to ensure proper display of the menu.

When using this component within lightning-button-group, set variant="border-filled" on lightning-button-menu for a white button background. Otherwise, the lightning-button-menu background is transparent by default.

To inform screen readers that a button menu is disabled, set the disabled attribute to true.

Buttons must have an accessible name to enable assistive technology to describe the button's purpose. Provide this name using the alternative-text or label attribute. Make it a clear action, such as "Show menu". To make the name available to assistive technology but hidden from view, use alternative-text.

lightning-button-menu is rendered with aria-haspopup="true" to indicate that the button opens a menu. The component also indicates whether the menu is currently expanded or collapsed using aria-expanded="true" or aria-expanded="false".

For more information, see the WAI-ARIA Specification.

To display a contextual popup over the button menu, use the tooltip attribute. The popup becomes visible when you hover over the button, or after the button receives keyboard focus. Showing the popup on hover or on keyboard focus ensures that all users can access it, even if they aren’t using a mouse.

If you use both title and tooltip attributes, they are both visible when you hover over the button. Some screen readers don’t support the title attribute and many of them don’t read the title attribute by default.

For sighted users, make sure your descriptions for title and tooltip are not repetitive. We recommend providing detailed information to tooltip and making title more concise if you use both.

If you use the is-loading indicator, use loading-state-alternative-text to provide a description for users of assistive devices.

If you use the is-draft indicator, use draft-alternative-text to provide a description for users of assistive devices.

select

The event fired when the menu is selected.

The select event returns the following parameter.

The event properties are as follows.

open

The event fired when you open the dropdown menu in one of the following ways.

• Tab to the button and press the Enter key
• Click the button that toggles the dropdown menu

The open event does not return any parameters.

The event properties are as follows.

close

The event fired when you close the dropdown menu in one of the following ways.

• Select or unselect a dropdown menu item
• Click the button that toggles the dropdown menu
• Remove focus from the dropdown menu, such as by clicking outside of the dropdown menu or tabbing to another element on the page

The close event does not return any parameters.

The event properties are as follows.