Skip to main content

createSlider

Headless pointer dragging, keyboard stepping, step snapping, and thumb styles for single or multi-thumb range sliders.

View as Markdown

createSlider is the interaction engine behind Moraine’s Slider. It handles pointer dragging with pointer capture, keyboard stepping, value clamping, and step snapping. It also computes inline styles for the range and thumbs. It renders nothing: you provide the track and thumb elements and wire the returned handlers to them.

Import#

import { createSlider } from 'moraine/utils'

Features#

  • Accepts a number for one thumb, or an array of numbers for one thumb per entry, such as [20, 80] for a range.
  • Captures the pointer during a drag so tracking continues when the pointer leaves the track.
  • Handles Arrow Left/Right/Up/Down, PageUp/PageDown, and Home/End. Shift + arrow takes a page-sized step.
  • Supports horizontal and vertical orientation, reversed axes, and RTL.
  • Reports each change through onValueInput and each finished interaction through onValueCommit.

Signature#

function createSlider<TValue extends number | number[]>(
  props: CreateSliderProps<TValue>,
  options?: CreateSliderOptions<TValue>,
): CreateSliderReturn<TValue>

props configures the value and geometry. It is read reactively, so declare a getter for any value that changes:

Prop Default Notes
value, defaultValue min Controlled and initial value. The shape of value or defaultValue sets the shape of callback values.
min, max 0, 100 Values clamp to this range.
step None Pointer and keyboard values snap to multiples of it from min. Without it, values are continuous.
orientation, reversed 'horizontal', false Axis and direction of the track.
minStepsBetweenThumbs 0 Minimum gap between thumbs in step units. Above 0, thumbs cannot cross.
allowThumbCrossing true When false, a dragged thumb stops at its neighbor.
thumbAlignment 'overflow' 'contain' keeps thumb edges inside the track.
markers, styles.marker None Marker interval (true uses step) and extra marker styles.
readOnly, formatOptions, translations None Blocks changes; formats aria-valuetext; overrides messages.

options holds the callbacks and the disabled state:

Option Called when or effect
disabled Accessor. While it returns true, pointer and keyboard input are ignored.
onValueInput(value) The value changes during an interaction. It does not fire for programmatic value changes.
onValueCommit(value) The pointer is released, a navigation key is released, or focus leaves the thumbs after a change.
onFocus(event), onBlur(event) Focus enters or leaves the group of thumbs. Moving between thumbs fires neither.

Wire setTrackRef, setThumbRefs, and the onTrack*, onThumb*, and onPointerCancel handlers to your elements, as in the example. onThumbFocus and onThumbBlur track keyboard focus and commit on blur. Bind thumbStyles() and rangeStyle() for placement, and currentValues() for the live values.

Usage Example#

src/CustomSlider.tsx
import { createSlider } from 'moraine/utils'

export function CustomSlider() {
  const slider = createSlider({
    min: 0,
    max: 100,
    step: 5,
    defaultValue: 50,
  })

  return (
    <div class="relative h-6">
      <div
        ref={(element) => slider.setTrackRef(element)}
        class="absolute inset-x-0 top-1/2 h-2 -translate-y-1/2 rounded-full bg-muted touch-none"
        onPointerDown={slider.onTrackPointerDown}
        onPointerMove={slider.onTrackPointerMove}
        onPointerUp={slider.onTrackPointerUp}
        onPointerCancel={slider.onPointerCancel}
        onLostPointerCapture={slider.onPointerCancel}
      >
        <div class="absolute h-full rounded-full bg-primary" style={slider.rangeStyle()} />
      </div>

      <div
        ref={(element) => slider.setThumbRefs(() => [element])}
        tabIndex={0}
        role="slider"
        aria-label="Amount"
        aria-valuenow={slider.currentValues()[0] ?? 0}
        aria-valuemin={0}
        aria-valuemax={100}
        onPointerDown={(event) => slider.onThumbPointerDown(0, event)}
        onPointerMove={slider.onThumbPointerMove}
        onPointerUp={slider.onThumbPointerUp}
        onPointerCancel={slider.onPointerCancel}
        onLostPointerCapture={slider.onPointerCancel}
        onFocus={(event) => slider.onThumbFocus(0, event)}
        onBlur={slider.onThumbBlur}
        onKeyDown={(event) => slider.onThumbKeyDown(0, event)}
        onKeyUp={slider.onThumbKeyUp}
        style={slider.thumbStyles()[0]}
        class="absolute top-1/2 size-5 -translate-x-1/2 -translate-y-1/2 rounded-full bg-primary ring-2 ring-background shadow-md touch-none"
      />
    </div>
  )
}