---
schema_version: "1"
id: ef4c253a739e48278f6500aacc656b4344262025e3bb82e30a918bd234df6510
title: Select
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/select/lightning-select.md
canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-select.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: d8d553b0b4a0da23e966975e18fc4ffc267a30eeb6c2726fd8f1b97f8f36aa73
products:
  - Lightning Component Reference
---

# Select

**`lightning-select`**

A menu of options for single or multiple selection.

**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="select" model="lwc" namespace="lightning"}


:::::

:::::tab

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

<!-- prettier-ignore-start -->
```html
<lightning-select
    value={selectVal}
    label="Select a product"
    options={productOptions}
    onchange={handleChange}
></lightning-select>
```
<!-- prettier-ignore-end -->

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.

```javascript
import { LightningElement } from "lwc";

export default class SimpleSelect extends LightningElement {
  selectVal = "";
  productOptions = [
    {
      label: "--None--",
      value: "",
    },
    {
      label: "Sales",
      value: "sales",
    },
    {
      label: "Marketing",
      value: "marketing",
    },
    {
      label: "Service",
      value: "service",
    },
  ];

  handleChange(event) {
    this.selectVal = event.detail.value;
  }
}
```

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.

## Design

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

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Select](https://v1.lightningdesignsystem.com/components/select/)                                                                     | [Select](https://www.lightningdesignsystem.com/components/select/)                                              |
| **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) |

## Select Multiple Options

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.

<!-- prettier-ignore-start -->
```html
<lightning-select
    value={selectVal}
    label="Select a product"
    options={productOptions}
    onchange={handleChange}
    multiple
    size="3"
></lightning-select>
```
<!-- prettier-ignore-end -->

When you specify `multiple`, most browsers show a scrolling list box instead of a single-line dropdown. Alternatively, use the [lightning-dual-listbox](/docs/platform/lightning-component-reference/guide/lightning-dual-listbox.html) component to move options between two lists and reorder the list options.

## Create Options

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

| Property | Type    | Description                                                            |
| -------- | ------- | ---------------------------------------------------------------------- |
| label    | string  | The text to show next to a checkbox.                                   |
| value    | string  | The string that's used to identify which checkbox is selected.         |
| disabled | boolean | If true, the option isn’t selectable and users can’t interact with it. |

## Input Validation

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.

<!-- prettier-ignore-start -->
```html
<lightning-select
    value={selectVal}
    label="Select a product"
    options={productOptions}
    onchange={handleChange}
    required
    message-when-value-missing="Which area can we help you with?"
>
</lightning-select>
```
<!-- prettier-ignore-end -->

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

```js
import { LightningElement } from "lwc";

export default class RequiredSelect extends LightningElement {
  selectVal = "";
  productOptions = [
    {
      label: "--None--",
      value: "",
    },
    {
      label: "Sales",
      value: "sales",
    },
    {
      label: "Marketing",
      value: "marketing",
    },
    {
      label: "Service",
      value: "service",
    },
  ];

  handleChange(event) {
    this.selectVal = event.detail.value;
  }
}
```

## Custom Validity Error Messages

`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](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()`.

<!-- prettier-ignore-start -->
```html
<lightning-select
    name="myselect"
    value={selectVal}
    label="Select a product"
    options={productOptions}
    onchange={handleChange}
    required
></lightning-select>

<lightning-button label="Register" onclick={register}></lightning-button>
```
<!-- prettier-ignore-end -->

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.

```javascript
import { LightningElement } from "lwc";

export default class CustomSelectError extends LightningElement {
  selectVal = "";
  productOptions = [
    {
      label: "--None--",
      value: "",
    },
    {
      label: "Sales",
      value: "sales",
    },
    {
      label: "Marketing",
      value: "marketing",
    },
    {
      label: "Service",
      value: "service",
    },
  ];

  handleChange(event) {
    this.selectVal = event.detail.value;
  }

  register(event) {
    const selectCmp = this.template.querySelector("lightning-select");
    if (this.selectVal === "") {
      selectCmp.setCustomValidity("You have not selected an option");
    } else {
      selectCmp.setCustomValidity("");
    }
    // Display the error without user interaction
    selectCmp.reportValidity();
  }
}
```

## Component Styling

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

### Variants

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.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute. For example, you can add padding on the top of the component using the `slds-p-top_medium` SLDS class.

### Styling Hooks

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](https://v1.lightningdesignsystem.com/components/overview/) for available component styling hooks.

For more information, see [Style Components Using Lightning Design System Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties) in the Lightning Web Components Developer Guide.


## Usage Considerations

`lightning-select` uses `delegatesFocus` to manage focus. `tabindex` is not supported. See [Handle Focus](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-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`](/docs/platform/lightning-component-reference/guide/aura-select.html) 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`](/docs/platform/lightning-component-reference/guide/lightning-combobox.html) if your dropdown menu doesn't need mobile support or multiple selection.

## Accessibility

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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select#Usage_notes) 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.

## Custom Events

**`change`**

The event fired when an option is selected.

The `change` event returns the following parameter.

| Parameter | Type   | Description                       |
| --------- | ------ | --------------------------------- |
| value     | 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.                                |


:::::

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

:::::

::::::