Select

A select component allows users to choose from a predefined list of options. You can click or tap on it, and it reveals a list of options and you can select the option that aligns with your preference.

Usage

Code

Accessibility

English

German

French

Spanish

Chinese

Music

Biology

Chemistry

Physics

Computer Science

<sl-select>
  <sl-option-group label="Languages">
    <sl-option>English</sl-option>
    <sl-option>German</sl-option>
    ...
  </sl-option-group>
  <sl-option>Music</sl-option>
  <sl-option-group label="Science">
    <sl-option>Biology</sl-option>
    <sl-option>Chemistry</sl-option>
    ...
  </sl-option-group>
</sl-select>

API

Select component has a range of properties, attributes etc. to define the experience in different use cases, and it can be used as the replacement of the HTML native select element.

Properties

Name	Attribute	Type	Default	Description
`button`	-	`SelectButton`		The button in the light DOM.
`clearable`	`clearable`	`boolean \| undefined`		Will display a clear button when an option is selected.
`customValidity`	`custom-validity`	`string \| undefined`		The error message to display when the control is invalid.
`dirty`	-	`boolean`	`false`	A control is dirty if the user has changed the value in the UI.
`disabled`	`disabled`	`boolean \| undefined`		Whether the select is disabled; when set no interaction is possible.
`form`	-	`HTMLFormElement \| null`		The form associated with the control.
`formValue`	-	`unknown`		The value used when submitting the form.
`labels`	-	`NodeListOf<HTMLLabelElement>` \| null		The labels associated with the control.
`name`	`name`	`string \| undefined`		The name of the form control.
`nativeFormValue`	-	`FormValue`		Returns the form value as used in a native `<form>`. This is always a string, File, FormData or null.
`placeholder`	`placeholder`	`string \| undefined`		The placeholder text to show when no option is chosen.
`required`	`required`	`boolean \| undefined`		Whether the select is a required field.
`rootMarginTop`	`hide-margin-top`	`number`	`0`	The number of pixels from the top of the viewport the select should be hidden on scroll. Use this when there is a sticky header you don't want dropdowns to fall on top of.
`showValid`	`show-valid`	`boolean`	`false`	When set will cause the control to show it is valid after reportValidity is called.
`showValidity`	`show-validity`	`'valid' \| 'invalid' \| undefined`		Whether to show the validity state.
`size`	`size`	`'md' \| 'lg' \| undefined`	`md`	The size of the select.
`touched`	-	`boolean`	`false`	A control is marked touched once the user has triggered a blur event on it.
`valid`	-	`boolean`		Returns whether the form control is valid or not.
`validationMessage`	-	`string`		String representing a localized (by the browser) message that describes the validation constraints that the control does not satisfy (if any). The string is empty if the control is not a candidate for constraint validation, or it satisfies its constraints. For true localization, see `getLocalizedValidationMessage()` instead.
`validity`	-	`ValidityState`		Returns the validity state the control is in.
`validityState`	-	`'valid' \| 'invalid' \| 'pending'`		Returns the current validity state.
`value`	`value`	`unknown \| undefined`		The value for the select, to be used in forms.

Methods

Name	Parameters	Return	Description
`focus`	`options?: FocusOptions`	`void`
`reportValidity`		`boolean`	Returns whether the control is valid. If the control is invalid, calling this will also cause an `invalid` event to be dispatched. After calling this, the control will also report the validity to the user.
`getLocalizedValidationMessage`		`string`	This returns a localized validation message. It does not support all `ValidityState` properties, since some require more context than we have here. If you need to support more, you can override this method in your own form control.
`setCustomValidity`	`message: string \| Promise<string>`	`void`	Sets a custom validation message for the form control. If the message is not an empty string, that will make the control invalid. By setting it to an empty string again, you can make the control valid again.

Events

Name	Event type	Description
`sl-blur`	`SlBlurEvent`	Emits when the focus leaves the component.
`sl-change`	`SlChangeEvent<T \| undefined>`	Emits when the value changes.
`sl-focus`	`SlFocusEvent`	Emits when the component gains focus.
`sl-form-control`	`SlFormControlEvent`	Emits when the form control is added to the DOM.
`sl-update-state`	`SlUpdateStateEvent`	Emits when the UI state (dirty, pristine, touched or untouched) of the form control changes.
`sl-update-validity`	`SlUpdateValidityEvent`	Emits when the validity of the form control changes.
`sl-validate`	`SlValidateEvent`	Emits when the form control can be validated.

Slots

Name	Description
`default`	Place for `sl-option` and `sl-option-group` elements

CSS Parts

Name	Description
`listbox`	Set `--sl-popover-max-block-size` and/or `--sl-popover-min-block-size` to control the minimum and maximum height of the dropdown (within the limits of the available screen real estate)

Interactive example