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:iterationThis 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); } })
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.
AccessibilityTo inform screen readers that a button is disabled, set the disabled attribute to true.
MethodsThis component supports the following method.
focus(): Sets the focus on the element.
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. |