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 >
2020-08-08 20:17:22 +00:00
< sl-menu-divider > < / sl-menu-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
?> This component doesn't work with standard forms. Use [`<sl-form>` ](/components/form ) instead.
## 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 >
```
### 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 >
```
### Pill
Use the `pill` prop to give selects rounded edges.
```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 >
```
### Disabled
Use the `disabled` prop to disable a select.
```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 >
```
### Multiple
To allow multiple options to be selected, use the `multiple` attribute. It's a good practice to use `clearable` when this option is enabled. When using this option, `value` will be an array instead of a string.
```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 >
< sl-menu-divider > < / sl-menu-divider >
< 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 >
```
### Grouping Options
Options can be grouped visually using menu labels and menu dividers.
```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 >
< sl-menu-divider > < / sl-menu-divider >
< 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 >
```
### 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 >
< br >
< 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 >
< br >
< 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 >
```
### Selecting Options Programmatically
The `value` prop is bound to the current selection. As the selection changes, so will the value. To programmatically manage the selection, update the `value` property.
```html preview
< div class = "selecting-example" >
< sl-select placeholder = "" >
< 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 >
< br >
< 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', () => {
select.value = button.dataset.option;
});
});
< / script >
```
### 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 >
```
### 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
< sl-select
label="Experience"
help-text="Please tell us your skill level."
>
< sl-menu-item value = "option-1" > Novice< / sl-menu-item >
< sl-menu-item value = "option-2" > Intermediate< / sl-menu-item >
< sl-menu-item value = "option-3" > Advanced< / sl-menu-item >
< / sl-select >
```
[component-metadata:sl-select]