<sl-menu-button>
  <span slot="button">Actions</span>
  <sl-menu-item>
    <sl-icon name="smile"></sl-icon>
    Profile
  </sl-menu-item>
  <sl-menu-item>
    <sl-icon name="far-gear"></sl-icon>
    Settings
  </sl-menu-item>
  <sl-menu-item>
    <sl-icon name="far-trash"></sl-icon>
    Remove
  </sl-menu-item>
</sl-menu-button>

<sl-menu-button aria-label="Show more options">
  <sl-icon name="ellipsis" slot="button"></sl-icon>
  <sl-menu-item>Update</sl-menu-item>
  <sl-menu-item>Remove</sl-menu-item>
</sl-menu-button>

When to Use

The following guidance describes when to use the Menu component.

Some interface elements can have additional actions, and providing a menu can enhance efficiency and streamline workflow. For instance, options to view details, open related documents, or access settings, offering extra details and actions specific to the element.

Reducing Visual Clutter

Keeping a clean interface with repetitive elements (like cards or table rows), but additional actions are still necessary, a menu fixes this scenario while providing access to secondary actions. For example, sorting a list of elements or changing the view of the page.

When not to Use

The following guidance describes when not to use the Menu component.

Menus should not be used for primary navigation in applications because they are hidden until triggered by a specific action, making them less discoverable for users. Basic actions should always be visible and accessible to ensure users can efficiently navigate to essential features without additional steps. Relying on menus for primary navigation can also create inconsistency in accessing core functions by requiring users to learn multiple ways to perform basic tasks.

Anatomy

Item	Name	Description	Optional
1	Button Menu	This is the trigger button to open the menu.	no
2	Menu Popover	This is the container for all the options of the menu, and appears close to the button menu.	no
3	Option Items	This are the menu options that can be separete on "Option Button" that behave like a regular button, "Selection Option" that can behave like a checkbox or radio button, and "Sub-Menu Button" to open a nested menu.	no
4	Group Heading	Title for the option groups to make eaiser to understand the function of the options.	yes
5	Option Icons	You can display an icon in each option to enhance the readability.	yes
6	Option Shortcuts	Adding shortcuts to the options to improve usability.	yes
7	Group Heading	Title for the option groups to make eaiser to understand the function of the options.	yes
8	Danger Option	Specific danger option of the menu.	yes

Options

The Figma component and the naming of its properties is still a work in progress. This information will be added as soon as possible.

Behaviours

Grouped Options

Splitting the related actions with a divider creates multiple categories, with the possibility of adding a heading to these ones. This helps users to quickly locate the available actions based on the relation of each action in the same group.

Overflow Content

Using sub-menus or nested options to organize related actions. This approach helps maintain clarity and reduces visual clutter by nesting similar or related actions under sub-menus. For example, within a "File" menu option, nested menus might include "Save As," "Print," and "Export," enhancing usability. However, this solution isn’t the magic one to create an infinite sub-menus to nested everything. Avoid adding more than 2 nested menus, so don’t exceed 3 levels.

Shortcut Options

Keyboard shortcuts next to menu options, providing alternative access methods for frequently used actions. These are typically indicated by symbols, numbers, or combinations, allowing proficient users to perform actions quickly without relying solely on mouse interactions. For instance, the "Paste" option in a text editor or the shortcut "Ctrl + V" enables users to execute the action promptly using the keyboard.

Card

More settings

List

Cards

Sort by

Newest

Oldest

Name

Edit

Remove

  <sl-menu-button position="bottom-end">
    <span slot="button">More settings</span>
    <sl-menu-item-group selects="single">
      <sl-menu-item selectable selected shortcut="$mod+Digit1">List</sl-menu-item>
      <sl-menu-item selectable shortcut="$mod+Digit2">Cards</sl-menu-item>
    </sl-menu-item-group>
    <hr />
    <sl-menu-item>
      Sort by
      <sl-menu selects="single" slot="submenu">
        <sl-menu-item selectable selected>Newest</sl-menu-item>
        <sl-menu-item selectable>Oldest</sl-menu-item>
        <sl-menu-item selectable>Name</sl-menu-item>
      </sl-menu>
    </sl-menu-item>
    <hr />
    <sl-menu-item disabled>Edit</sl-menu-item>
    <sl-menu-item>Remove</sl-menu-item>
  </sl-menu-button>

Component has a range of properties to define the experience in different use cases.

Properties

Name	Attribute	Type	Default	Description
`disabled`	`disabled`	`boolean \| undefined`		Whether the button is disabled; when set no interaction is possible.
`fill`	`fill`	`'solid' \| 'outline' \| 'link' \| 'ghost'`	`'outline'`	The fill of the button.
`position`	`position`	`'top' \| 'right' \| 'bottom' \| 'left' \| AlignedPlacement \| undefined`		The position of the menu relative to the button.
`size`	`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	The size of the button.
`variant`	`variant`	`'default' \| 'primary' \| 'success' \| 'info' \| 'warning' \| 'danger'`	`'default'`	The variant of the button.

Methods

Name	Parameters	Return	Description
`setAttributesTarget`	`target: HTMLElement`	`void`

Slots

Name	Description
`default`	The menu items should be slotted in the default slot.
`button`	Any content for the button should be slotted here.

CSS Parts

Name	Description
`button`	The button element.

Component has a range of properties to define the experience in different use cases.

Properties

Name	Attribute	Type	Default	Description
`heading`	`heading`	`string \| undefined`		The optional heading for the group.
`selects`	`selects`	`'single' \| 'multiple' \| undefined`		Determines whether if and how many menu items can be selected within this group.

Slots

Name	Description
`default`	The menu items within a group.
`header`	The header of the group.

Component has a range of properties to define the experience in different use cases.

Properties

Name	Attribute	Type	Description
`disabled`	`disabled`	`boolean \| undefined`	Whether this menu item is disabled.
`selectable`	`selectable`	`boolean \| undefined`	Whether this menu item can be selected.
`selected`	`selected`	`boolean \| undefined`	Whether this menu item has been selected.
`shortcut`	`shortcut`	`string \| undefined`	Keyboard shortcut for activating this menu item.
`variant`	`variant`	`'default' \| 'danger' \| undefined`	The variant of the menu item.

Events

Name	Event type	Description
`sl-select`	`SlSelectEvent`	Emits the current selected state as a boolean when the user toggles the menu item.

Slots

Name	Description
`default`	Content to display inside the menu item.
`submenu`	The menu items that will be displayed when the menu item is shown.

CSS Parts

Name	Description
`wrapper`	The wrapper around the menu item content.

Component has a range of properties to define the experience in different use cases.

Properties

Name	Attribute	Type	Default	Description
`offset`	`offset`	`number \| undefined`		The offset of the menu to its anchor. This is a property on this instance so that it can be overridden by the menu item in case of a nested menu. You should not need to set this property yourself.
`position`	`position`	`'top' \| 'right' \| 'bottom' \| 'left' \| AlignedPlacement \| undefined`	`'right-start'`	The position of the menu relative to its anchor.
`selects`	`selects`	`'single' \| 'multiple' \| undefined`		Determines whether if and how many menu items can be selected.

Events

Name	Event type	Description
`sl-select`	`SlSelectEvent<void>`	Emits when the menu item selection changes.

Slots

Name	Description
`default`	The menu's content: menu items or menu item groups.

CSS Properties

Name	Description
`--sl-menu-max-inline-size`	The maximum inline size of the menu.
`--sl-menu-min-inline-size`	The minimum inline size of the menu.

Keyboard interactions

Command	Description
Space/Enter	Open the menu and the sub-menus. When you open the menu, the focus move to the first option.
Up & Down	Once you have open the menu. You can move between options with the `up` and `down` keys. The focus indicator loops, so when you are at the last option and press `down` it will focus on the first option. And if you are at the first option and press `up` it'll focus the last option.
Right	When you are in a sub-menu option `right` key open it and the focus move to the first option.
Right & Esc	This keys close the menu. But, when you are in a sub-menu `right` & `esc` keys close it and the focus move parent option. This works from any option, doesn't matter where you are.

WAI-ARIA

Attribute	Value	Description	User suppliedSpecifies whether the attribute is always set in the component (no) or it needs to be provided by the developer (yes)
`role`	`'button'`	`sl-button` as part of `sl-menu-button` has a role of button.	no
`aria-expanded`	boolean	Set to `true` if the `sl-menu` is visible (opened), `false` if it is hidden.	no
`aria-details`	string	Used to link the menu element with the button (that triggers the menu component). It contains `id` of the menu element and is added to the button element.	no
`aria-label`	string	Please add when only icon button is used (so no text for the menu button is added).	yes
`aria-disabled`	boolean	Announces the menu button component as disabled with a screen reader. See [Note 1] below.	yes

Attribute	Value	Description	User supplied
`role`	`'menu'`	Declare component as a menu.	no

Attribute	Value	Description	User supplied
`role`	`'menuitem'`	Declare an element as an menu item.	no
`aria-expanded`	boolean	Added when menu item is expandable and connected with another menu element (submenu). Set to `true` if the `sl-menu` (submenu) is visible (opened), `false` if it is hidden.	no
`aria-details`	string	Used to link the menu (submenu) element with the expandable menu item (that triggers the [sub]menu). It contains `id` of the menu (submenu) and is added to the menu item element.	no
`aria-disabled`	boolean	Announces the menu item component as disabled with a screen reader. See [Note 1] below.	yes
`aria-label`	string	Can be added when there is no label/text that could be described by. eg. when there is only an icon added.	yes

Notes:

The aria-disabled should not be used as a one-for-one replacement for the disabled attribute because they have different functionalities:

disabled dims the menu button/menu item visually, takes it out of the tab-focus sequence, prevents actions (click, enter) on it and announces it as 'dimmed' or 'disabled' in a screen reader.
aria-disabled only does the latter. You will need to disable the functionality yourself. This might be useful for scenarios where you don't want to take the menu button / menu item out of the navigation flow.

When disabled is added there is no need to also add aria-disabled. Everything aria-disabled does, disabled does as well. You can read more on the difference and in which scenarios which option might be preferable on the MDN page about aria-disabled.

Interactive example

Menu

When to Use

Contextual Actions

Reducing Visual Clutter

When not to Use

Primary Navigation

Anatomy

Options

Behaviours

Grouped Options

Overflow Content

Shortcut Options

Menu button API

Properties

Methods

Slots

CSS Parts

Menu item group API

Properties

Slots

Menu item API

Properties

Events

Slots

CSS Parts

Menu API

Properties

Events

Slots

CSS Properties

Keyboard interactions

WAI-ARIA

Menu button

Menu

Menu item