---
schema_version: "1"
id: e15643c7d5462baa3af6266cc4e523fe45c8522246b36ef628b4b415754cb430
title: Button Menu
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/buttonMenu/lightning-button-menu.md
canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-menu.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 274b71dc42f7e99537fab5fe47467fc3558ddf2e941c8a633d26f0288a03d56b
products:
  - Lightning Component Reference
---

# Button Menu

**`lightning-button-menu`**

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

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="buttonMenu" model="lwc" namespace="lightning"}


:::::

:::::tab

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`](/docs/platform/lightning-component-reference/guide/lightning-menu-item.html) 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.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu alternative-text="Settings">
        <lightning-menu-item label="Font" value="font"> </lightning-menu-item>
        <lightning-menu-item label="Size" value="size"> </lightning-menu-item>
        <lightning-menu-item label="Format" value="format">
        </lightning-menu-item>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->

## Design

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

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Menus](https://v1.lightningdesignsystem.com/components/menus/)                                                                       | [Menus](https://www.lightningdesignsystem.com/components/menus/)                                                |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

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](#component-styling) section.

## Checked Menu Items

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

<!-- prettier-ignore -->
```html
<lightning-button-menu
  alternative-text="Formatting options"
  onselect={handleSelect}
>
  <lightning-menu-item
    value="bold"
    label="Bold"
    checked={isBold}
  ></lightning-menu-item>
  <lightning-menu-item
    value="italic"
    label="Italic"
    checked={isItalic}
  ></lightning-menu-item>
</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`.

```javascript
import { LightningElement } from "lwc";

export default class ButtonMenuCheckedExample extends LightningElement {
  isBold = true; // initial value must be true/false
  isItalic = false;

  handleSelect(event) {
    const { value } = event.detail;
    if (value === "bold") this.isBold = !this.isBold;
    if (value === "italic") this.isItalic = !this.isItalic;
  }
}
```

## Create Dividers and Subheadings

Use the [`lightning-menu-divider`](/docs/platform/lightning-component-reference/guide/lightning-menu-divider.html) component to create a dividing line after a menu item.

Use the [`lightning-menu-subheader`](/docs/platform/lightning-component-reference/guide/lightning-menu-subheader.html) component to create subheadings in the list of menu items.

## Generate 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](https://developer.salesforce.com/docs/platform/lwc/guide/create-lists.html) in the _Lightning Web Components Developer Guide_.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu
        alternative-text="Action"
        onselect={handleMenuSelect}
    >
        <template for:each={items} for:item="action">
            <lightning-menu-item
                label={action.label}
                value={action.value}
                key={action.label}
            >
            </lightning-menu-item>
        </template>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->

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.

```javascript
import { LightningElement, track } from "lwc";

export default class DemoButtonMenu extends LightningElement {
  @track
  items = [
    {
      label: "Alpha",
      value: "alpha",
    },
    {
      label: "Beta",
      value: "beta",
    },
    {
      label: "Gamma",
      value: "gamma",
    },
  ];

  handleMenuSelect(event) {
    // retrieve the selected item's value
    const selectedItemValue = event.detail.value;

    // INSERT YOUR CODE HERE
  }
}
```

## Show the Loading State of a Menu

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

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu
        is-loading
        loading-state-alternative-text="Loading menu items"
    >
        <lightning-menu-item value="one" label="One"></lightning-menu-item>
        <lightning-menu-item value="two" label="Two"></lightning-menu-item>
        <lightning-menu-item value="three" label="Three"></lightning-menu-item>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->

## Draft Indicators

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.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-button-menu
        is-draft
        draft-alternative-text="Menu has unsaved changes"
    >
        <lightning-menu-item value="one" label="One"></lightning-menu-item>
        <lightning-menu-item value="two" label="Two"></lightning-menu-item>
        <lightning-menu-item value="three" label="Three"></lightning-menu-item>
    </lightning-button-menu>
</template>
```
<!-- prettier-ignore-end -->

## Component Styling

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

### Icons

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](https://v1.lightningdesignsystem.com/icons/#utility)
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.

### Variants

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.

### Sizes

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

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

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

<!-- prettier-ignore-start -->
```html
<lightning-button-menu
    class="slds-p-around_medium"
    alternative-text="Show menu"
>
    <lightning-menu-item value="Edit" label="Edit"></lightning-menu-item>
    <lightning-menu-item value="Save" label="Save"></lightning-menu-item>
</lightning-button-menu>
```
<!-- prettier-ignore-end -->

### Styling Hooks

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](https://v1.lightningdesignsystem.com/components/overview/) for available component styling hooks.

For more information, see [Style Components Using Lightning Design System Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties) in the Lightning Web Components Developer Guide.


`lightning-button-menu` supports these component styling hooks.

| CSS Custom Property                | `lightning-button-menu` Variants                                                                            |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `--slds-c-button-color-background` | `border` (default), `bare`, `bare-inverse`, and `container`                                                 |
| `--slds-c-button-color-border`     | `bare`, `bare-inverse`, and `container`                                                                     |
| `--slds-c-button-text-color`       | `border` (default), `bare`, `bare-inverse`,`container`, and `border-filled`; use with the `label` attribute |
| `--slds-c-button-text-color-*`     | `border` (default), `bare`, `container`, and `border-filled`                                                |
| `--slds-c-button-radius-border`    | all                                                                                                         |
| `--slds-c-button-sizing-border`    | `bare`, `bare-inverse`, `border-inverse`, and `container`                                                   |

For more information, see [Style Components Using Lightning Design System Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties) in the Lightning Web Components Developer Guide.

## Usage Considerations

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.

## Accessibility

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](https://www.w3.org/TR/wai-aria/).

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.

<!-- prettier-ignore-start -->
```html
<lightning-button-menu
    icon-name="utility:settings"
    title="Settings"
    tooltip="Choose a settings category"
    alternative-text="Hidden text for assistive technology"
>
</lightning-button-menu>
```
<!-- prettier-ignore-end -->

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.

## Custom Events

**`select`**

The event fired when the menu is selected.

The `select` event returns the following parameter.

| Parameter | Type   | Description                       |
| --------- | ------ | --------------------------------- |
| value     | string | The value of the selected option. |

The event properties are as follows.

| Property   | Value | Description                                                                    |
| ---------- | ----- | ------------------------------------------------------------------------------ |
| bubbles    | false | This event does not bubble.                                                    |
| cancelable | true  | This event can be canceled. You can call `preventDefault()` on this event.     |
| composed   | false | This event does not propagate outside the template in which it was dispatched. |

**`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.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can’t call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside of the component in which it was dispatched.                        |

**`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.

| Property   | Value | Description                                                                                                |
| ---------- | ----- | ---------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                                |
| cancelable | false | This event has no default behavior that can be canceled. You cannot call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside of the component in which it was dispatched.                         |


:::::

:::::tab
::component-specification{component="buttonMenu" model="lwc" namespace="lightning"}

:::::

::::::