2020-07-15 21:30:37 +00:00
# Select
[component-header:sl-select]
Selects allow you to choose one or more items from a dropdown menu.
```html preview
2020-08-25 20:25:25 +00:00
< sl-select >
2020-07-15 21:30:37 +00:00
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
2021-09-29 12:03:03 +00:00
< sl-divider > < / sl-divider >
2020-07-15 21:30:37 +00:00
< sl-menu-item value = "option-4" > Option 4< / sl-menu-item >
< sl-menu-item value = "option-5" > Option 5< / sl-menu-item >
< sl-menu-item value = "option-6" > Option 6< / sl-menu-item >
< / sl-select >
```
2021-06-04 12:19:28 +00:00
2021-11-04 22:12:47 +00:00
```jsx react
import { SlDivider, SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
< SlSelect >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< SlDivider / >
< SlMenuItem value = "option-4" > Option 4< / SlMenuItem >
< SlMenuItem value = "option-5" > Option 5< / SlMenuItem >
< SlMenuItem value = "option-6" > Option 6< / SlMenuItem >
< / SlSelect >
);
```
2022-01-11 14:18:20 +00:00
?> This component works with standard `<form>` elements. Please refer to the section on [form controls ](/getting-started/form-controls ) to learn more about form submission and client-side validation.
2021-06-04 12:19:28 +00:00
## Examples
### Placeholders
Use the `placeholder` attribute to add a placeholder.
```html preview
< sl-select placeholder = "Select one" >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
< / sl-select >
```
2021-11-04 22:12:47 +00:00
```jsx react
import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
< SlSelect placeholder = "Select one" >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< / SlSelect >
);
```
2021-06-04 12:19:28 +00:00
### Clearable
Use the `clearable` attribute to make the control clearable.
```html preview
< sl-select placeholder = "Clearable" clearable >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
< / sl-select >
```
2021-11-04 22:12:47 +00:00
```jsx react
import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
< SlSelect placeholder = "Clearable" clearable >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< / SlSelect >
);
```
2021-09-25 02:28:14 +00:00
### Filled Selects
Add the `filled` attribute to draw a filled select.
```html preview
< sl-select filled >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
< / sl-select >
```
2021-11-04 22:12:47 +00:00
```jsx react
import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
< SlSelect filled >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< / SlSelect >
);
```
2021-06-04 12:19:28 +00:00
### Pill
2021-07-08 21:41:10 +00:00
Use the `pill` attribute to give selects rounded edges.
2021-06-04 12:19:28 +00:00
```html preview
< sl-select pill >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
< / sl-select >
```
2021-11-04 22:12:47 +00:00
```jsx react
import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
< SlSelect pill >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< / SlSelect >
);
```
2021-06-04 12:19:28 +00:00
### Disabled
2021-07-08 21:41:10 +00:00
Use the `disabled` attribute to disable a select.
2021-06-04 12:19:28 +00:00
```html preview
< sl-select placeholder = "Disabled" disabled >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
< / sl-select >
```
2021-11-04 22:12:47 +00:00
```jsx react
import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
< SlSelect placeholder = "Disabled" disabled >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< / SlSelect >
);
```
2022-03-01 14:32:01 +00:00
### Setting the Selection
Use the `value` attribute to set the current selection. When users interact with the control, its `value` will update to reflect the newly selected menu item's value. Note that the value must be an array when using the [`multiple` ](#multiple ) option.
```html preview
< sl-select value = "option-2" >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
< / sl-select >
```
```jsx react
import { SlDivider, SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
< SlSelect value = "option-2" >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< / SlSelect >
);
```
### Setting the Selection Imperatively
To programmatically set the selection, update the `value` property as shown below. Note that the value must be an array when using the [`multiple` ](#multiple ) option.
```html preview
< div class = "selecting-example" >
< sl-select >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
< / sl-select >
2022-03-02 15:10:41 +00:00
< br / >
2022-03-01 14:32:01 +00:00
< sl-button data-option = "option-1" > Set 1< / sl-button >
< sl-button data-option = "option-2" > Set 2< / sl-button >
< sl-button data-option = "option-3" > Set 3< / sl-button >
< / div >
< script >
const container = document.querySelector('.selecting-example');
const select = container.querySelector('sl-select');
[...container.querySelectorAll('sl-button')].map(button => {
button.addEventListener('click', () => {
2022-03-02 15:10:41 +00:00
select.value = button.dataset.option;
2022-03-01 14:32:01 +00:00
});
});
< / script >
```
```jsx react
import { useState } from 'react';
import { SlButton, SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => {
const [value, setValue] = useState('option-1');
return (
< >
< SlSelect value = {value} onSlChange = {event = > setValue(event.target.value)}>
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< / SlSelect >
< br / >
< SlButton onClick = {() = > setValue('option-1')}>Set 1< / SlButton >
< SlButton onClick = {() = > setValue('option-2')}>Set 2< / SlButton >
< SlButton onClick = {() = > setValue('option-3')}>Set 3< / SlButton >
< />
);
};
```
2021-06-04 12:19:28 +00:00
### Multiple
2022-03-01 14:32:01 +00:00
To allow multiple options to be selected, use the `multiple` attribute. With this option, `value` will be an array of strings instead of a string. It's a good practice to use `clearable` when this option is enabled.
2021-06-04 12:19:28 +00:00
```html preview
< sl-select placeholder = "Select a few" multiple clearable >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
2021-09-29 12:03:03 +00:00
< sl-divider > < / sl-divider >
2021-06-04 12:19:28 +00:00
< sl-menu-item value = "option-4" > Option 4< / sl-menu-item >
< sl-menu-item value = "option-5" > Option 5< / sl-menu-item >
< sl-menu-item value = "option-6" > Option 6< / sl-menu-item >
< / sl-select >
```
2021-11-04 22:12:47 +00:00
```jsx react
import { SlDivider, SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
< SlSelect placeholder = "Select a few" multiple clearable >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< SlDivider / >
< SlMenuItem value = "option-4" > Option 4< / SlMenuItem >
< SlMenuItem value = "option-5" > Option 5< / SlMenuItem >
< SlMenuItem value = "option-6" > Option 6< / SlMenuItem >
< / SlSelect >
);
```
2022-03-01 14:32:01 +00:00
?> When using the `multiple` option, the value will be an array instead of a string. You may need to [set the selection imperatively ](#setting-the-selection-imperatively ) unless you're using a framework that supports binding properties declaratively.
2022-01-18 13:50:14 +00:00
2021-06-04 12:19:28 +00:00
### Grouping Options
2021-09-29 12:03:03 +00:00
Options can be grouped visually using menu labels and dividers.
2021-06-04 12:19:28 +00:00
```html preview
< sl-select placeholder = "Select one" >
< sl-menu-label > Group 1< / sl-menu-label >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
2021-09-29 12:03:03 +00:00
< sl-divider > < / sl-divider >
2021-06-04 12:19:28 +00:00
< sl-menu-label > Group 2< / sl-menu-label >
< sl-menu-item value = "option-4" > Option 4< / sl-menu-item >
< sl-menu-item value = "option-5" > Option 5< / sl-menu-item >
< sl-menu-item value = "option-6" > Option 6< / sl-menu-item >
< / sl-select >
```
2021-11-04 22:12:47 +00:00
```jsx react
import { SlDivider, SlMenuItem, SlMenuLabel, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
< SlSelect placeholder = "Select one" >
< SlMenuLabel > Group 1< / SlMenuLabel >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< SlDivider > < / SlDivider >
< SlMenuLabel > Group 2< / SlMenuLabel >
< SlMenuItem value = "option-4" > Option 4< / SlMenuItem >
< SlMenuItem value = "option-5" > Option 5< / SlMenuItem >
< SlMenuItem value = "option-6" > Option 6< / SlMenuItem >
< / SlSelect >
);
```
2021-06-04 12:19:28 +00:00
### Sizes
Use the `size` attribute to change a select's size.
```html preview
< sl-select placeholder = "Small" size = "small" multiple >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
< / sl-select >
2022-03-02 15:10:41 +00:00
< br / >
2021-06-04 12:19:28 +00:00
< sl-select placeholder = "Medium" size = "medium" multiple >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
< / sl-select >
2022-03-02 15:10:41 +00:00
< br / >
2021-06-04 12:19:28 +00:00
< sl-select placeholder = "Large" size = "large" multiple >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
< / sl-select >
```
2021-11-04 22:12:47 +00:00
```jsx react
import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
< >
< SlSelect placeholder = "Small" size = "small" multiple >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< / SlSelect >
< br / >
< SlSelect placeholder = "Medium" size = "medium" multiple >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< / SlSelect >
< br / >
< SlSelect placeholder = "Large" size = "large" multiple >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< / SlSelect >
< />
);
```
2021-06-04 12:19:28 +00:00
### Labels
Use the `label` attribute to give the select an accessible label. For labels that contain HTML, use the `label` slot instead.
```html preview
< sl-select label = "Select one" >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
< / sl-select >
```
2021-11-04 22:12:47 +00:00
```jsx react
import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
< SlSelect label = "Select one" >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< / SlSelect >
);
```
2021-06-04 12:19:28 +00:00
### Help Text
Add descriptive help text to a select with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
```html preview
2022-03-02 15:10:41 +00:00
< sl-select label = "Experience" help-text = "Please tell us your skill level." >
2021-11-04 22:12:47 +00:00
< sl-menu-item value = "1" > Novice< / sl-menu-item >
< sl-menu-item value = "2" > Intermediate< / sl-menu-item >
< sl-menu-item value = "3" > Advanced< / sl-menu-item >
2021-06-04 12:19:28 +00:00
< / sl-select >
```
2021-11-04 22:12:47 +00:00
```jsx react
import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
2022-03-02 15:10:41 +00:00
< SlSelect label = "Experience" help-text = "Please tell us your skill level." >
2021-11-04 22:12:47 +00:00
< SlMenuItem value = "1" > Novice< / SlMenuItem >
< SlMenuItem value = "2" > Intermediate< / SlMenuItem >
< SlMenuItem value = "3" > Advanced< / SlMenuItem >
< / SlSelect >
);
```
2022-02-21 14:04:21 +00:00
### Placement
2022-02-21 14:13:33 +00:00
The preferred placement of the select's menu can be set with the `placement` attribute. Note that the actual position may vary to ensure the panel remains in the viewport. Valid placements are `top` and `bottom` .
2022-02-21 14:04:21 +00:00
```html preview
< sl-select placement = "top" >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
< / sl-select >
```
```jsx react
2022-03-02 15:10:41 +00:00
import {
2022-02-21 14:04:21 +00:00
SlMenuItem,
SlSelect
} from '@shoelace-style/shoelace/dist/react';
const App = () => (
< SlSelect placement = "top" >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
2022-03-02 15:10:41 +00:00
< / SlDropdown >
2022-02-21 14:04:21 +00:00
);
```
2021-08-16 21:05:28 +00:00
### Prefix & Suffix Icons
2021-08-16 20:30:55 +00:00
2021-08-16 21:05:28 +00:00
Use the `prefix` and `suffix` slots to add icons.
2021-08-16 20:30:55 +00:00
```html preview
2021-08-16 21:05:28 +00:00
< sl-select placeholder = "Small" size = "small" >
< sl-icon name = "house" slot = "prefix" > < / sl-icon >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
< sl-icon name = "chat" slot = "suffix" > < / sl-icon >
2021-08-16 20:30:55 +00:00
< / sl-select >
2022-03-02 15:10:41 +00:00
< br / >
2021-08-16 21:05:28 +00:00
< sl-select placeholder = "Medium" size = "medium" >
< sl-icon name = "house" slot = "prefix" > < / sl-icon >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
< sl-icon name = "chat" slot = "suffix" > < / sl-icon >
< / sl-select >
2022-03-02 15:10:41 +00:00
< br / >
2021-08-16 21:05:28 +00:00
< sl-select placeholder = "Large" size = "large" >
< sl-icon name = "house" slot = "prefix" > < / sl-icon >
< sl-menu-item value = "option-1" > Option 1< / sl-menu-item >
< sl-menu-item value = "option-2" > Option 2< / sl-menu-item >
< sl-menu-item value = "option-3" > Option 3< / sl-menu-item >
< sl-icon name = "chat" slot = "suffix" > < / sl-icon >
2021-08-16 20:30:55 +00:00
< / sl-select >
```
2021-11-04 22:12:47 +00:00
```jsx react
import { SlIcon, SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
const App = () => (
< >
< SlSelect placeholder = "Small" size = "small" >
< SlIcon name = "house" slot = "prefix" > < / SlIcon >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< SlIcon name = "chat" slot = "suffix" > < / SlIcon >
< / SlSelect >
< br / >
< SlSelect placeholder = "Medium" size = "medium" >
< SlIcon name = "house" slot = "prefix" > < / SlIcon >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< SlIcon name = "chat" slot = "suffix" > < / SlIcon >
< / SlSelect >
< br / >
< SlSelect placeholder = "Large" size = "large" >
< SlIcon name = "house" slot = "prefix" > < / SlIcon >
< SlMenuItem value = "option-1" > Option 1< / SlMenuItem >
< SlMenuItem value = "option-2" > Option 2< / SlMenuItem >
< SlMenuItem value = "option-3" > Option 3< / SlMenuItem >
< SlIcon name = "chat" slot = "suffix" > < / SlIcon >
< / SlSelect >
< />
);
```
2021-06-04 12:19:28 +00:00
[component-metadata:sl-select]