Button Menu

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

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

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.

1<template>
2    <lightning-button-menu alternative-text="Settings">
3        <lightning-menu-item label="Font" value="font"> </lightning-menu-item>
4        <lightning-menu-item label="Size" value="size"> </lightning-menu-item>
5        <lightning-menu-item label="Format" value="format">
6        </lightning-menu-item>
7    </lightning-button-menu>
8</template>

lightning-button-menu 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.

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.

To create menu items that appear with a checkmark, use the checked attribute in the lightning-menu-item component, toggling it as needed.

1<lightning-button-menu
2  alternative-text="Formatting options"
3  onselect={handleSelect}
4>
5  <lightning-menu-item
6    value="bold"
7    label="Bold"
8    checked={isBold}
9  ></lightning-menu-item>
10  <lightning-menu-item
11    value="italic"
12    label="Italic"
13    checked={isItalic}
14  ></lightning-menu-item>
15</lightning-button-menu>

To enable toggling of a menu item, you must set an initial value on the checked attribute, specifying either true or false.

1import { LightningElement } from "lwc";
2
3export default class ButtonMenuCheckedExample extends LightningElement {
4  isBold = true; // initial value must be true/false
5  isItalic = false;
6
7  handleSelect(event) {
8    const { value } = event.detail;
9    if (value === "bold") this.isBold = !this.isBold;
10    if (value === "italic") this.isItalic = !this.isItalic;
11  }
12}

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. When working with an iterator, include a unique key value on lightning-menu-item. For more information, see Render Lists in the Lightning Web Components Developer Guide.

1<template>
2    <lightning-button-menu
3        alternative-text="Action"
4        onselect={handleMenuSelect}
5    >
6        <template for:each={items} for:item="action">
7            <lightning-menu-item
8                label={action.label}
9                value={action.value}
10                key={action.label}
11            >
12            </lightning-menu-item>
13        </template>
14    </lightning-button-menu>
15</template>

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.

1import { LightningElement, track } from "lwc";
2
3export default class DemoButtonMenu extends LightningElement {
4  @track
5  items = [
6    {
7      label: "Alpha",
8      value: "alpha",
9    },
10    {
11      label: "Beta",
12      value: "beta",
13    },
14    {
15      label: "Gamma",
16      value: "gamma",
17    },
18  ];
19
20  handleMenuSelect(event) {
21    // retrieve the selected item's value
22    const selectedItemValue = event.detail.value;
23
24    // INSERT YOUR CODE HERE
25  }
26}

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

1<template>
2    <lightning-button-menu
3        is-loading
4        loading-state-alternative-text="Loading menu items"
5    >
6        <lightning-menu-item value="one" label="One"></lightning-menu-item>
7        <lightning-menu-item value="two" label="Two"></lightning-menu-item>
8        <lightning-menu-item value="three" label="Three"></lightning-menu-item>
9    </lightning-button-menu>
10</template>

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. Use the draft indicator with the draft-alternative-text attribute to provide text describing the reason the menu is in a draft state. Use the button menu’s draft state to show there’s unsaved state or unsaved data, for example, if a user changes a customizable menu.

1<template>
2    <lightning-button-menu
3        is-draft
4        draft-alternative-text="Menu has unsaved changes"
5    >
6        <lightning-menu-item value="one" label="One"></lightning-menu-item>
7        <lightning-menu-item value="two" label="Two"></lightning-menu-item>
8        <lightning-menu-item value="three" label="Three"></lightning-menu-item>
9    </lightning-button-menu>
10</template>

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

By default, the button shows a utility:down icon to indicate the dropdown function. Use the icon-name attribute to place an optional utility icon in front of the utility:down 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’re 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 - The default variant, which shows a gray border around the button’s down arrow symbol. The area inside the border is transparent and clickable.
• 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 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 by 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 by using an SLDS class.

1<lightning-button-menu
2    class="slds-p-around_medium"
3    alternative-text="Show menu"
4>
5    <lightning-menu-item value="Edit" label="Edit"></lightning-menu-item>
6    <lightning-menu-item value="Save" label="Save"></lightning-menu-item>
7</lightning-button-menu>

Component styling hooks provide CSS custom properties that use the --slds-c-* prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the SLDS 1 component blueprints for available component styling hooks.

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

lightning-button-menu supports these component styling hooks.

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

Icons aren’t available in Lightning Out, but they’re 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 in an open state overlays the record edit page or modal, the global header, and the record form footer when scrolling.

You can customize the alignment of the dropdown menu relative to the button by using menu-alignment. If you’re using lightning-button-menu in a container that specifies the overflow:hidden CSS property, setting menu-alignment="auto" makes sure that the dropdown menu isn’t 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.

1<lightning-button-menu
2    icon-name="utility:settings"
3    title="Settings"
4    tooltip="Choose a settings category"
5    alternative-text="Hidden text for assistive technology"
6>
7</lightning-button-menu>

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 doesn’t 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.