@19h47/slider

@19h47/slider

Multi-thumb range slider controller (APG-style). One instance controls both thumbs inside a rail and prevents crossing ((min \le max)).

Based on the W3C APG multi-thumb slider pattern: W3C APG – Horizontal Multi-Thumb Slider Example

Installation

npm i @19h47/slider

Markup (HTML-first)

The controller expects a rail element that contains exactly 2 thumbs with role="slider".

The library is HTML-first for ARIA attributes (it does not set aria-orientation at runtime), but its internal orientation is determined by the JS option.

Important: thumbs order matters (matches APG):

• first thumb = max
• second thumb = min

Example:

<div class="rail">
  <button
    role="slider"
    tabindex="0"
    class="max"
    aria-label="Maximum value"
    aria-valuemin="0"
    aria-valuemax="35"
    aria-valuenow="35"
    aria-valuetext="35"
    aria-orientation="horizontal"
  ></button>

  <button
    role="slider"
    tabindex="0"
    class="min"
    aria-label="Minimum value"
    aria-valuemin="0"
    aria-valuemax="35"
    aria-valuenow="0"
    aria-valuetext="0"
    aria-orientation="horizontal"
  ></button>
</div>

The controller keeps these attributes updated:

• aria-valuenow / aria-valuetext on both thumbs
• aria-valuemin on the max thumb (set to current min)
• aria-valuemax on the min thumb (set to current max)

Usage

import Slider from '@19h47/slider'

const rail = document.querySelector('.rail')
const slider = new Slider(rail, { orientation: 'horizontal', width: 24, height: 24 })

slider.init();

If you attach sliders dynamically, call destroy() to remove global listeners:

slider.destroy()

Options

type Orientation = 'horizontal' | 'vertical'

type Options = {
  orientation: Orientation
  width: number
  height: number
  direction: 'auto' | 'ltr' | 'rtl'
  step: number
  page: number
}

Defaults:

• orientation: 'horizontal'
• width: 24
• height: 24
• direction: 'auto' (reads getComputedStyle(rail).direction)
• step: 1
• page: 10

Notes:

• This implementation keeps the thumbs always visible by applying a constant 1-thumb offset (vertical: min thumb; horizontal: max thumb), matching the original library approach.
• In RTL (direction: 'rtl' or dir="rtl"), the horizontal slider reverses the value axis (higher values to the left) and swaps Left/Right arrow behavior.

Events

The controller dispatches a DOM event on the rail:

• name: Slider.change
• target: rail element
• detail:

type Detail = {
  min: number
  max: number
  active: 'min' | 'max'
}

Example:

rail.addEventListener('Slider.change', (event) => {
  const { min, max, active } = event.detail
  console.log({ min, max, active })
})

Utilities

If you need to draw UI based on geometry (range bar, tooltips), you can use:

• slider.rect(): returns a DOMRect snapshot for the rail

Keyboard support

Key	Function
Right Arrow	Increases slider value one step.
Up Arrow	Increases slider value one step.
Left Arrow	Decreases slider value one step.
Down Arrow	Decreases slider value one step.
Page Up	Increases slider value by page.
Page Down	Decreases slider value by page.
Home	Sets slider to its minimum value.
End	Sets slider to its maximum value.

Orientation + positioning

This package positions thumbs via transform: translate3d(...).

It uses a “thumb origin” coordinate system (top-left of the thumb) and:

• track: railLength - 2 * thumbSize
• offset (always visible):
  • vertical: min thumb is offset by +height
  • horizontal: max thumb is offset by +width

So your CSS should set a stable origin for thumbs (e.g. top: 0 for vertical, left: 0 for horizontal) and let JS handle positioning.

Acknowledgments

• Multithumb slider