Combobox

lightning-combobox is an input element that enables single selection from a list of options. The result of the selection corresponds to the value of the input. Multiple selection is not supported. To support multiple selection, use lightning-dual-listbox instead.

This example creates a list of options 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<template>
2    <lightning-combobox
3        name="status"
4        label="Status"
5        placeholder="Choose Status"
6        value={value}
7        onchange={handleChange}
8        options={statusOptions}
9    >
10    </lightning-combobox>
11    <p>Selected option: {value}</p>
12</template>

lightning-combobox implements the combobox blueprint in the Salesforce Lightning Design System (SLDS). The combobox adapts to SLDS 1 or SLDS 2 styling based on the org’s theme or the container app that you use.

In your JavaScript, define an array of options. 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 dropdown list shows the label that you provide by using the label value. Select an item updates its corresponding value property.

Define an optional description property to add a line of descriptive text for each option. The descriptive text appears 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 alignment of the items can appear incorrect.

1import { LightningElement } from "lwc";
2export default class ComboboxExample extends LightningElement {
3  statusOptions = [
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
17  value = "new";
18
19  handleChange(event) {
20    // Get the string of the "value" attribute on the selected option
21    this.value = event.detail.value;
22  }
23}

Selecting an option triggers the change event, which calls the handleChange function. To check which option is clicked, use event.detail.value.

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<lightning-combobox
2    label="Filter"
3    variant="button"
4    value={filterValue}
5    options={filterOptions}
6    onchange={handleFilterChange}>
7</lightning-combobox>

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

1import { LightningElement } from "lwc";
2export default class ComboboxExample extends LightningElement {
3  filterValue = 'all';
4  get filterOptions() {
5      return [
6          { label: 'All Items', value: 'all', iconName: 'utility:filter' },
7          { label: 'Active Only', value: 'active', iconName: 'utility:check' },
8          { label: 'Archived', value: 'archived', iconName: 'utility:archive' },
9          { label: 'Pending', value: 'pending', iconName: 'utility:clock' },
10      ];
11  }
12  handleFilterChange(event) {
13          this.filterValue = event.detail.value;
14  }
15}

To create a combobox that appears pill-like without an icon, use the button variant without specifying iconName on the options.

Client-side input validation is available for this component. You can require the selection by adding the required attribute. An error message is automatically shown when an item isn’t selected on a required element.

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 JavaScript. This validity attribute returns an object with boolean attributes. See lightning-input for more information.

You can override the default message by providing your own value for message-when-value-missing.

Use a combination of variants and utility classes to customize your combobox styles.

Use the variant attribute with one of these values to apply styling.

• label-hidden hides the label but make it available to assistive technology
• label-inline horizontally aligns the label and combobox
• label-stacked to place the label above the combobox
• button presents a pill-shaped combobox with icon support. See Append an SLDS Icon.

To apply additional styling, use the SLDS utility classes with the class attribute,

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

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

When you use single quotes in the 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 these limitations.

• The dropdown menu doesn’t scroll correctly when there’s limited space to show the complete list of options.
• The mobile viewport doesn’t display the dropdown menu correctly, especially if you place the component near the bottom of the page.

We recommend that you use the HTML <select> element on mobile instead.

To enable record lookup in a combobox, use the lightning-record-picker component instead.

Provide a text label for accessibility to make the information available to assistive technology. The label attribute creates an HTML label element for your 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.

change

The event fired when an item is selected in the combobox.

The change event returns this parameter.

The event properties are as follows.

open

The event fired when the dropdown is opened.

The open event doesn’t return any parameters.