# Select

[component-header:sl-select]

Selects allow you to choose one or more items from a dropdown menu.

```html preview
<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-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>
```

?> This component doesn't work with standard forms. Use [`<sl-form>`](/components/form.md) 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>
```

### Scrollable

When the list is long, the dropdown will automatically allows for scrolling.

```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-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-menu-item value="option-7">Option 7</sl-menu-item>
  <sl-menu-item value="option-8">Option 8</sl-menu-item>
  <sl-menu-item value="option-9">Option 9</sl-menu-item>
  <sl-menu-item value="option-10">Option 10</sl-menu-item>
  <sl-menu-item value="option-11">Option 11</sl-menu-item>
  <sl-menu-item value="option-12">Option 12</sl-menu-item>
  <sl-menu-item value="option-13">Option 13</sl-menu-item>
  <sl-menu-item value="option-14">Option 14</sl-menu-item>
  <sl-menu-item value="option-15">Option 15</sl-menu-item>
  <sl-menu-item value="option-16">Option 16</sl-menu-item>
  <sl-menu-item value="option-17">Option 17</sl-menu-item>
  <sl-menu-item value="option-18">Option 18</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>
```

### Searchable

Use the `searchable` attribute allow the user to enter text for searching. Search events will be emitted when text is being edited, but value won't change till the user selects a value from the list. 

```html preview
<div class="searchable-example">
  <sl-select searchable clearable debounce="250" label="Select single" placeholder="Search city"></sl-select>
</div>

<script>
  const container = document.querySelector('.searchable-example');
  const select = container.querySelector('sl-select');
  const texts = ['Austria','Belgium','Bulgaria','Croatia','Cyprus','Czech Republic','Denmark','Estonia','Finland','France','Germany','Greece','Hungary','Ireland','Italy','Latvia','Lithuania','Luxembourg','Malta','Netherlands','Poland','Portugal','Romania','Slovak Republic','Slovenia','Spain','Sweden','United Kingdom']
  select.addEventListener('slSearch', ev => {
    const search = ev.detail.toLowerCase();
    while (select.firstChild) {
        select.removeChild(select.firstChild);
    }

    texts.forEach((t, i) => {
      if(t.toLowerCase().startsWith(search) || search == '') {
        const item = document.createElement('sl-menu-item');
        item.setAttribute('value', 'option-' + i);
        item.innerText = t;
        select.appendChild(item);
      }
    });
  });
</script>
```

### Searchable and multi select

Use the `searchable` attribute allow the user to enter text for searching. Search events will be emitted when text is being edited, but value won't change till the user selects a value from the list. 

```html preview
<div class="searchable-example2">
  <sl-select searchable multiple debounce="250" label="Select multiple" placeholder="Search cities"></sl-select>
</div>

<script>
  const container = document.querySelector('.searchable-example2');
  const select = container.querySelector('sl-select');
  const texts = ['Austria','Belgium','Bulgaria','Croatia','Cyprus','Czech Republic','Denmark','Estonia','Finland','France','Germany','Greece','Hungary','Ireland','Italy','Latvia','Lithuania','Luxembourg','Malta','Netherlands','Poland','Portugal','Romania','Slovak Republic','Slovenia','Spain','Sweden','United Kingdom']
  select.addEventListener('slSearch', ev => {
    const search = ev.detail.toLowerCase();
    while (select.firstChild) {
        select.removeChild(select.firstChild);
    }

    const label = document.createElement('sl-menu-label');
    label.innerText = 'Cities';
    select.appendChild(label);

    texts.forEach((t, i) => {
      if(t.toLowerCase().startsWith(search) || search == '') {
        const item = document.createElement('sl-menu-item');
        item.setAttribute('value', 'option-' + i);
        item.setAttribute('tag-icon', i % 2 == 0 ? 'person-fill' : 'people-fill');
        item.setAttribute('tag-type', i % 2 == 0 ? 'primary' : 'info');
        item.innerText = t;
        select.appendChild(item);
      }
    });
  });

  select.addEventListener('valueChange', ev => {
    console.log('Selected', ev.detail);
  });
</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>
```

### Error Text

Add descriptive error text to a select with the `error-text` attribute. For error texts that contain HTML, use the `error-text` slot instead. When an error text is supplied the help text will be hidden.

```html preview
<div id="error-example">
  <sl-select
    label="Select one"
    help-text="When error is switch off, this help text is shown."
    error-text="The selected value is invalid!"
  >
    <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>

  <sl-switch class="mt-4" checked>Error enabled</sl-switch>
</div>

<script>
  let example = document.getElementById('error-example');
  let input = example.querySelector('sl-select');
  let switchEl = example.querySelector('sl-switch');

  switchEl.addEventListener('checkedChange', evt => {
    console.log(evt);
    const checked = evt.detail;
    input.errorText = checked ? 'The selected value is still invalid' : null;
  });
</script>
```

[component-metadata:sl-select]