Button Menu

A lightning:buttonMenu represents a button that when clicked displays a dropdown menu of actions or functions that a user can access.

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:menuItem as a subcomponent of lightning:buttonMenu to specify the menu items for the button menu.

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

Use the class attribute to apply utility classes. For example, you can set class="slds-m-vertical_large" or other margin classes to add spacing around the icon.

Use the variant attribute to change border styling, fill, and clickable area. See Variants for descriptions of the available variants.

Use the iconName attribute to specify an optional utility icon to display in front of the default icon. Use the iconSize attribute to change the icon size from the default size of medium.

Use the label attribute to add a text label to the button before the icon.

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.

This example shows a dropdown menu with some customized styling and three items.

1<lightning:buttonMenu
2  iconName="utility:settings"
3  iconSize="small"
4  variant="border-filled"
5  alternativeText="Settings"
6  onselect="{! c.handleMenuSelect }"
7>
8  <lightning:menuItem label="Font" value="font" />
9  <lightning:menuItem label="Size" value="size" />
10  <lightning:menuItem label="Format" value="format" />
11</lightning:buttonMenu>

When onselect is triggered, its event will have a value parameter, which is the value of the selected menu item. Here’s an example of how to read that value.

1handleMenuSelect: function(cmp, event, helper) {
2    var selectedMenuItemValue = event.getParam("value");
3}

The lightning:buttonMenu component supports several variants that change the look of the button.

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

You can create menu items that can be checked or unchecked using the checked attribute in the lightning:menuItem 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:menuDivider component to create a dividing line after a menu item.

Use the lightning:menuSubheader component to create subheadings in the list of menu items.

This example creates a button menu with several items during initialization.

1<aura:component>
2  <aura:handler name="init" value="{!this}" action="{!c.createItems}" />
3  <lightning:buttonMenu
4    alternativeText="Action"
5    onselect="{! c.handleMenuSelect }"
6  >
7    <aura:iteration var="action" items="{! v.actions }">
8      <lightning:menuItem
9        aura:id="actionMenuItems"
10        label="{! action.label }"
11        value="{! action.value }"
12      />
13    </aura:iteration>
14  </lightning:buttonMenu>
15</aura:component>

The client-side controller creates the array of menu items and set its value on the actions attribute.

1({
2  createItems: function (cmp, event) {
3    var items = [
4      { label: "New", value: "new" },
5      { label: "Edit", value: "edit" },
6      { label: "Delete", value: "delete" },
7    ];
8    cmp.set("v.actions", items);
9  },
10});

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

Use loadingStateAlternativeText along with isLoading to specify explanatory text such as “Loading menu…” or “Please wait while items load”.

Use the isDraft and draftAlternativeText 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 isDraft is true. The draftAlternativeText attribute is required to provide text describing the reason the menu is considered in a draft state. The button menu draft state might be used to to show there is unsaved state or data that could be lost, for example if there’s a user change in a customizable menu.

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

This component contains menu items that are created only if the button is triggered. You won’t be able to 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 menuAlignment. If you are using buttonMenu in a container that specifies the overflow:hidden CSS property, setting menuAlignment="auto" ensures that the dropdown menu is not hidden from view when the menu is toggled. For mobile devices, set menuAlignment="auto" to ensure proper display of the menu.

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

lightning:buttonMenu 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". To control the visibility of the menu, use the visible attribute. Note that a disabled menu cannot be expanded or collapsed.

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.