Select

lightning-select enables single and multiple selections on a menu of options by using the HTML select element and option elements. To specify whether multiple options can be selected, use the multiple attribute. The size attribute can be used to specify how many options are visible at once. lightning-select also accepts most general form input attributes such as required and disabled.

Here’s an example on how to create a menu of options. Pass a default value to the value attribute to make it selected by default when the component loads.

1<lightning-select
2    value={selectVal}
3    label="Select a product"
4    options={productOptions}
5    onchange={handleChange}
6></lightning-select>

In your JavaScript, define an array of options. Each option has a value and label property. The value is returned when you select an option. The label value is the text to show on the menu.

1import { LightningElement } from "lwc";
2
3export default class SimpleSelect extends LightningElement {
4  selectVal = "";
5  productOptions = [
6    {
7      label: "--None--",
8      value: "",
9    },
10    {
11      label: "Sales",
12      value: "sales",
13    },
14    {
15      label: "Marketing",
16      value: "marketing",
17    },
18    {
19      label: "Service",
20      value: "service",
21    },
22  ];
23
24  handleChange(event) {
25    this.selectVal = event.detail.value;
26  }
27}

Selecting an option triggers the change event, which calls the onchange handler. To check which option is selected, use event.detail.value. If your value attribute is null, event.detail.value returns an empty string.

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

To enable multiple selection of options, use the multiple attribute. You can use the size attribute to specify the number of options to display by default.

1<lightning-select
2    value={selectVal}
3    label="Select a product"
4    options={productOptions}
5    onchange={handleChange}
6    multiple
7    size="3"
8></lightning-select>

When you specify multiple, most browsers show a scrolling list box instead of a single-line dropdown. Alternatively, use the lightning-dual-listbox component to move options between two lists and reorder the list options.

To create menu options, pass in the following properties to the options attribute.

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

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.

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

Here’s an example that displays a custom field-level message when a user interacts with the component but doesn’t select an option.

1<lightning-select
2    value={selectVal}
3    label="Select a product"
4    options={productOptions}
5    onchange={handleChange}
6    required
7    message-when-value-missing="Which area can we help you with?"
8>
9</lightning-select>

Set the default value to an empty string so that an option isn’t selected by default.

1import { LightningElement } from "lwc";
2
3export default class RequiredSelect extends LightningElement {
4  selectVal = "";
5  productOptions = [
6    {
7      label: "--None--",
8      value: "",
9    },
10    {
11      label: "Sales",
12      value: "sales",
13    },
14    {
15      label: "Marketing",
16      value: "marketing",
17    },
18    {
19      label: "Service",
20      value: "service",
21    },
22  ];
23
24  handleChange(event) {
25    this.selectVal = event.detail.value;
26  }
27}

lightning-select supports setCustomValidity() from HTML5’s Constraint Validation API. To set an error message, specify a quoted string. To reset the error message, set the message to an empty string (""). See details at https://www.w3.org/TR/html52/sec-forms.html#dom-htmlinputelement-setcustomvalidity.

This example shows how to specify a custom error message with setCustomValidity() and reportValidity().

1<lightning-select
2    name="myselect"
3    value={selectVal}
4    label="Select a product"
5    options={productOptions}
6    onchange={handleChange}
7    required
8></lightning-select>
9
10<lightning-button label="Register" onclick={register}></lightning-button>

When you click the Register button, the register() function shows a custom error message if no option is selected, or clears the error message if an option has been selected.

1import { LightningElement } from "lwc";
2
3export default class CustomSelectError extends LightningElement {
4  selectVal = "";
5  productOptions = [
6    {
7      label: "--None--",
8      value: "",
9    },
10    {
11      label: "Sales",
12      value: "sales",
13    },
14    {
15      label: "Marketing",
16      value: "marketing",
17    },
18    {
19      label: "Service",
20      value: "service",
21    },
22  ];
23
24  handleChange(event) {
25    this.selectVal = event.detail.value;
26  }
27
28  register(event) {
29    const selectCmp = this.template.querySelector("lightning-select");
30    if (this.selectVal === "") {
31      selectCmp.setCustomValidity("You have not selected an option");
32    } else {
33      selectCmp.setCustomValidity("");
34    }
35    // Display the error without user interaction
36    selectCmp.reportValidity();
37  }
38}

Use a combination of the variant and class attributes to customize the dropdown menu.

Use the variant attribute with one of these values to position the labels differently relative to the dropdown menu.

• standard is the default, which displays the label above the dropdown menu.
• label-hidden hides the label but make it available to assistive technology. If you provide a value for field-level-help, the tooltip icon is still displayed.
• label-inline aligns the label and dropdown menu horizontally.
• label-stacked places the label above the dropdown menu.

To apply additional styling, use the SLDS utility classes with the class attribute. For example, you can add padding on the top of the component using the slds-p-top_medium SLDS class.

Component styling hooks provide CSS custom properties that use the --slds-c-* prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the SLDS 1 component blueprints for available component styling hooks.

For more information, see Style Components Using Lightning Design System Styling Hooks in the Lightning Web Components Developer Guide.

lightning-select uses delegatesFocus to manage focus. tabindex is not supported. See Handle Focus for more information.

Option groupings and disabled options are currently not supported.

lightning-select has usage differences from its Aura counterpart (lightning:select). lightning:select does not support multiple selection, and it takes in menu options as subcomponents in lightning:select. lightning:select doesn’t currently support multiple selection.

Alternatively, consider using lightning-combobox if your dropdown menu doesn’t need mobile support or multiple selection.

Provide a text label for accessibility using the label attribute, which creates an HTML <label> element for your input component. To hide the label from view and make it available to assistive technology, use the label-hidden variant.

When the component is in an invalid state, an error message is displayed under the <select> element. The message is contained in a <div> element that specifies role="status". To enable screen readers to announce the error message, the id value is associated with the aria-describedby attribute on the <select> element. The label is also used as assistive text for screen readers.

On desktop, select multiple options by clicking an option and dragging up or down the list. Alternatively, hold the Ctrl, Command, or Shift keys (depending on your operating system) and then click multiple options to select or deselect them. For more information, see Selecting multiple options in the MDN web docs.

Validation errors are displayed below the dropdown menu using role="status". When an error is displayed, the select element updates the aria-describedby value to the ID of the element that contains the error message. The label value is also used as assistive text for screen readers.

change

The event fired when an option is selected.

The change event returns the following parameter.

The event properties are as follows.