Components

Picklist

Picklists, commonly known as dropdown menus, allow the user to select one option or multiple options from a list. Picklists are used instead of radio lists and checkbox lists inside of a larger form. They provide more flexibility in the number of options the user can choose from.

BaseBase › ClosedBase › OpenBase › Item selectedBase › Multiple items selectedBase › Closed - Multiple items selectedBase › With HeaderBase › AutocompleteBasedev readyNot Compatible with S1 Mobile

Preview

Code

<div class="slds-picklist slds-dropdown-trigger slds-dropdown-trigger--click">
  <div class="slds-form-element">
    <label class="slds-form-element__label" for="text-input-01">Categories</label>
    <div class="slds-form-element__control slds-input-has-icon slds-input-has-icon--right slds-picklist__input">
      <input type="search" id="text-input-01" class="slds-lookup__search-input slds-input" placeholder="Select an Option" aria-owns="option-list-01" role="combobox" aria-activedescendant="" aria-expanded="false" readonly="" />
      <button class="slds-button slds-input__icon slds-text-color--default" aria-expanded="false" tabindex="-1" title="settings">
        <svg class="slds-button__icon slds-button__icon" aria-hidden="true">
          <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#down"></use>
        </svg>
        <span class="slds-assistive-text">Expand category options</span>
      </button>
    </div>
  </div>
  <div class="slds-dropdown slds-dropdown--left" role="listbox">
    <ul id="option-list-01" class="slds-dropdown__list slds-dropdown--length-5" role="presentation">
      <li role="presentation">
        <span class="slds-lookup__item-action slds-lookup__item-action--label" role="option" tabindex="0" id="listbox-option-242">
          <svg class="slds-icon slds-icon--selected slds-icon--x-small slds-icon-text-default slds-m-right--x-small slds-shrink-none" aria-hidden="true">
            <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#check"></use>
          </svg>
          <span class="slds-truncate">Option A</span>
        </span>
      </li>
      <li role="presentation">
        <span class="slds-lookup__item-action slds-lookup__item-action--label" role="option" tabindex="-1" id="listbox-option-243">
          <svg class="slds-icon slds-icon--selected slds-icon--x-small slds-icon-text-default slds-m-right--x-small slds-shrink-none" aria-hidden="true">
            <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#check"></use>
          </svg>
          <span class="slds-truncate">Option B</span>
        </span>
      </li>
      <li role="presentation">
        <span class="slds-lookup__item-action slds-lookup__item-action--label" role="option" tabindex="-1" id="listbox-option-244">
          <svg class="slds-icon slds-icon--selected slds-icon--x-small slds-icon-text-default slds-m-right--x-small slds-shrink-none" aria-hidden="true">
            <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#check"></use>
          </svg>
          <span class="slds-truncate">Option C</span>
        </span>
      </li>
      <li role="presentation">
        <span class="slds-lookup__item-action slds-lookup__item-action--label" role="option" tabindex="-1" id="listbox-option-245">
          <svg class="slds-icon slds-icon--selected slds-icon--x-small slds-icon-text-default slds-m-right--x-small slds-shrink-none" aria-hidden="true">
            <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#check"></use>
          </svg>
          <span class="slds-truncate">Option D</span>
        </span>
      </li>
      <li role="presentation">
        <span class="slds-lookup__item-action slds-lookup__item-action--label" role="option" tabindex="-1" id="listbox-option-246">
          <svg class="slds-icon slds-icon--selected slds-icon--x-small slds-icon-text-default slds-m-right--x-small slds-shrink-none" aria-hidden="true">
            <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#check"></use>
          </svg>
          <span class="slds-truncate">Option E</span>
        </span>
      </li>
      <li role="presentation">
        <span class="slds-lookup__item-action slds-lookup__item-action--label" role="option" tabindex="-1" id="listbox-option-247">
          <svg class="slds-icon slds-icon--selected slds-icon--x-small slds-icon-text-default slds-m-right--x-small slds-shrink-none" aria-hidden="true">
            <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#check"></use>
          </svg>
          <span class="slds-truncate" title="Option FGHIJKLMNOPQRSTUVWXYZ">Option FGHIJKLMNOPQRSTUVWXYZ</span>
        </span>
      </li>
    </ul>
  </div>
</div>

Component Overview

A picklist extends a menu dropdown.

A picklist is a list of actionable items that is invoked by selection of a particular item. That value is then shown as selected and its value is updated within the .slds-picklist__label.

A multi-select picklist is a list of actionable items that is invoked by selection of a particular item(s). The multi-select picklist can have more than one selected option. When more than one option has been selected, the .slds-picklist__label test should update with the total number of selected items, such as "3 options selected". When the picklist loses focus but has items selected, a .slds-pill_container--bare should be display below the .slds-picklist__label with the selected items in pills, allowing a user to easily remove selected items.

The unordered menu list with [role="menu"] should be contained in a <div> with the class .slds-dropdown. The exception to this is the Action Overflow for Touch, which not a dropdown menu.

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

Accessibility

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.

Expected markup:

  • Menu trigger is a focusable element (<a> or <button>) with aria-haspopup="true"
  • Menu has role="menu" and an aria-labelledby attribute whose value is the id of the menu trigger
  • Menu items have role="menuitem", role="menuitemcheckbox", or role="menuitemradio"

Expected keyboard interactions:

  • Arrow keys cycle focus through menu items (you should use JS to disable focus for any disabled items)
  • Tab key closes menu and moves focus to the next focusable element on the page
  • Esc key closes 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

Usage

This table gives you a quick overview of the SLDS CSS classes that can be applied to this component.
Class NameUsage
.slds-picklist
Applied to:

<div>

Outcome:

Initializes picklist

Required:

Required

Comments:

--

.slds-picklist--fluid
Applied to:

.slds-picklist

Outcome:

Forces width of picklist and picklist dropdown to inherit width of its content

Required:

No, optional element or modifier

Comments:

--

.slds-picklist__label
Applied to:

<button>

Outcome:

Custom select

Required:

Required

Comments:

--