---
schema_version: "1"
id: 85ed87133fe86603a21ce4fa16cf1cd76ec31fcd3e9189543e7427f30e33ca57
title: Combobox
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/combobox/lightning-combobox.md
canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-combobox.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: c5794cdf87d890fab1e98457e6ad1fc4857e9f866ce4132f8b7b2127d0f123c4
products:
  - Lightning Component Reference
---

# Combobox

**`lightning-combobox`**

A widget that provides an input field that is readonly, accompanied by a dropdown list of selectable options.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="combobox" model="lwc" namespace="lightning"}


:::::

:::::tab

`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`](/docs/platform/lightning-component-reference/guide/lightning-dual-listbox.html) 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.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-combobox
        name="status"
        label="Status"
        placeholder="Choose Status"
        value={value}
        onchange={handleChange}
        options={statusOptions}
    >
    </lightning-combobox>
    <p>Selected option: {value}</p>
</template>
```
<!-- prettier-ignore-end -->

## Design

`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.

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Combobox](https://v1.lightningdesignsystem.com/components/combobox/)                                                                 | [Combobox](https://www.lightningdesignsystem.com/components/combobox/)                                          |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Create a Combobox

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.

```javascript
import { LightningElement } from "lwc";
export default class ComboboxExample extends LightningElement {
  statusOptions = [
    { value: "new", label: "New", description: "A new item" },
    {
      value: "in-progress",
      label: "In Progress",
      description: "Currently working on this item",
    },
    {
      value: "finished",
      label: "Finished",
      description: "Done working on this item",
    },
  ];

  value = "new";

  handleChange(event) {
    // Get the string of the "value" attribute on the selected option
    this.value = event.detail.value;
  }
}
```

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

## Append an SLDS Icon

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](https://v1.lightningdesignsystem.com/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.

<!-- prettier-ignore -->
```html
<lightning-combobox
  label="Filter"
  variant="button"
  value={filterValue}
  options={filterOptions}
  onchange={handleFilterChange}
>
</lightning-combobox>
```

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

```javascript
import { LightningElement } from "lwc";
export default class ComboboxExample extends LightningElement {
  filterValue = "all";
  get filterOptions() {
    return [
      { label: "All Items", value: "all", iconName: "utility:filter" },
      { label: "Active Only", value: "active", iconName: "utility:check" },
      { label: "Archived", value: "archived", iconName: "utility:archive" },
      { label: "Pending", value: "pending", iconName: "utility:clock" },
    ];
  }
  handleFilterChange(event) {
    this.filterValue = event.detail.value;
  }
}
```

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

## Input Validation

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](/docs/platform/lightning-component-reference/guide/lightning-input.html) for more information.

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

## Component Styling

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

### Variants

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](#append-an-slds-icon).

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute,

## Usage Considerations

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

```javascript
const options = [
  { value: '"new"', label: '"New"' },
  { value: "expired", label: "Expired" },
];
```

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](/docs/platform/lightning-component-reference/guide/lightning-record-picker.html) instead.

## Accessibility

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](https://v1.lightningdesignsystem.com/components/combobox/#%22Input%22-markup).

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.

When a validation error appears, `lightning-combobox` links the input to the error message using the `aria-describedby` attribute. The error message is wrapped in an element with `role="status"`, which announces it through a polite, non-interruptive live region. `lightning-combobox` doesn't use `role="alert"` or `aria-live="assertive"` for validation errors as these roles interrupt the user immediately. A validation error doesn't need immediate interruption as the component already blocks form submission until the error is corrected.

Some browser and screen reader combinations, such as Chrome with JAWS or NVDA on Windows, announce the error message twice when a user leaves the invalid field. However, this behavior ensures that the user is notified of the error, regardless of which browser or screen reader they use. For more information, see [_LinkedIn_:Balancing UX and Accessibility with Screen Readers and Error Messages](https://www.linkedin.com/pulse/balancing-ux-accessibility-screen-readers-error-zmdte/).

## Custom Events

**`change`**

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

The `change` event returns this parameter.

| Parameter     | Type   | Description                       |
| ------------- | ------ | --------------------------------- |
| selectedValue | string | The value of the selected option. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

**`open`**

The event fired when the dropdown is opened.

The `open` event doesn’t return any parameters.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | false | This event does not bubble.                                                                               |
| cancelable | false | This event has no default behavior that can be canceled. You can’t call `preventDefault()` on this event. |
| composed   | false | This event does not propagate outside of the component in which it was dispatched.                        |


:::::

:::::tab
::component-specification{component="combobox" model="lwc" namespace="lightning"}

:::::

::::::