# Select

> Choose one option, or several, from a styled menu.

## Introduction

Select turns a native `<select>` into an exposed menu — a text field plus a menu. Wrap it in `.field` and give the label a matching `for`. Add `outlined` (or `border`) on that field for the outlined variant. `AutoInit()` starts every `select` except those marked `no-autoinit`. Add `browser-default` to keep the native control.

Filled enhanced selects reserve space for their label, including translated labels that wrap or grow with text size. The outlined and native variants retain their existing layout.

Choose your option Option 1 Option 2 Option 3 Expressive Select

Add `multiple` to select several options. Chosen values appear as a comma-separated list.

Choose your option Option 1 Option 2 Option 3 Multiple Select

Native `<optgroup>` elements become group headings in the menu.

Option 1 Option 2 Option 3 Option 4 Optgroups

Put an image URL in `data-icon` on an option. Classes on that option are copied to the image; `left` floats it left. Images float right by default. There is no `icons` class on the `<select>`. Relative, HTTP(S), blob, and image data URLs are supported (AVIF, BMP, GIF, JPEG, PNG, SVG, WebP, or ICO). Invalid URLs and other schemes are ignored; the option remains selectable.

Choose your option example 1 example 2 example 3 Images in select

Choose your option example 1 example 2 example 3 Images in select

Add `browser-default` to skip the menu and keep the native select.

Browser Select Choose your option Option 1 Option 2 Option 3

```
<div class="field">
  <select id="form-select-1">
    <option value="" disabled selected>Choose your option</option>
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
    <option value="3">Option 3</option>
  </select>
  <label for="form-select-1">Expressive Select</label>
</div>

<div class="field">
  <select id="form-select-2" multiple>
    <option value="" disabled selected>Choose your option</option>
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
    <option value="3">Option 3</option>
  </select>
  <label for="form-select-2">Multiple Select</label>
</div>

<div class="field">
  <select id="form-select-3">
    <optgroup label="team 1">
      <option value="1">Option 1</option>
      <option value="2">Option 2</option>
    </optgroup>
    <optgroup label="team 2">
      <option value="3">Option 3</option>
      <option value="4">Option 4</option>
    </optgroup>
  </select>
  <label for="form-select-3">Optgroups</label>
</div>

<div class="field">
  <select id="form-select-4">
    <option value="" disabled selected>Choose your option</option>
    <option value="1" data-icon="photo.jpg">example 1</option>
    <option value="2" data-icon="photo.jpg" class="left">example 2</option>
  </select>
  <label for="form-select-4">Images in select</label>
</div>

<label for="form-select-6">Browser Select</label>
<select id="form-select-6" class="browser-default">
  <option value="" disabled selected>Choose your option</option>
  <option value="1">Option 1</option>
</select>
```

## Initialization

The IIFE bundle exposes `Expressive.FormSelect`. Call `init` yourself when you need options other than the defaults, after adding a select dynamically, or after changing an existing select’s options. Otherwise `Expressive.AutoInit()` starts every `select`.

```
document.addEventListener('DOMContentLoaded', function() {
  const elems = document.querySelectorAll('select');
  const instances = Expressive.FormSelect.init(elems, {
    // specify options here
  });
});
```

Per-instance options can also be passed through AutoInit:

```
Expressive.AutoInit(document.body, {
  FormSelect: { menuOptions: { constrainWidth: false } }
});
```

## Options

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | String | `''` | Space-separated classes added to the generated `.select-wrapper`. |
| `menuOptions` | Object | `{}` | Options passed to `Menu`. See [Menu](/menu.html.md#options). `coverTrigger` is forced to `false` and `closeOnClick` is forced to `false`. |

There is no `selected` option. Mark options with the HTML `selected` attribute instead.

## Methods

> All methods are called on the plugin instance. You can get the instance like this:

```
const instance = Expressive.FormSelect.getInstance(elem);
```

### .getSelectedValues();

Selected values as an array of strings.

```
instance.getSelectedValues();
```

### .refresh();

Re-read the native `<select>`. Call this after changing `select.value` or after adding or removing `<option>`s. The menu is rebuilt; the field and Menu instance stay put.

```
instance.refresh();
```

### .destroy();

Destroy the plugin instance, remove the menu, and restore the native select.

```
instance.destroy();
```

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `el` | Element | The native `<select>` the plugin was initialized with. |
| `options` | Object | The options the instance was initialized with. |
| `isMultiple` | Boolean | Whether this is a multiple select. |
| `wrapper` | Element | The generated `.select-wrapper`. |
| `menuEl` | Element | The generated `<menu>`. |
| `labelEl` | Element | The associated label, or `null` if none was found. |
| `input` | Element | The text input that shows the current selection. |
| `menu` | Menu | The Menu instance for this select. |

## Disabled Styles

`disabled` on the `<select>` disables the whole control. `disabled` on an `<option>` makes that item unselectable.

Choose your option Option 1 Option 2 Option 3 Disabled Select

Browser Disabled Choose your option Option 1 Option 2 Option 3

```
<div class="field">
  <select id="form-select-7" disabled>
    <option value="" disabled selected>Choose your option</option>
    <option value="1">Option 1</option>
  </select>
  <label for="form-select-7">Disabled Select</label>
</div>

<label for="form-select-8">Browser Disabled</label>
<select id="form-select-8" class="browser-default" disabled>
  <option value="" disabled selected>Choose your option</option>
  <option value="1">Option 1</option>
</select>
```