Sliders, one file.

API reference

Constructor & usage

new Slider(target, options?) — target is a CSS selector string or an element. A non-matching target throws; constructing on an element that already holds an instance destroys the old instance first. Without a DOM (SSR), the constructor returns an inert no-op instance.

Build mode — pass an empty container and the slider is built inside it. With name set, hidden input(s) are created so plain form posts work:

<div id="volume"></div>
<script>
  var volume = new Slider('#volume', { value: 40, suffix: '%' })
</script>

Dual thumb — a two-element array as value creates a range with two thumbs that clamp at each other:

new Slider('#price', {
  min: 0, max: 1000, step: 10,
  value: [200, 650],          // [lo, hi] — sorted, snapped, clamped
  prefix: '$'
})

Replace mode (progressive enhancement) — pass an <input> and it is hidden (via the hidden attribute) and kept synced, so the form keeps posting the real value ("20,80" when dual) and receives native input / change events. The input's own min, max, step, value and disabled attributes seed any omitted options. destroy() restores the input untouched:

<input type="range" name="volume" min="0" max="100" value="40">
<script>
  new Slider(document.querySelector('[name=volume]'))
</script>

Static helpers cover the same ground:

Slider.create('#el', opts)   // identical to new Slider('#el', opts)
Slider.get('#el')            // existing instance for an element, or null
Slider.autoInit()            // init every [data-vsld] — also runs on page load

Options

All keys of Slider.defaults, with their exact defaults. Unknown option keys are ignored; there are no per-call-only constructor options beyond these. In replace mode, omitted min / max / step / value / disabled are seeded from the replaced input's attributes.

Instance methods

Useful instance properties: el (root element), track, thumbs, values, input (the replaced input, or null in build mode), opts, dual.

Statics & helpers

Events & callbacks

onInput fires on every move (each drag tick, each key press, and a changed setValue); onChange fires on commit — pointer release when the value differs from where the drag started, every key press, and a changed setValue. Both receive (value, slider), where value is a number or [lo, hi] for dual.

The root element also dispatches CustomEvents, so you can delegate without keeping a reference:

In replace mode the hidden original input additionally receives real, bubbling (non-cancelable) native input and change events on the same occasions — dispatched before the matching callback and CustomEvent — so existing listeners and frameworks keep working.

Declarative init (data-* attributes)

Any element with a data-vsld attribute is initialized automatically on DOMContentLoaded (or immediately if the script loads later), and again by any explicit Slider.autoInit(root?) call — already-initialized elements are skipped.

<div data-vsld data-min="0" data-max="100" data-value="40" data-suffix="%"></div>
<div data-vsld data-value="20,80" data-name="range" data-tooltip="always"></div>

format, labels, onInput and onChange have no declarative form — use the constructor, or listen for the slider:* CustomEvents.

Theming

With theme: 'auto' (the default) the theme is resolved as: VC core's shared engine when loaded, otherwise <html data-theme> / data-bs-theme → .dark / .light class on <html> → prefers-color-scheme — re-resolved live via a MutationObserver and a media-query listener. theme: 'light' / 'dark' pins an instance. The resolved theme is stamped on the root as data-theme.

All colors are CSS custom properties, defined on .vsld and re-defined on .vsld[data-theme=dark]:

CSS isolation: roots render as class="vsld vc1" and all structural rules ship salted (.vsld.vc1 .vsld-thumb { … }), so host-page design systems can't override the slider — while .vsld { --vsld-* } variable overrides keep working, because the variable definitions are deliberately unsalted. The injected stylesheet is inserted before the page's own CSS so your overrides win the cascade. Custom token: Slider.salt = 'acme' before the first instance; disable with Slider.salt = false. With the VC core loaded, VC.config({ accent: '#b45309' }) themes sliders and every other family component at once.

Headless: Slider.defaults.styles = false (or styles: false per instance) injects no CSS while keeping the full behavior — pointer capture, clamping, keyboard, ARIA, form sync. The stock stylesheet is available as the Slider.css string as a starting point. Markup contract:

.vsld.vsld-vertical.vsld-tip-always.vsld-disabled[data-theme=dark]
  .vsld-track                ← the rail (press/drag surface)
    .vsld-fill               ← range fill bar
    .vsld-mark               ← tick; one per step or per `marks` key
      .vsld-mark-label       ← only for object marks
    .vsld-thumb              ← role=slider; .vsld-active while dragging
      .vsld-tip              ← value bubble (absent when tooltip: false)
  input[type=hidden]         ← only when `name` given

Accessibility

Each thumb is a focusable role="slider" element carrying aria-valuemin / aria-valuemax / aria-valuenow, a formatted aria-valuetext, an aria-label from labels, and aria-orientation="vertical" when vertical. Dual thumbs advertise the sibling as their live limit (the low thumb's aria-valuemax is the high thumb's value, and vice versa). Disabled thumbs get aria-disabled="true" and tabindex="-1"; the tooltip bubble is aria-hidden. Transitions are dropped under prefers-reduced-motion: reduce.

Key presses are ignored while disabled or with Alt/Ctrl/Meta held. Every key press is both a move and a commit — it fires onInput and onChange.