Lookup is an autocomplete combobox that will search against a database object.

Relate To

About Lookups#

Note — A lookup is a combobox component, please find implementation documentation under the combobox component.

The lookup can parse through single or multi scoped datasets. The parsed dataset can be filtered by single or multi option selects.

You can find the lookup component throughout most data fields that allow inline inputs. Most commonly used on record home and object home.

Accessibility#

Lookups allow the user to have dual keyboard focus: while focus in the input search field, the user can type text into the field and simultaneously use arrow keys to navigate up and down the results list. Use the appropriate ARIA attributes in your markup in order to effectively communicate the relationship between the input field and the results list to users of assistive technology.

Expected 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
aria-activedescendant must be set to the currently selected option within the list
role="listbox" must be added to the list of results, each result should have role="option"

Expected keyboard interactions:

Up and Down arrow keys to cycle through the available options in the list, also updates aria-activedescendant on the input
Enter selects the current option and collapses the list
Escape collapses the list
Character keys jumps to the first option with those characters

Base#

Relate To

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

States#

Focused#

Relate To

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

Open - Item Focused#

Relate To

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

Displaying options based on user input#

Relate To

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

Option Selected#

Relate To

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-5" id="combobox-label-id-16">Relate To</label>
  <div class="slds-form-element__control">
    <div class="slds-combobox_container slds-has-selection">

Grouped#

Accounts

5 Results, sorted by relevancy
Account Name	Location	Secondary Column	Tertiary Column
Acme Landscape	Seattle, WA	Secondary Field	Tertiary Field
ACME Construction	San Francisco, CA	Secondary Field	Tertiary Field
Action Sports	Madison, WI	Secondary Field	Tertiary Field
Moderno Bistro	Acton, OH	Secondary Field	Tertiary Field
Cozy Kitchen	Acton, CA	Secondary Field	Tertiary Field

<div class="demo-only" style="height:640px">
  <section role="dialog" tabindex="-1" aria-modal="true" class="slds-modal slds-fade-in-open slds-modal_large">
    <div class="slds-modal__container">
      <button class="slds-button slds-button_icon slds-modal__close slds-button_icon-inverse">

Multi Entity#

Relate To

Filter Search by:

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

States#

Focused#

Relate To

Filter Search by:

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

Open - Item Focused#

Relate To

Filter Search by:

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

Option(s) Selected#

Relate To

Filter Search by:

AccountSalesforce Inc.
AccountDickenson plc

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-3">Relate To</label>
  <div class="slds-form-element__control">
    <div class="slds-combobox-group slds-has-selection">

Focused - Option(s) Selected#

Relate To

Filter Search by:

AccountSalesforce Inc.
AccountDickenson plc

<div class="slds-form-element">
  <label class="slds-form-element__label" for="combobox-id-4">Relate To</label>
  <div class="slds-form-element__control">
    <div class="slds-combobox-group slds-has-selection">

Overview of CSS Classes#

Selector: The CSS class being referred to.
Summary: A description of what the class does.
Support: Whether the class name is dev-ready (meaning it's fully vetted and tested and safe to use) or prototype (which means it's not fully vetted yet).
Restrict: The selector that the class name is allowed to be used on.
Variant: The base level pattern for a component. A variant can be extended to create another variant of that component, for example, a stateful button is a derivative of the base button.
Modifier: A single class that can be added to an HTML element of a component to modify its output. Typically these will be colors, sizing and positioning.

Selector	`.slds-combobox-group`
Summary	Container for a combobox group
Support	dev-ready
Restrict	`div`
Variant	True

Selector	`.slds-combobox_object-switcher`
Summary	Modifier that identifies the combobox as the object switcher, applies specific interactions for its context
Restrict	`.slds-combobox-group div`

Selector	`.slds-has-selection`
Summary	Modifier that notifies the combobox group that a selection has been made
Restrict	`.slds-combobox-group, .slds-combobox_container`

Selector	`.slds-combobox-addon_start`
Summary	The first combobox in the combobox group
Restrict	`.slds-combobox-group div`

Selector	`.slds-combobox-addon_end`
Summary	The last combobox in the combobox group
Restrict	`.slds-combobox-group div`

Selector	`.slds-listbox_selection-group`
Summary	The container of pill selections found inside of a combobox group
Restrict	`.slds-combobox-group ~ div, .slds-combobox_container ~ div`

Selector	`.slds-listbox`
Summary	Listbox container
Support	dev-ready
Restrict	`.slds-dropdown ul, .slds-dueling-list__options ul, .slds-pill_container ul, .slds-listbox_selection-group ul, .slds-combobox_container ul, .slds-form-element__control ul, .slds-popover__body ul`
Variant	True

Selector	`.slds-listbox_inline`
Summary	Inline listbox
Restrict	`.slds-listbox`
Modifier	True

Selector	`.slds-listbox_horizontal`
Summary	Horizontal listbox
Restrict	`.slds-listbox`
Modifier	True

Selector	`.slds-listbox__item`
Summary	Listbox item
Restrict	`.slds-listbox > li`

Selector	`.slds-listbox__option`
Summary	Choosable option within listbox
Restrict	`.slds-listbox__item > div`

Selector	`.slds-listbox__option-header`
Summary	Header for choosable option within listbox
Restrict	`.slds-listbox__option h3`

Selector	`.slds-listbox__option-icon`
Summary	Container for listbox option icon
Restrict	`.slds-listbox__option span`

Selector	`.slds-has-focus`
Summary	Focus state of a vertical listbox option
Restrict	`.slds-listbox__option`
Modifier	True

Selector	`.slds-listbox__option_entity`
Summary	Modifies the listbox option if it contains an entity object
Restrict	`.slds-listbox__option`

Selector	`.slds-listbox__option_plain`
Summary	Modifies the listbox option if it contains an plain object or string
Restrict	`.slds-listbox__option`

Selector	`.slds-listbox__option_has-meta`
Summary	If the listbox option has metadata or secondary information that sits below its primary text
Restrict	`.slds-listbox__option`

Selector	`.slds-is-selected`
Summary	Modifier that makes selected icon visible
Restrict	`.slds-listbox__option`
Modifier	True

Selector	`.slds-listbox__option-text_entity`
Summary	The main text of an entity listbox
Restrict	`.slds-listbox__option span`

Selector	`.slds-listbox__option-meta`
Summary	The metadata or secondary text of an entity listbox
Restrict	`.slds-listbox__option span`

Selector	`.slds-listbox__icon-selected`
Summary	The icon within a plain listbox that indicates if an option has been selected or not.
Restrict	`.slds-listbox__item svg`

Selector	`.slds-listbox_vertical`
Summary	Creates a vertical listbox
Restrict	`.slds-listbox`
Modifier	True

Selector	`.slds-dropdown_length-5`
Summary	Forces overflow scrolling after 5 list items
Restrict	`.slds-dropdown, .slds-dropdown__list, .slds-listbox`
Modifier	True

Selector	`.slds-dropdown_length-7`
Summary	Forces overflow scrolling after 7 list items
Restrict	`.slds-dropdown, .slds-dropdown__list, .slds-listbox`
Modifier	True

Selector	`.slds-dropdown_length-10`
Summary	Forces overflow scrolling after 10 list items
Restrict	`.slds-dropdown, .slds-dropdown__list, .slds-listbox`
Modifier	True

Selector	`.slds-dropdown_length-with-icon-5`
Summary	Forces overflow scrolling after 5 list items with an icon
Restrict	`.slds-dropdown, .slds-dropdown__list, .slds-listbox`
Modifier	True

Selector	`.slds-dropdown_length-with-icon-7`
Summary	Forces overflow scrolling after 7 list items with an icon
Restrict	`.slds-dropdown, .slds-dropdown__list, .slds-listbox`
Modifier	True

Selector	`.slds-dropdown_length-with-icon-10`
Summary	Forces overflow scrolling after 10 list items with an icon
Restrict	`.slds-dropdown, .slds-dropdown__list, .slds-listbox`
Modifier	True

Selector	`.slds-is-expanded`
Summary	Expanded state of a selection group
Restrict	`.slds-listbox_selection-group`

Selector	`.slds-listbox-toggle`
Summary	Toggle button to show all of the pill selections
Restrict	`.slds-listbox_selection-group > span`

Selector	`.slds-combobox`
Summary	Container that manages layout when a listbox of pill options sit next to a combobox search input
Support	dev-ready
Restrict	`div`
Variant	True

Selector	`.slds-is-open`
Summary	Opens listbox dropdown
Restrict	`.slds-combobox`
Modifier	True

Selector	`.slds-combobox__form-element`
Summary	Form element with combobox input
Restrict	`.slds-combobox > div`

Selector	`.slds-combobox__input-entity-icon`
Summary	If readonly selection is an entity, use this class
Restrict	`.slds-combobox__form-element span`

Selector	`.slds-combobox__input`
Summary	Input field within a combobox
Restrict	`.slds-combobox__form-element input, .slds-combobox__form-element button`

Selector	`[aria-autocomplete="list"]`
Summary
Support	dev-ready
Restrict	`.slds-combobox__input`
Variant	True

Selector	`.slds-combobox__input-value`
Summary	Class to target styling the value of a combobox input
Restrict	`.slds-combobox__input`

Selector	`.slds-has-focus`
Summary	Force focus state of the input
Restrict	`.slds-combobox__input`

Selector	`.slds-has-icon_left`
Summary	Modifier to the combobox when an SVG icon sits adjacent to the combobox form element
Restrict	`.slds-combobox`

Lookups Release Notes

2.16.0

Changed

Updated combobox to ARIA 1.2 compliance.

2.13.1

Fixed

Small improvements to the UI text.

2.13.0

Changed

The assistive text for the listbox of pills has been moved out of the individual pills to remove repetition for users with screenreaders.

2.11.0

Added

Grouped Lookup wrapping <div> attributes:
- role="combobox"
- aria-haspopup="listbox"
- aria-expanded="true"
Grouped Lookup <input> attribute aria-controls set to id of adjacent table

Changed

Grouped Lookup <input> role from combobox to textbox

Sections

About Lookups#

Accessibility#

Base#

States#

Focused#

Open - Item Focused#

Displaying options based on user input#

Option Selected#

Grouped#

Multi Entity#

Suggested for you

States#

Focused#

Suggested for you

Open - Item Focused#

Suggested for you

Option(s) Selected#

Suggested for you

Focused - Option(s) Selected#

Suggested for you

Overview of CSS Classes#

What are these categories?

Lookups Release Notes

2.16.0

Changed

2.13.1

Fixed

2.13.0

Changed

2.11.0

Added

Changed