menus

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 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 (you should use JavaScript to disable focus for any disabled 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

Mobile

On mobile devices, such as phones and other devices that have touch as the primary method of interaction, menus will have an increased button size to accommodate tapping with a finger instead of the more precise mouse cursor as well as larger text size.

Below is a live example of what to expect in that context. No code changes are needed in the Salesforce platform context as this change occurs automatically in the appropriate context. For those users not on the Salesforce platform, these modifications will occur automatically when the secondary touch stylesheet is loaded and the device has touch as the primary method of interaction.

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" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">

With Subheaders

Accessible Role

A subheading must have role="separator" 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" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">

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" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">

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" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">

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" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">

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 itsmenuitemcheckbox 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" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">

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" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">

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="javascript:void(0);" 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" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">

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" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">

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="javascript:void(0);" aria-haspopup="true" aria-expanded="true" tabindex="-1">...</a>
  <div class="slds-dropdown slds-dropdown_submenu slds-dropdown_submenu-left">

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" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">

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" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">

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-border-filled slds-button_icon-x-small" aria-haspopup="true" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">

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" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">

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" title="Show More">
    <svg class="slds-button__icon" aria-hidden="true">

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>