Select

lightning-select enables single and multiple selection on a menu of options 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.

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 that's displayed on the menu.

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.

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.

When you specify multiple, most browsers will 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 is not 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 does not select an option.

Set the default value to an empty string so that an option is not selected by default.

lightning-select supports setCustomValidity() from HTML5's Constraint Validation API. To set an error message, provide a quoted string to display. 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 display a custom error message with setCustomValidity() and reportValidity().

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

lightning-select implements the select blueprint in the Salesforce Lightning Design System (SLDS).

You can 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 use the --slds-c-* prefix and change styling for specific elements or properties of a component. Component-specific styling isn’t recommended, because it’s unsupported for SLDS 2, but existing customizations still work with the original SLDS. If you use component styling hooks, limit the components to SLDS themes until SLDS 2 and the Salesforce Cosmos theme become generally available. See Select: Styling Hooks Overview for documentation on component-specific hooks for this component.

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.