About Menu#

The unordered menu list <ul> with role="menu" should be contained in a <div> with the class .slds-dropdown.

The target HTML element and dropdown need to be wrapped in the class .slds-dropdown-trigger dropdown-trigger_click.

Accessibility#

Markup#

• The menu trigger is a focusable element (<a> or <button>) with aria-haspopup="true"
• The menu trigger has the aria-expanded attribute applied and the value is set to "true" or "false" depending on if the menu is open or not.
• The menu has role="menu" and an aria-label attribute whose value is the name of the menu trigger
• The menu items have role="menuitem", role="menuitemcheckbox", or role="menuitemradio", depending on the selection options

Keyboard Interactions#

The main thing that distinguishes menus from other popover blocks is keyboard navigation: elsewhere, users press the Tab key to navigate through actionable items, but in a menu, users press the arrow keys to navigate.

• Arrow keys cycle focus through menu items (including disabled menu items)
• If a menu item opens a submenu, pressing Enter or the right arrow key opens the submenu and focus goes to the first item in the submenu
• If a submenu is open, pressing the left arrow key closes the submenu and puts focus back on the menu item that opened the submenu
• Tab key closes the menu and moves focus to the next focusable element on the page
• Esc key closes the menu and moves focus back to the menu trigger
• Any character key moves focus to the next menu item that starts with that character, if applicable

Base#

<div class="slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <button class="slds-button slds-button_icon slds-button_icon-border-filled" aria-haspopup="true" aria-expanded="true" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#down"></use>

With Subheaders#

Accessible Role

A subheading must have role="presentation" on the <li> and the content inside the <li> should be in a <span>.

<li class="slds-dropdown__header slds-truncate" title="Menu Sub Heading" role="separator">
  <span>Menu Sub Heading</span>
</li>

<div class="slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <button class="slds-button slds-button_icon slds-button_icon-border-filled" aria-haspopup="true" aria-expanded="true" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#down"></use>

With Icons#

Icons can be included on either the left, right, or both sides of an option.

Accessibility Note

If using one of the icons to indicate selection (e.g. checkmarks), be sure to check out the Menus with Selectable Items docs for the Accessibility implications.

Icon on the Left#

<div class="slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <button class="slds-button slds-button_icon slds-button_icon-border-filled" aria-haspopup="true" aria-expanded="true" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#down"></use>

Icon on the Right#

<div class="slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <button class="slds-button slds-button_icon slds-button_icon-border-filled" aria-haspopup="true" aria-expanded="true" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#down"></use>

Double Icon#

Accessibility Note

If using one of the icons to indicate selection (e.g. checkmarks), be sure to check out the Menus with Selectable Items docs.

<div class="slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <button class="slds-button slds-button_icon slds-button_icon-border-filled" aria-haspopup="true" aria-expanded="true" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#down"></use>

With Selectable Items#

When creating a menu with selectable items:

• All selectable items need the proper role, either role="menuitemcheckbox" or role="menuitemradio"
• All selectable items should contain an icon
• Each icon must have the class slds-icon_selected on the <svg>
  • This hides icons of non-selected items
• Items that have been selected need aria-checked="true" on the <a> element

Revealing Icons for Selected Items

A selected item reveals its icon when the class slds-is-selected is applied to the <li> and aria-checked="true" is applied to its menuitemcheckbox or menuitemradio child.

<li class="slds-dropdown__item slds-is-selected" role="presentation">
  <a role="menuitemcheckbox" aria-checked="true">...</a>
</li>

<div class="slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <button class="slds-button slds-button_icon slds-button_icon-border-filled" aria-haspopup="true" aria-expanded="true" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#down"></use>

With Status Notifications#

<div class="slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <button class="slds-button slds-button_icon slds-button_icon-border-filled" aria-haspopup="true" aria-expanded="true" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#down"></use>

To enable menu items to reflect status level notifications like Error, Success and Warning, place a modifier class onto the menuitem that has the offending notification.

The class is based on the slds-has-${level} pattern, where ${level} corresponds to the level you wish to set.

• slds-has-error
• slds-has-success
• slds-has-warning

<a class="slds-has-warning" href="#" role="menuitem" tabindex="-1">...</a>

Warning Icon

For warning level menu items it is required that you switch the icon to use the currentColor variant for icons.

With Overflow Scrolling#

<div class="slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <button class="slds-button slds-button_icon slds-button_icon-border-filled" aria-haspopup="true" aria-expanded="true" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#down"></use>

To force overflow scrolling after either 5, 7, or 10 items, add the modifier slds-dropdown_length-* to the <div> with class slds-dropdown where the * is either 5, 7, or 10.

<div class="slds-dropdown slds-dropdown_length-5">...</div>

Scrolling for Menu Items with Icons#

To force overflow scrolling after either 5, 7, or 10 items with icons, add the modifier slds-dropdown_length-with-icon-* to the <div> with class slds-dropdown where the * is either 5, 7, or 10.

<div class="slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <button class="slds-button slds-button_icon slds-button_icon-border-filled" aria-haspopup="true" aria-expanded="true" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#down"></use>

With a Submenu#

To create a menu with a submenu, add the slds-has-submenu class to the list item, <li>, that will open the submenu.

Accessibility Note

Any menu item that opens a submenu must have aria-haspop="true" on the <a> within the <li>. In order to open the submenu, set aria-expanded to true on that <a> when the user clicks or hovers over the list item, or presses enter while focused on the list item. Additionally, the submenu should have role="menu" and an aria-label attribute whose value matches the name of the <li> that opened the submenu.

<li class="slds-dropdown__item slds-has-submenu" role="presentation">
  <a role="menuitem" href="#" aria-haspopup="true" aria-expanded="true" tabindex="-1">...</a>
  <div class="slds-dropdown slds-dropdown_submenu slds-dropdown_submenu-left">
    <ul class="slds-dropdown__list" role="menu" aria-label="Name of Item that Opened this Menu">...</ul>
  </div>
</li>

Submenu to Right#

To open the submenu to the right of the main menu, add slds-dropdown_submenu-right to the <div> with the slds-dropdown_submenu class.

<div class="slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <button class="slds-button slds-button_icon slds-button_icon-border-filled" aria-haspopup="true" aria-expanded="true" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#down"></use>

Submenu to Left#

To open the submenu to the left, add slds-dropdown_submenu-left to the <div> with the slds-dropdown_submenu class.

<div class="slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <button class="slds-button slds-button_icon slds-button_icon-border-filled" aria-haspopup="true" aria-expanded="true" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#down"></use>

Overflow Menu with Actions#

For an overflow of action items, use the overflow menu with actions styling by adding the modifier slds-dropdown_actions to the div with class slds-dropdown. This pattern is typically used in conjunction with a button group.

<div class="slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <button class="slds-button slds-button_icon slds-button_icon-x-small slds-button_icon-border-filled" aria-haspopup="true" aria-expanded="true" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#down"></use>

Positioning#

There are 3 options for the positioning of the menu dropdown -- left, right, and bottom. To access these options, add a modifier to the <div> with class name slds-dropdown. For the standard positioning where the dropdown aligns with the left side of the dropdown trigger, use slds-dropdown_left, as seen above.

<div class="slds-dropdown slds-dropdown_left">...</div>

Positioned Right#

To position the dropdown to align with the right of the dropdown trigger, use slds-dropdown_right.

<div class="slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <button class="slds-button slds-button_icon slds-button_icon-border-filled" aria-haspopup="true" aria-expanded="true" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#down"></use>

Positioned Bottom#

To position the dropdown to sit on top of the dropdown trigger, use slds-dropdown_bottom.

<div class="slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open">
  <button class="slds-button slds-button_icon slds-button_icon-border-filled" aria-haspopup="true" aria-expanded="true" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#down"></use>

Width#

To adjust the width of the menu dropdown add modifier slds-dropdown_* to the <div> with class slds-dropdown where the * is xx-small, x-small, small, medium, or large.

<div class="slds-dropdown slds-dropdown_left slds-dropdown_medium">...</div>

Height#

To adjust the length of visible menu dropdown items before overflow scrolling activates, add modifier slds-dropdown_length-*, or when using icons, slds-dropdown_length-with-icon-*, where the * is 5, 7, 10. Apply the height classes to both the <div>s with class slds-dropdown and slds-dropdown__list

<div class="slds-dropdown slds-dropdown_left slds-dropdown_length-7">
  <ul class="slds-dropdown__list slds-dropdown_length-7">...</ul>
</div>