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

Biology

Mathematics

English

Music

Geography

History

Physics

Chemistry

  <sl-select value="2" style="inline-size: 20rem;">
    <sl-select-option value="1">Biology</sl-select-option>
    <sl-select-option value="2">Mathematics</sl-select-option>
    <sl-select-option value="3">English</sl-select-option>
    ...
  </sl-select>

When to use

Use the select component when you need users to select from a predefined list of more than five options. Whether it’s choosing a country, a language, or a course, a select dropdown keeps things organized and user-friendly.

Filtering and sorting options

When designing search interfaces or data tables, consider using select components for filtering or sorting. These components allow users to narrow down search results based on specific criteria. For instance, teachers can filter pupils by grade level or sort the results by relevance or class.

When not to use

Fewer total options

If you’re dealing with less than 5 options, use radio buttons instead of a select component. Radio buttons are more straightforward for a limited set of options.

Avoid using the select component as a menu. Its primary purpose is to display a list of options. If you need to present a list of actions, consider using a menu component specifically designed for that purpose.

Anatomy

Item	Name	Description	Optional
1	Label	Describes the input category	yes
2	Select field	Contains optional placeholder text, which is replaced by the selection	no
3	Hint	Informative message	yes
4	Dropdown panel	Shows a list of options	no

Figma Options

With these options, you can tweak the appearance of the select in Figma. They are available in the Design Panel so you can compose the select to exactly fit the user experience need for the use case you are working on.

Label

Item	Options	Description
Label	`boolean`	To display a label.
Size	`sm` `md` `lg`	The label come in three sizes small, medium (default) and large.
Disabled	`boolean`	To show the disabled state of the label.
Required	`boolean`	Indicates if it is requiered to select an option.
Optional	`boolean`	Indicates if it is optional to select an option.
Info	`boolean`	To show a info icon with tooltip after the label.
Text	`value`	To insert the text of the label.

Select box

Item	Options	Description
Size	`md` `lg`	The select box come in two sizes; medium (default) and large
Variant	`default` `valid` `invalid`	Indicates the variant of the select box
State	`idle` `hover` `active` `disabled`	Indicates the state of the select box
Filled	`empty` `filled` `placeholder`	To indicate the select is filled or shows a placeholder text
Default value	`value`	To insert the default text of the placeholder

Item	Options	Description
Menu open	`boolean`	Displays the dropdown panel
Position	`top` `bottom`	Indicates the position of the dropdown panel
Size	`md` `lg`	Description
Pre selected item	`default` `01` `02` `03` `04` `05` `06` `07` `08` `09` `10` `11` `12` `13` `14` `15`	Indicates the pre selected item from the list

Hint

Item	Options	Description
Hint	`boolean`	To display the hint.
Size	`sm` `md` `lg`	The hint come in three sizes small, medium (default) and large.
State	`default` `disabled` `invalid`	To indicate the state of the hint.
Icon	`boolean`	Displays an icon in front of the hint.
Text	`value`	To insert the text of the hint.

Focus ring

Item	Options	Description
Focus ring	`boolean`	To display the focus state of the select.

English

German

French

Spanish

Chinese

Music

Biology

Chemistry

Physics

Computer Science

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

Select option group API

Select option group component provides properties to define the experience in different use cases, and it is a kind of wrapper for multiple select options, can be used optionally to improve readability.

Properties

Name	Attribute	Type	Default	Description
`heading`	`heading`	`string \| undefined`		The heading for the group.

Slots

Name	Description
`default`	List of `sl-select-option` elements

Select option API

Select option component offers settings for various scenarios, and it is a part of the select component representing each selectable element.

Properties

Name	Attribute	Type	Description
`disabled`	`disabled`	`boolean \| undefined`	Whether the option item is disabled.
`selected`	`selected`	`boolean \| undefined`	Whether the option item is selected.
`value`	`value`	`T \| undefined`	The value for the option item, to be used in forms.

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.
`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.
`listbox`	-	`HTMLElement`		The listbox element.
`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.
`offset`	-	`number`	`6`	The default offset of the listbox to the button.
`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'`	`'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.
`viewportMargin`	-	`number`	`8`	The default margin between the tooltip and the viewport.

Methods

Name	Parameters	Return	Description
`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-select-option` elements

Keyboard interactions

Command	Description
Tab	When focus is outside the select, moves focus to the input container.
Space/Enter	Opens/closes the select panel
Arrow Keys	Once you are in the opened select panel you can navigate to the next option by using the right or down arrow key. You can navigate back to the previous option with left or up. The focus indicator loops, so when you are at the last option and press "down" it will focus on the first option.
Home	When focus is inside the select panel, moves to the first available option item in the select panel
End	When focus is inside the select panel, moves to the last available option item in the select panel

WAI-ARIA

WAI-ARIA Roles, States, and Properties for a select component provide essential information to assistive technologies and screen readers. They convey the select component's role, and additional properties to ensure accessibility and a better user experience for individuals using assistive technology.

Select

Attribute	Value	Description	User suppliedSpecifies whether the attribute is always set in the component (no) or it needs to be provided by the developer (yes)
`role`	`'combobox'`	Identifies the select-button as a combobox.	no
`role`	`'listbox'`	Identifies the list of options as a listbox.	no
`aria-expanded`	boolean	Set to `true` if the listbox (list of options) is visible, `false` if it is hidden.	no
`aria-activedescendant`	string	When a select option in the listbox is visually indicated as having keyboard focus, refers to that option (by `id`) or when it is already selected.	no
`aria-label`	string	Defines a string that labels the action that will be performed when the user interacts with the select. Needs to be added when the select is not wrapped with `sl-form-field` and there is no `sl-label`.	yes
`aria-labelledby`	string	Used to connect with single header/element that describes the select, when there is no label connected to.	yes

Select option group

Attribute	Value	Description	User supplied
`role`	`'group'`	Identifies the `select-option-group` as a group.	no
`aria-label`	string	String that labels the select options group. Same as `heading` string by default. When there is no `heading` please add your own aria-label string.	no/yes
`aria-labelledby`	string	Can be used to connect with single header/element that describes the select group, when there is no label/`heading` connected to.	yes

Select option

Attribute	Value	Description	User supplied
`role`	`'option'`	Identifies the `select-option` as an option, which is a part of the listbox/group.	no
`aria-disabled`	boolean	Announces the select option as disabled with a screen reader when there is a `disabled` attribute set.	no
`aria-selected`	boolean	Set to `true` when a select option is selected.	no

Interactive example