Selects, one file.

API reference

The complete surface of select.js v1.0.0 — constructor, options, methods, statics, events, declarative attributes, theming and accessibility. Everything below is taken from the source; where the README summarises, the source is authoritative.

Constructor & usage

new Select(target, options?)   // → Select instance
Select.create(target, options?) // identical alias

target is a CSS selector string or a DOM element. If no element matches, the constructor throws. Creating a second instance on the same element destroys the previous one first. Without a DOM (SSR), the constructor returns an inert instance whose public methods all no-op.

There are two modes, decided by the target's tag:

1. Native <select> mode — progressive enhancement

Options, selection, multiple and disabled are read from the element. It stays in the DOM (hidden, aria-hidden, marked data-vsel-bound) and every change is mirrored back, so forms, validation and existing change listeners keep working. A leading empty-value option is treated as the placeholder: its label is adopted (when you didn't pass your own placeholder) and clearing re-selects it.

<select id="fruit" name="fruit">
  <option value="">Choose a fruit…</option>
  <option value="apple">Apple</option>
</select>
<script>new Select('#fruit', { searchable: true })</script>

2. Container mode — built from an array

Any non-<select> element becomes the host; options come from the options array. Pass name and the widget maintains a hidden <input type="hidden"> (single) or hidden <select multiple> (multiple) inside itself, so it submits like any form field.

<div id="size"></div>
<script>
new Select('#size', {
  name: 'size',
  options: ['S', 'M', 'L', { value: 'xl', label: 'XL', disabled: true }],
  value: 'M',
  onChange: function (v) { console.log(v) }
})
</script>

Options

Every option, with the exact default from the Select.defaults object in the source. Any default can be changed globally, once: Select.defaults.placeholder = '…'.

Option item shape

Entries of the options array (and of data-vsel-options JSON) are normalized to this shape; a bare string 'a' becomes { value: 'a', label: 'a' }. Values are always coerced to strings.

Methods

All methods return the instance (chainable) except getValue(). On an inert SSR instance every method is a safe no-op.

Instance properties

Also readable on the instance: sel.el (target element), sel.native (the native <select>, or null in container mode), sel.isOpen, and sel.opts (resolved options).

Statics & helpers

Events & callbacks

Each lifecycle moment is exposed twice: as a constructor callback and as a bubbling CustomEvent dispatched on the target element (the native <select> or the container), so you can also listen with delegation.

In native mode, every non-silent change also dispatches a bubbling native change event on the hidden <select>, so pre-existing form listeners keep working untouched.

document.getElementById('city').addEventListener('select:change', function (e) {
  console.log(e.detail.value, e.detail.select)
})

Declarative init (data attributes)

Every [data-vsel] element is auto-initialized on DOMContentLoaded (or immediately if the script loads later). Call Select.autoInit(root) yourself for content added afterwards — already-bound elements are skipped. For boolean attributes, presence means true; the values "false" and "0" mean false.

<select data-vsel data-vsel-searchable data-vsel-clearable>…</select>

<div data-vsel data-vsel-name="size" data-vsel-placeholder="Pick a size…"
     data-vsel-options='["S","M","L","XL"]'></div>

Theming

Light/dark is automatic (see the theme option). All colors are CSS custom properties defined on .vsel — override them from your own stylesheet; the injected sheet is inserted before the page's first stylesheet precisely so your overrides win. The dark theme redefines them on .vsel[data-theme=dark].

.vsel { --vsel-accent: #b45309; --vsel-radius: 8px; }

CSS isolation: the control and panel render as class="vsel vc1" and all structural rules ship salted (.vsel.vc1 .vsel-option { … }), so host-page design systems can't accidentally override the widget — while the --vsel-* variable definitions stay unsalted so the overrides above keep working. Change the token with Select.salt = 'acme' or disable with Select.salt = false, before the first instance.

Headless: set styles: false per instance (or Select.defaults.styles = false globally, or data-vsel-styles="false") and no CSS is injected — you keep the full behavior (selection, search, keyboard, ARIA, form sync) and style the .vsel-* markup contract yourself. The stock stylesheet is available as a starting point via Select.css (string) or dist/select.css (file). With the VC core loaded, VC.config({ accent: '#b45309' }) themes selects and every other family component in one call.

Accessibility

Keyboard

ARIA & behavior notes

• WAI-ARIA combobox pattern: the control is role="combobox" with aria-haspopup="listbox", aria-expanded, aria-controls and aria-activedescendant; the panel is a role="listbox" of role="option" items with aria-selected / aria-disabled; groups are role="group" with aria-label; the list gets aria-multiselectable="true" in multiple mode.
• Focus stays on the control (or the search field, itself a role="combobox" with aria-autocomplete="list") while ↑/↓ move the active option — screen readers follow via aria-activedescendant.
• The accessible name is borrowed from a <label for="…"> pointing at the native select; in container mode set aria-label / aria-labelledby on the container or use the labels option.
• Tag remove buttons are tabindex="-1" so the widget is one tab stop; Backspace removes tags from the keyboard.
• Option labels are rendered with textContent; html: true per option is an explicit opt-in for trusted markup.
• :focus-visible outlines only; prefers-reduced-motion disables all transitions and animations.