lightning:buttonMenu

Represents a dropdown menu with a list of actions or functions.

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

Use the variant, size, or class attributes to customize the styling.

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

This example shows a dropdown menu with three items.

<lightning:buttonMenu iconName="utility:settings" alternativeText="Settings" onselect="{! c.handleMenuSelect }">
    <lightning:menuItem label="Font" value="font" />
    <lightning:menuItem label="Size" value="size"/>
    <lightning:menuItem label="Format" value="format" />
</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.

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

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.

The menu closes when you click away from it, and it will also close and will put the focus back on the button when a menu item is selected.

Generating Menu Items with aura:iteration

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

<aura:component>
    <aura:handler name="init" value="{!this}" action="{!c.createItems}" />
    <lightning:buttonMenu alternativeText="Action" onselect="{! c.handleMenuSelect }">
        <aura:iteration var="action" items="{! v.actions }">
            <lightning:menuItem aura:id="actionMenuItems" label="{! action.label }" value="{! action.value }"/>
        </aura:iteration>
    </lightning:buttonMenu>
</aura:component>

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

({
    createItems: function (cmp, event) {
        var items = [
            { label: "New", value: "new" },
            { label: "Edit", value: "edit" },
            { label: "Delete", value: "delete" }
        ];
        cmp.set("v.actions", items);
    }
})
Usage Considerations

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.

Accessibility

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

Methods

This component supports the following method.

focus(): Sets the focus on the element.

Attributes

Attribute Name Attribute Type Description Required?
accesskey String Specifies a shortcut key to activate or focus an element.
alternativeText String The assistive text for the button.
body ComponentDefRef[] The body of the component.
class String A CSS class for the outer element, in addition to the component's base classes.
disabled Boolean If true, the menu is disabled. Disabling the menu prevents users from opening it. This value defaults to false.
iconName String The name of the icon to be used in the format 'utility:down'. This value defaults to utility:down. If an icon other than utility:down or utility:chevrondown is used, a utility:down icon is appended to the right of that icon.
iconSize String The size of the icon. Options include xx-small, x-small, medium, or large. This value defaults to medium.
menuAlignment String Determines the alignment of the menu relative to the button. Available options are: left, center, right. This value defaults to left.
name String The name for the button element. This value is optional and can be used to identify the button in a callback.
onblur Action The action triggered when the element releases focus.
onfocus Action The action triggered when the element receives focus.
onselect Action Action fired when a menu item is selected. The 'detail.menuItem' property of the passed event is the selected menu item.
tabindex Integer Specifies the tab order of an element (when the tab button is used for navigating).
title String Tooltip text on the button.
value String The value for the button element. This value is optional and can be used when submitting a form.
variant String The variant changes the look of the button. Accepted variants include bare, container, border, border-filled, bare-inverse, and border-inverse. This value defaults to border.
visible Boolean If true, the menu items are displayed. This value defaults to false.