combobox

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-3">Relate to</label>
  <div class="slds-form-element__control">

Base Combobox

A Base Combobox is a readonly text input that allows a user to select an option from a pre-defined list of options. It does not allow free form user input, nor does it allow the user to modify the selected value.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-1">Relate to</label>
  <div class="slds-form-element__control">

Combobox markup

• A Combobox must come with an associated label element, with an appropriate for attribute
• slds-combobox acts as the root node to the composite Combobox widget. It takes the role="combobox" attribute as a result
  • aria-haspopup="listbox" attribute is then applied to indicate the Combobox will display a popup, of type listbox
  • aria-expanded="true|false" attribute is applied to describe whether the popup of listbox is currently visible or not
• The element slds-combobox__form-element between the combobox and its input must have role="none"

Input markup

• The input is an input with a role of textbox. The role is implicit on inputs, but in this case it doesn't hurt to be explicit
• The input has the following attributes:
  • autocomplete="off" to remove the browsers' suggestions from the input
  • aria-controls="" which points to the ID of the listbox. It informs assistive technology what DOM node the input controls, in terms of visibility and / or content
  • type attribute set to be text as it's not a search field
  • readonly

Mobile

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

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.

Displaying options

To toggle visibility of the listbox, add the class slds-is-open to the slds-dropdown-trigger element.

It is most common to expand the listbox of options when a user clicks on the Combobox. For a more detailed description of interaction behaviors, see the Interaction section.

Accessibility Requirement

When toggling visibility of the Combobox, the aria-expanded attribute needs to be toggled to true. Set it to false again when the options are hidden.

Accessibility Note

The listbox of options must be an owned child of the combobox. If it cannot be a direct child of the combobox element, then aria-owns must be placed on the combobox and point to the ID of the listbox instead.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-3">Relate to</label>
  <div class="slds-form-element__control">

Listbox markup

• The listbox has role="listbox" applied
• The listbox can have child options. We place role="option" on a div element, inside a list item. As such the list item li needs to be removed from the Accessibility Tree with role="presentation"
• A listbox has the ability to group options together under a visual heading or label. This means the role="listbox" attribute is placed on a common parent element, which can wrap multiple lists (or groups) of options
  • When a listbox has no option groups, the ul element has role="presentation" to remove it from the Accessibility Tree
• Every option has aria-selected="false" by default
• Focused options should have aria-selected="true"
• Chosen optionss should have aria-checked="true"
• Disabled options should have aria-disabled="true" applied along with a class on the icon in an entity option

Loading more options

If you are dynamically loading in more items to the listbox, the very last <li> of the <ul> should receive the role="presentation" attribute and have the Spinner component injected into it.

For layout purposes, wrap the spinner in a <div> with the class slds-align_absolute-center to position the spinner in the middle of the list item, as well as slds-p-top_medium to provide the appropriate amount of space for the spinner to be visible.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-9">Relate to</label>
  <div class="slds-form-element__control">

Grouped options

Options within a listbox can be grouped together under meaningful headings. This is useful if you wish to create separation between 2 or more sets of options within a single listbox.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-10">Relate to</label>
  <div class="slds-form-element__control">

Grouped listbox markup

• When a listbox has option groups, each group gets a visual label. Exactly like optgroup in a select element
  • The ul element in this case has role="group" with an aria-label that matches the visible label
  • Display the group label visually, but due to the way a listbox works it can only be marked as role="presentation", as a listbox can only have option children. This allows us to communicate the group label visually and programmatically to a screen reader

Styling choices for options

The options in the listbox can have a left icon and/or metatext.

<div id="listbox-id-2" class="slds-dropdown slds-dropdown_length-5 slds-dropdown_fluid" role="listbox">
  <ul class="slds-listbox slds-listbox_vertical" role="presentation">
    <li role="presentation" class="slds-listbox__item">

Disabled listbox items

Options in a listbox that are disabled require these accessibility and styling considerations:

• aria-disabled="true" must be applied to slds-listbox__option
• if using an entity icon, apply slds-icon_disabled to slds-icon_container

Plain options: Example shows two disabled options with one enabled one

<div id="listbox-id-2" class="slds-dropdown slds-dropdown_length-5 slds-dropdown_fluid" role="listbox">
  <ul class="slds-listbox slds-listbox_vertical" role="presentation">
    <li role="presentation" class="slds-listbox__item">

Entity options: Example shows two disabled entity options with one enabled one

<div id="listbox-id-3" class="slds-dropdown slds-dropdown_length-with-icon-7 slds-dropdown_fluid" role="listbox">
  <ul class="slds-listbox slds-listbox_vertical" role="presentation">
    <li role="presentation" class="slds-listbox__item">

Interaction

At its most basic, the listbox of options should be displayed when a user interacts with the Combobox. When the user leaves the combobox the options are hidden. However, there are some differences when interacting with a Combobox with a mouse versus with a keyboard.

Expanding the Combobox

A mouse or pointer device user can click on a Combobox and the listbox will display automatically whilst focus is placed inside the Combobox input field.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-3">Relate to</label>
  <div class="slds-form-element__control">

If using a keyboard, placing focus into the Combobox input field will not display the listbox of options automatically.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-2">Relate to</label>
  <div class="slds-form-element__control">

After focusing inside the Combobox with the keyboard, pressing the Down or Enter key will expand the collapsed Combobox and display the listbox options. Be sure to update aria-expanded to be true. This will also highlight the first option in the listbox.

Accessibility Requirement

Update aria-expanded to "true" when the Combobox is expanded.

Highlighting an option

To Highlight an option in the Listbox use the Up and Down arrow keys to cycle through all the available options in the list.

• Each press of the arrow key must update the input value to reflect the currently selected option
• It is common to loop the selected option to the first option when you get to the last option in the list. Similarly, loop to the last option when you reach the first option.

When an option from the listbox is "in focus", user focus never leaves the input field, since we manually create a programmatic or "faux focus" state that highlights the selected option and associates it to the input.

Accessibility Requirement

When highlighting an option with "faux focus", the aria-activedescendant attribute on the input needs to be set to the value of the ID of the highlighted option. The highlighted option must also have aria-selected="true". When no option is highlighted, aria-activedescendant must be removed.

By typing the first letter of an option name, the first matching option will highlight. When the letter doesn't match an option, highlighting doesn't move.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-4">Relate to</label>
  <div class="slds-form-element__control">

Collapsing the Combobox

To collapse the Combobox the user should be able to press the Escape key on their keyboard or click anywhere outside of the Combobox.

Pressing the Enter key whilst an option is highlighted will select the option as the current value and collapse the Combobox.

Accessibility Requirement

Update aria-expanded to "false" when the Combobox is collapsed.

Selecting an option

A user selects an option by using their mouse to click the option they require, or pressing the Enter key once they have arrowed to the desired option.

Upon selection the Combobox collapses, only showing the input field. The value of the input inside the Combobox is set to match the selected option name so the user can see what was previously selected from the listbox of options.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-6">Relate to</label>
  <div class="slds-form-element__control">

Single selection

When an option becomes selected, the class slds-is-selected should be applied to the slds-listbox__option element with the role="option". This will provide visual feedback that the user has selected that element.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-5">Relate to</label>
  <div class="slds-form-element__control">

Re-opening with a selection

When re-opening a Combobox that already has a selected value, the listbox should be displayed with the selected option already highlighted.

Accessibility Requirement

Be sure to re-set the aria-activedescendant attribute on the `input` to the value of the ID of the highlighted option. The highlighted option must also have aria-selected="true".

Multiple selections

When more than one option has been selected, the value of the input should be updated with the total number of selected items, such as "3 options selected".

<div aria-checked="true" id="please-provide-a-unique-id" class="slds-media slds-listbox__option slds-listbox__option_plain slds-media_small slds-is-selected" role="option">
  <span class="slds-media__figure slds-listbox__option-icon">
    <span class="slds-icon_container slds-icon-utility-check slds-current-color">

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-7">Relate to</label>
  <div class="slds-form-element__control">

When a Combobox with multiple selected options is closed, a Listbox of Pills is also used to represent those selected options.

The Listbox of Pills is positioned below the read-only input, outside of the Combobox. Each pill represents a selected option. This allows a user to easily see and remove selected items from the Combobox without opening it again.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-8">Relate to</label>
  <div class="slds-form-element__control">

Editing multiple selections

The Listbox of Pills allows you to quickly remove selections without opening the Combobox by clicking the remove "x" or using your delete key.

The Listbox of Pills acts as a single focusable element. Using the arrow keys whilst focused on the first pill will cycle the user through the pill options.

Autocomplete Combobox

An autocomplete Combobox also allows a user to select an option from a list, but that list can be affected by what the user types into the input of the Combobox. This can be useful when the list of options is very large, as user input can start to display options that only match the text they have entered.

If no option matches, the user can complete the value of the combobox by finishing their own text entry.

Accessibility Difference

The difference between the Base Combobox and the Autocomplete Combobox, is that the text input must have the readonly attribute removed and replaced with aria-autocomplete="list".

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-11">Relate to</label>
  <div class="slds-form-element__control">

Displaying options

Displaying options for the Autocomplete Combobox happens just like the base Combobox, except there is no difference between mouse and keyboard users when interacting with the Combobox for the first time. Clicking or placing focus on the Combobox text input will automatically expand the Combobox and display the options.

When a user stops interacting with the Combobox, or selects an option, the Combobox collapses and hides the options.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-12">Relate to</label>
  <div class="slds-form-element__control">

Displaying options based on user input

If an option from the pre-populated listbox isn't what the user wants, they can start typing into the input. This term will be used to filter the options by and narrow down the size of the list to something more relevant.

Whilst typing, the highlighted option in the listbox should be the user's text string.

Accessibility Requirement

When highlighting an option with "faux focus", the aria-activedescendant attribute on the `input` needs to be set to the value of the ID of the highlighted option. The highlighted option must also have aria-selected="true".

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-14">Relate to</label>
  <div class="slds-form-element__control">

Drill In for Autocomplete

The options in the autocomplete listbox can have a right icon to indicate an option that drills in for more options.

<div id="listbox-id-3" class="slds-dropdown slds-dropdown_length-with-icon-7 slds-dropdown_fluid" role="listbox">
  <ul class="slds-listbox slds-listbox_vertical" role="presentation">
    <li role="presentation" class="slds-listbox__item">

Keyboard interaction

The same keyboard interactions apply from the base Combobox, but with these differences:

• Up and Down arrows should optionally update the input value to reflect the currently selected option

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-16">Relate to</label>
  <div class="slds-form-element__control">

Selecting an option

The user again can click on the desired option or press the Enter key with the desired option highlighted. Alternatively they can leave their entered text string as the value of the Combobox.

Selecting an option from the listbox will close the listbox.

To remove the selected option, simply clear the text input.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-18">Relate to</label>
  <div class="slds-form-element__control">

Multiple selection

Multiple selection is much the same as the Base Combobox. A list of selected options are displayed below the Combobox as a Listbox of Pills.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-20">Relate to</label>
  <div class="slds-form-element__control">

Editing multiple selections

The Listbox of Pills allows you to quickly remove selections without opening the Combobox by clicking the remove "x" or using your delete key.

The Listbox of Pills acts as a single focusable element. Using the arrow keys whilst focused on the first pill will cycle the user through the pill options.

Entity Autocomplete Combobox (Lookup)

An Entity Autocomplete Combobox or Lookup, is used to search for and select Salesforce Entities.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-22">Relate to</label>
  <div class="slds-form-element__control">

Displaying options

Displaying options happens just like an Autocomplete Combobox, by placing user focus inside the Combobox text input.

The options now have extra information about them, such as the type of entity and any other important metadata.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-13">Relate to</label>
  <div class="slds-form-element__control">

Displaying options based on user input

As with the Autocomplete Combobox, the user can start typing into the input to search for Salesforce Entities that match their search term.

In the resultant displayed options, we highlight the matched term by bolding it using the <mark> element.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-15">Relate to</label>
  <div class="slds-form-element__control">

Keyboard interaction

The same keyboard interactions apply from the base Combobox, but with these differences:

• Up and Down arrows should not update the input value to reflect the currently selected option. The input value should only be updated upon selection.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-17">Relate to</label>
  <div class="slds-form-element__control">

Selecting an option

The user again can click on the desired option or press the Enter key with the desired option highlighted. The user can only select from the returned options; a plain text string is not a valid selection with the Entity Lookup.

The selected option is still set as the value of the text input, but this time we make the input look like a dismissible pill. This input becomes readonly at this point, so the user can no longer type into it.

To remove the selected option, simply press the Delete key when focused inside the text input or click the remove "x".

Accessibility Requirement

When the option is selected, make sure to add the readonly attribute to the text input. Be sure to remove it again when the option is cleared.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-19">Relate to</label>
  <div class="slds-form-element__control">

Multiple selection

Multiple selection is handled the same as the Base and Autocomplete Combobox, a list of selected entities is displayed under the combobox as a Listbox of Pills.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-21">Relate to</label>
  <div class="slds-form-element__control">

Mobile context changes

Please be aware that in a mobile context comboboxes with multiple selection will automatically change slightly as shown in the example below. For more details please see the mobile specific documentation above.

Grouped Comboboxes (Cross-entity / Polymorphic)

The Grouped Comboboxes should be used when a Combobox has another Combobox appended or prepended to itself.

The containing div of the comboboxes should have the class slds-combobox-group on it.

Keep in mind

The grouped combobox only accepts one addon, in addition to the primary combobox. Use the classes slds-combobox_addon-start and slds-combobox_addon-end to describe the position of the form element.

Accessibility Requirement

Be sure to set aria-controls on the Object Switcher, which points to the Search Combobox ID.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-24">Relate to</label>
  <div class="slds-form-element__control">

Mobile context changes

Please be aware that in a mobile context grouped comboboxes (cross-entity / polymorphic) will automatically change slightly as shown in the example below. For more details please see the mobile specific documentation above.

User input (Typeahead)

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-28">Relate to</label>
  <div class="slds-form-element__control">

User input (Typeahead) - Loading

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-30">Relate to</label>
  <div class="slds-form-element__control">

Selecting options

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-32">Relate to</label>
  <div class="slds-form-element__control">

User input with selection(s) made

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-34">Relate to</label>
  <div class="slds-form-element__control">

Selected options overflow

When a user is not focused on any element inside of the combobox group, the pill container should become collapsed to reduce vertical space.

The combobox group element needs the class slds-has-selection when a selection has been made. The pill selections are found inside of a Listbox of Pills located after the combobox group. It requires the class slds-listbox_selection-group to provide appropriate styling for the expanding and collapsing behavior of this region.

Collapsed

By default, the slds-listbox_selection-group is collapsed.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-36">Relate to</label>
  <div class="slds-form-element__control">

Expanded

When a user focuses on any element inside of the combobox group, the class slds-is-expanded should be applied to the slds-listbox_selection-group. The selection group should remain open until the user moves away from any element inside the combobox group.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-38">Relate to</label>
  <div class="slds-form-element__control">

For mouse users, clicking on the "+{x} more" text would expand the selection group and place the user's focus on the first pill inside the Listbox of Pills.

Scoping results

A grouped combobox is intended to be used to filter down or scope you search results. You can do so by interacting with the object switcher to scope down to an object type.

The containing element should receive the class slds-combobox_object-switcher and slds-combobox_addon-start.

Text variant

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-40">Relate to</label>
  <div class="slds-form-element__control">

Icon variant

Blurred

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-42">Relate to</label>
  <div class="slds-form-element__control">

Focused

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-44">Relate to</label>
  <div class="slds-form-element__control">

Combobox with a Dialog

If the data displayed within the dropdown of a combobox cannot be represented as a listbox (as shown above), tree, grid, or tree-grid, then the dropdown should be represented as a dialog, with role="dialog".

The key difference for dialog dropdowns lies in how they handle focus. In listbox dropdowns, users can enter values in the input while arrowing through the listbox options using aria-activedescendant. In dialog dropdowns, the dropdown becomes a focus trap, so users must have a way to clear or save any selections or changes made.

Implementation Details

1. 1. The input does not have `aria-autocomplete`, it is essentially readonly
2. 2. The input for this dialog variant will also never have `aria-activedescendant`
3. 3. The combobox `<div>` with `class="slds-combobox"` has `aria-haspopup=”dialog”`
4. 4. The dropdown is a dialog with `role="dialog"`
5. 5. The dialog should have an `aria-label` with a value for the dialog's title
6. 6. The combobox has `aria-expanded="false"` when the dialog is closed, and `aria-expanded="true"` when the dialog is open.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-55">Languages</label>
  <div class="slds-form-element__control">

Open Dialog

To open the dialog, remove the class slds-popover_hide from the <div> with class="slds-popover". Any content can go inside a dialog dropdown.

Accessibility Note

When the dialog is open, be sure to change `aria-expanded` to **true** on the combobox `<div>` with `class="slds-combobox"`.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-46">Languages</label>
  <div class="slds-form-element__control">

Keyboard Interaction

• Focusing on the input does not open the dropdown
• Typing in the input does nothing
• Pressing the down arrow from the input opens the dialog and moves the user's focus into the dialog.
• The dialog dropdown is a focus trap
  • Pressing the Tab key cycles the user through all UI elements in the dialog
• Pressing Escape closes the dialog and clears any changes
• Pressing the Cancel button closes the dialog and clears any changes
• Pressing the Save button updates the selected value in the input and closes the dialog

Focus Management

• Clicking on the input opens and focuses the cursor inside the dialog on the first focusable element.
• Placing focus on the input does not open the dialog
• Pressing the down arrow whilst focused on the input opens the dialog and moves focus to the first focusable element

Examples

Multiple Selection

Below is an example of a dialog combobox where users can make multiple selections using checkboxes. The main difference between the dialog variant of a multi-select combobox and the multi-select Entity Autocomplete involves the behavior after a selection is made. A dialog will not close after each selection, since it is a focus trap, while the listbox dropdown of the Entity Autocomplete example closes after each selection made, forcing users to re-open the listbox if they need to make another selection.

Dueling Picklist vs. Multi Select Combobox

We recommend using the Dueling Picklist when there are many items to choose from, such as “Select Country”. Use a multiselect combobox with a dialog when you have less horizontal real estate available and fewer items to select from.

Open

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-47">Languages</label>
  <div class="slds-form-element__control">

Open and Selecting

If nothing has been selected yet, the input's placeholder remains "Select an Option" or something similar.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-48">Languages</label>
  <div class="slds-form-element__control">

Closed with One Option Selected

When only one selection has been made, the input's value takes on the value of the selection - German in this case.

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-50">Languages</label>
  <div class="slds-form-element__control">

Open with One Option Selected

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-49">Languages</label>
  <div class="slds-form-element__control">

Closed with Two or More Options Selected

When more then one option has been selected, the input's value reads "{# of items selected} options selected".

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-52">Languages</label>
  <div class="slds-form-element__control">

Open with Two or More Options Selected

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-51">Languages</label>
  <div class="slds-form-element__control">