Combobox

lightning:combobox is an input element that enables single selection from a list of options. The result of the selection is stored as the value of the input. Multiple selection is currently not supported. To support multiple selection, use lightning:dualListbox instead.

This component implements styling from combobox in the Lightning Design System.

This example creates a list of options during init, with a default selection that’s specified with the value attribute. The options attribute specifies the name of an array of items for the dropdown list.

1<aura:component>
2  <aura:attribute name="statusOptions" type="List" default="[]" />
3  <aura:handler name="init" value="{! this }" action="{! c.loadOptions }" />
4  <lightning:combobox
5    aura:id="selectItem"
6    name="status"
7    label="Status"
8    placeholder="Choose Status"
9    value="new"
10    onchange="{!c.handleOptionSelected}"
11    options="{!v.statusOptions}"
12  />
13</aura:component>

In your client-side controller, define an array of options and assign it to the statusOptions attribute. Each option corresponds to a list item on the dropdown list. Define the content of each option by specifying a value property and a label property. The label value is displayed for the item in the rendered dropdown list, while the value property’s value is stored when the item is selected.

Define an optional description property to add a line of descriptive text for each option. The descriptive text displays below the label of the list item. When adding descriptions, specify a description for each item in a list. If some items are missing descriptions, the text of the items can be misaligned.

1({
2  loadOptions: function (component, event, helper) {
3    var options = [
4      { value: "new", label: "New", description: "A new item" },
5      {
6        value: "in-progress",
7        label: "In Progress",
8        description: "Currently working on this item",
9      },
10      {
11        value: "finished",
12        label: "Finished",
13        description: "Done working on this item",
14      },
15    ];
16    component.set("v.statusOptions", options);
17  },
18  handleChange: function (cmp, event) {
19    // Get the string of the "value" attribute on the selected option
20    var selectedOptionValue = event.getParam("value");
21    alert("Option selected with value: '" + selectedOptionValue + "'");
22  },
23});

Selecting an option triggers the onchange event, which calls the handleChange client-side controller. To check which option has been clicked, use event.getParam("value"). Calling cmp.find("mycombobox").get("v.value"); returns the currently selected option.

By default, the combobox options don’t include an icon. To include an SLDS icon on the options, use the button variant. This variant supports options with and without icons. Consider these icon behaviors:

• The icon is placed before the option label
• The icon size is xx-small (14 px)
• Each option can have a unique SLDS icon

Visit icons to view the available icons.

To create a combobox with a unique SLDS icon on each option, use the button variant with the iconName property on the options.

1<aura:component>
2  <aura:attribute name="options" type="List" default="[
3      {'label': 'Slack', 'value': 'new', iconName: 'standard:slack'},
4      {'label': 'In Progress', 'value': 'inProgress', iconName: 'utility:filter'},
5      {'label': 'Finished', 'value': 'finished', iconName: 'utility:archive'},
6      ]"/>
7  <lightning:combobox
8    variant="button"
9    name="progress"
10    label="Status"
11    value="inProgress"
12    placeholder="Select Progress"
13    options="{! v.options }" />
14</aura:component>

When you select an option from the list, the icon and label are shown on the button.

Client-side input validation is available for this component. You can require the user to make a selection by setting required="true". An error message is automatically displayed when an item is not selected and required="true".

To check the validity states of an input, use the validity attribute, which is based on the ValidityState object. You can access the validity states in your client-side controller. This validity attribute returns an object with boolean properties.

You can override the default message by providing your own value for messageWhenValueMissing.

To programmatically display error messages on invalid fields, use the reportValidity() method. For custom validity error messages, display the message using setCustomValidity() and reportValidity(). For more information, see the lightning:input documentation.

Special characters like " must be escaped. For example, you want to display "New".

1var options = [
2  { value: '"new"', label: '"New"' },
3  { value: "expired", label: "Expired" },
4];

When using single quotes in your value, escape the quote with a double slash instead of a single slash.

lightning:combobox doesn’t currently support autocomplete or typeahead. The autocomplete attribute is reserved for internal use.

In Lightning Experience, a lightning:combobox dropdown list that’s opened overlays the record edit page or modal, the global header, and record form footer when scrolling.

On mobile devices, lightning:combobox has the following limitations.

• The dropdown menu doesn’t scroll correctly when there isn’t enough room to display the complete list of options.
• The mobile viewport doesn’t display the dropdown menu correctly especially if the component is placed near the bottom of the page.

We recommend using the lightning:select component on mobile instead.

You must provide a text label for accessibility to make the information available to assistive technology. The label attribute creates an HTML label element for your input component. To hide a label from view and make it available to assistive technology, use the label-hidden variant.

This component uses button elements for select-only comboboxes to comply with the Lightning Design System combobox blueprint.

When an option label is too long to fit in a single line, the label wraps and continues in a new line. If a long word in an option label isn’t fully visible, scroll horizontally on the dropdown list to reveal the whole word.