{"slug":"range-slider","name":"Range Slider","description":"Slider with tick dots and a vertical-bar thumb that bounces as it lands on each step. Drag or keyboard, reduced-motion safe.","category":"motion","source_url":"https://beui.dev/r/range-slider/raw","detail_url":"https://beui.dev/r/range-slider","raw_url":"https://beui.dev/r/range-slider/raw","page_url":"https://beui.dev/components/motion/range-slider","markdown_url":"https://beui.dev/components/motion/range-slider.md","published_at":"2026-06-24","updated_at":"2026-09-09","dependencies":["clsx","motion","react","tailwind-merge"],"internal":["@/components/motion/range-slider","@/lib/ease","@/lib/hooks/use-slider","@/lib/touch","@/lib/utils"],"files":[{"path":"components/motion/range-slider.tsx","type":"component","content":"\"use client\";\n// beui.dev/components/motion/range-slider\n\nimport {\n motion,\n useMotionValue,\n useReducedMotion,\n useSpring,\n useTransform,\n} from \"motion/react\";\nimport { useEffect, useLayoutEffect, useState } from \"react\";\n\nimport { SPRING_GLIDE } from \"@/lib/ease\";\nimport { type SliderOptions, useSlider } from \"@/lib/hooks/use-slider\";\nimport { TOUCH_GESTURE_CLASS } from \"@/lib/touch\";\nimport { cn } from \"@/lib/utils\";\n\n// Bouncy grab feedback for the thumb scale only.\nconst SPRING_BOUNCY = { type: \"spring\", stiffness: 500, damping: 14, mass: 0.7 } as const;\n\nexport interface RangeSliderProps extends SliderOptions {\n /** Render a tick dot at each step. */\n showTicks?: boolean;\n className?: string;\n}\n\nexport function RangeSlider({ showTicks = true, className, ...options }: RangeSliderProps) {\n const reduce = useReducedMotion();\n const { percent, dragging, min, max, step, trackProps, sliderProps } = useSlider(options);\n const [trackWidth, setTrackWidth] = useState(292);\n useLayoutEffect(() => {\n const track = trackProps.ref.current;\n if (!track) return;\n const measure = () => {\n const width = track.getBoundingClientRect().width;\n if (width > 0) setTrackWidth(width);\n };\n measure();\n const observer = new ResizeObserver(measure);\n observer.observe(track);\n return () => observer.disconnect();\n }, [trackProps.ref]);\n\n // Spring-smoothed position drives both the thumb and the fill.\n const target = useMotionValue(percent);\n useEffect(() => {\n target.set(percent);\n }, [percent, target]);\n const smooth = useSpring(target, SPRING_GLIDE);\n const pos = reduce ? target : smooth;\n const thumbX = useTransform(pos, (p) => 8 + Math.max(0, trackWidth - 20) * p / 100);\n // Match InlineSlider: the 4px handle starts 8px inside the track, and\n // the rounded fill extends 8px past its left edge. Translate a full-size\n // fill inside the 2px inset clip so its corner never stretches.\n const fillX = useTransform(pos, (p) => p >= 100\n ? \"0%\"\n : `calc(${p - 100}% + ${14 - 0.16 * p}px)`);\n\n // Floor rather than round, so a range the step does not divide (0 to 10 by 4)\n // stops its dots at the last whole step instead of drawing one past max.\n // toFixed comes first because 0.3/0.1 is 2.9999999999999996, which would\n // floor to 2 and drop the last dot.\n const steps = Math.floor(Number(((max - min) / step).toFixed(6)));\n const ticks =\n showTicks && steps > 0 && steps <= 50\n ? Array.from({ length: steps + 1 }, (_, i) => Number((min + i * step).toFixed(6)))\n : [];\n\n return (\n \n
\n \n
\n\n {/* Tick centres follow the same inset path as the handle centre. */}\n
\n {ticks.map((t) => {\n const tp = ((t - min) / (max - min)) * 100;\n return (\n \n );\n })}\n
\n\n {/* Keep the handle inside the rounded progress fill at both ends. */}\n \n \n );\n}\n"},{"path":"lib/ease.ts","type":"util","content":"// Shared motion tokens. Easing curves mirror the CSS custom properties in\n// globals.css; springs are the canonical physics used across components.\n// Strong custom variants — defaults like `ease-in`/`ease-out` feel weak.\n\nexport const EASE_OUT = [0.16, 1, 0.3, 1] as const;\nexport const EASE_IN_OUT = [0.77, 0, 0.175, 1] as const;\nexport const EASE_DRAWER = [0.32, 0.72, 0, 1] as const;\n\n/** CSS string form of EASE_OUT for inline style transitions. */\nexport const EASE_OUT_CSS = \"cubic-bezier(0.16, 1, 0.3, 1)\";\n\n/** Press feedback on buttons and other tappable surfaces. */\nexport const SPRING_PRESS = {\n type: \"spring\",\n stiffness: 500,\n damping: 30,\n mass: 0.6,\n} as const;\n\n/** Content swaps — label/icon slots trading places inside a control. */\nexport const SPRING_SWAP = {\n type: \"spring\",\n stiffness: 460,\n damping: 30,\n mass: 0.55,\n} as const;\n\n/** Overlay panel entrances — modals and sheets summoned by pointer. */\nexport const SPRING_PANEL = {\n type: \"spring\",\n stiffness: 420,\n damping: 40,\n mass: 0.5,\n} as const;\n\n/** Shared-layout glides — pills, indicators and panels morphing between positions. */\nexport const SPRING_LAYOUT = {\n type: \"spring\",\n stiffness: 360,\n damping: 32,\n mass: 0.6,\n} as const;\n\n/** Cursor-follow physics for decorative mouse tracking (magnetic, tilt, dock). */\nexport const SPRING_MOUSE = {\n stiffness: 200,\n damping: 15,\n mass: 0.3,\n} as const;\n\n/** Dragged handles and fills (sliders) — critically damped `useSpring` config,\n * so the value follows the pointer butterily and never rebounds off an end. */\nexport const SPRING_GLIDE = {\n stiffness: 700,\n damping: 50,\n mass: 0.5,\n} as const;\n"},{"path":"lib/hooks/use-slider.ts","type":"util","content":"\"use client\";\n\nimport { type KeyboardEvent, type PointerEvent, useCallback, useRef, useState } from \"react\";\nimport { capturePointer, releasePointer } from \"@/lib/touch\";\n\nconst clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v));\n\n/** Nearest legal value on [min, max] for the given step. max counts as a\n * candidate when the step does not divide the range, so a pointer near the end\n * does not snap back onto the last whole step. */\nexport function snapSliderValue(next: number, min: number, max: number, step: number): number {\n // Neither case has a grid to walk. An empty range has exactly one legal\n // point, and a non-positive step only needs a clamp, which also keeps the\n // division below away from zero.\n if (!(max > min)) return min;\n if (!(step > 0)) return clamp(next, min, max);\n const whole = Math.floor(Number(((max - min) / step).toFixed(6)));\n const lastWhole = Number((min + whole * step).toFixed(6));\n const toGrid = clamp(Math.round((next - min) / step) * step + min, min, lastWhole);\n const snapped =\n lastWhole < max && Math.abs(next - max) <= Math.abs(next - toGrid) ? max : toGrid;\n return Number(snapped.toFixed(6));\n}\n\nexport interface SliderOptions {\n value?: number;\n defaultValue?: number;\n onValueChange?: (value: number) => void;\n min?: number;\n max?: number;\n step?: number;\n disabled?: boolean;\n \"aria-label\"?: string;\n /** Announced instead of the raw number — pass one when the value carries a\n * unit or a suffix (\"72.5 kg\", \"35%\"); a bare number needs no valueText. */\n formatValueText?: (value: number) => string;\n}\n\n/**\n * Shared value + input plumbing for slider designs: controlled/uncontrolled\n * value, step snapping, pointer-capture drag along a track and arrow-key\n * control. Visuals and motion live in the component; this only owns the number.\n */\nexport function useSlider({\n value,\n defaultValue = 0,\n onValueChange,\n min = 0,\n max = 100,\n step = 1,\n disabled = false,\n \"aria-label\": ariaLabel,\n formatValueText,\n}: SliderOptions) {\n const trackRef = useRef(null);\n const sliderEl = useRef(null);\n // The state drives visuals. Move reads this ref instead, so the first\n // pointermove after pointerdown does not have to wait on a re-render.\n const draggingRef = useRef(false);\n const [internal, setInternal] = useState(defaultValue);\n const [dragging, setDragging] = useState(false);\n const controlled = value !== undefined;\n // Collapse inverted or empty ranges and non-positive steps here, so that\n // percent, ticks and the keyboard maths never divide by zero or walk a\n // NaN grid.\n const lo = min;\n const hi = max > min ? max : min;\n const stride = step > 0 ? step : 1;\n const current = clamp(controlled ? value : internal, lo, hi);\n const percent = hi > lo ? ((current - lo) / (hi - lo)) * 100 : 0;\n\n const commit = useCallback(\n (next: number) => {\n const clean = snapSliderValue(next, lo, hi, stride);\n if (!controlled) setInternal(clean);\n onValueChange?.(clean);\n },\n [controlled, onValueChange, lo, hi, stride],\n );\n\n const commitFromX = useCallback(\n (clientX: number) => {\n const rect = trackRef.current?.getBoundingClientRect();\n if (!rect || rect.width === 0) return;\n const ratio = clamp((clientX - rect.left) / rect.width, 0, 1);\n commit(lo + ratio * (hi - lo));\n },\n [commit, lo, hi],\n );\n\n const onPointerDown = useCallback(\n (event: PointerEvent) => {\n if (disabled) return;\n // Start the drag first: capture is a convenience, and a browser that\n // refuses it — or a test DOM that has no pointer capture at all — must\n // not take the drag down with it.\n draggingRef.current = true;\n setDragging(true);\n capturePointer(event.currentTarget, event.pointerId);\n // A click on the track should land keyboard focus on the handle.\n sliderEl.current?.focus({ preventScroll: true });\n commitFromX(event.clientX);\n },\n [disabled, commitFromX],\n );\n\n const onPointerMove = useCallback(\n (event: PointerEvent) => {\n if (!draggingRef.current || disabled) return;\n commitFromX(event.clientX);\n },\n [disabled, commitFromX],\n );\n\n const endDrag = useCallback((event: PointerEvent) => {\n releasePointer(event.currentTarget, event.pointerId);\n draggingRef.current = false;\n setDragging(false);\n }, []);\n\n const onKeyDown = useCallback(\n (event: KeyboardEvent) => {\n if (disabled) return;\n const map: Record = {\n ArrowRight: current + stride,\n ArrowUp: current + stride,\n ArrowLeft: current - stride,\n ArrowDown: current - stride,\n PageUp: current + stride * 10,\n PageDown: current - stride * 10,\n Home: lo,\n End: hi,\n };\n if (event.key in map) {\n event.preventDefault();\n commit(map[event.key]);\n }\n },\n [disabled, current, stride, lo, hi, commit],\n );\n\n return {\n current,\n percent,\n dragging,\n min: lo,\n max: hi,\n step: stride,\n commit,\n /** Pointer handlers for the track element — drag anywhere on it. */\n trackProps: {\n ref: trackRef,\n onPointerDown,\n onPointerMove,\n onPointerUp: endDrag,\n onPointerCancel: endDrag,\n onLostPointerCapture: endDrag,\n },\n /** ARIA + keyboard props for the focusable slider element. */\n sliderProps: {\n // Callback keeps the handle typed across button/div/motion hosts.\n ref: (node: HTMLElement | null) => {\n sliderEl.current = node;\n },\n role: \"slider\" as const,\n tabIndex: disabled ? -1 : 0,\n \"aria-label\": ariaLabel,\n \"aria-valuemin\": lo,\n \"aria-valuemax\": hi,\n \"aria-valuenow\": current,\n \"aria-valuetext\": formatValueText?.(current),\n \"aria-disabled\": disabled || undefined,\n onKeyDown,\n },\n };\n}\n"},{"path":"lib/touch.ts","type":"util","content":"// Shared touch primitives. iOS and iPadOS run their own gestures on top of the\n// page — the long-press selection callout and the selection it drags in with\n// it — and they win: once the platform claims a touch it cancels ours\n// mid-gesture, so a press-and-hold or a drag simply dies. Surfaces that own\n// their gesture have to opt out.\n//\n// What the two classes below cover, precisely:\n// - `-webkit-touch-callout: none` stops iOS's long-press callout. WebKit-only:\n// it is not a property other engines have, so it is inert everywhere else.\n// - `user-select: none` stops the long-press selection on every engine,\n// Android included, and stops a drag from painting a selection under the\n// cursor. It is inherited, so it reaches every descendant — which is why the\n// two classes differ only in whether they apply it unconditionally.\n// What neither covers:\n// - Chrome for Android's long-press menu on a link or an image. No CSS\n// suppresses it; a gesture surface that wraps one needs its own\n// `onContextMenu` with `preventDefault()`.\n// - The native drag of an `` or `` descendant. `-webkit-user-drag` is\n// not inherited and plain divs and buttons are not drag sources, so setting\n// it on the surface does nothing — the child itself needs `draggable={false}`.\n\n/**\n * Classes for a surface that *is* the control: a thumb, a drum, a stage, a\n * handle, a hold button. Selection is suppressed on every input, because a\n * drag that highlights the control's own label is wrong on a mouse too.\n * Compose with `touch-none` when the surface also owns the scroll axis — leave\n * it off when the page must still scroll from there.\n */\nexport const TOUCH_GESTURE_CLASS = \"select-none [-webkit-touch-callout:none]\";\n\n/**\n * The same opt-out for a gesture surface that wraps content the consumer owns:\n * a scroller, a context-menu trigger, a sheet header, a list row. Selection is\n * suppressed only where the platform runs its own press gestures — a coarse\n * pointer — so a mouse user can still select and copy that content. If the\n * gesture itself would paint a selection under the cursor, add `select-none`\n * for the duration of the gesture rather than reaching for\n * `TOUCH_GESTURE_CLASS`.\n *\n * `pointer: coarse` describes the *primary* pointer and nothing else, so a\n * hybrid machine reads it wrong in both directions: a tablet with a mouse\n * plugged in keeps touch as primary and loses mouse selection, and a laptop\n * with a touchscreen keeps the mouse as primary and leaves selection live\n * under a finger. No media query can answer per interaction — the query is\n * about the device, and the question is about the gesture in progress. The\n * default stays here because it is right on the machines that are one thing or\n * the other, and losing a selection is a nuisance; where the miss costs a\n * *gesture* instead, the surface pairs it with `holdSelection` on the press.\n */\nexport const TOUCH_GESTURE_CONTENT_CLASS =\n \"[-webkit-touch-callout:none] pointer-coarse:select-none\";\n\n/**\n * Suppress selection on `element` for as long as a gesture is running on it,\n * whatever the primary pointer of the machine happens to be. Returns the\n * release. Inline, so it wins over the class above and is gone again the\n * moment the gesture ends.\n *\n * For the press gestures a native selection would otherwise steal — a\n * long-press that opens a menu. Elsewhere prefer the classes: a surface that\n * takes selection away for the whole session is a surface whose text nobody\n * can copy.\n */\nexport function holdSelection(element: HTMLElement) {\n element.style.setProperty(\"user-select\", \"none\");\n element.style.setProperty(\"-webkit-user-select\", \"none\");\n return () => {\n element.style.removeProperty(\"user-select\");\n element.style.removeProperty(\"-webkit-user-select\");\n };\n}\n\n/**\n * Pointer capture, best effort. WebKit throws `NotFoundError` when the pointer\n * is already gone by the time the handler runs — routine on iOS, where the\n * system can claim the touch first — and an uncaught throw takes the rest of\n * the handler, the gesture included, down with it. Touch pointers carry\n * implicit capture anyway, so losing it is never fatal.\n */\nexport function capturePointer(element: Element, pointerId: number) {\n try {\n element.setPointerCapture(pointerId);\n } catch {\n // Pointer is no longer active — implicit capture still applies on touch.\n }\n}\n\n/** Release a capture taken with `capturePointer`, ignoring a stale pointer. */\nexport function releasePointer(element: Element, pointerId: number) {\n try {\n if (element.hasPointerCapture(pointerId)) {\n element.releasePointerCapture(pointerId);\n }\n } catch {\n // Capture was already dropped by the browser.\n }\n}\n\n/**\n * Whether this event came from a pointer that is *hovering*: not a touch, and\n * not currently pressed. Which input the user is holding right now is not\n * something a device capability can answer — a touchscreen laptop hovers and\n * taps, and iPadOS reports a fine hovering pointer for a finger — so both\n * paths stay live and each handler branches on the event it was given.\n *\n * A pen resting on the glass is making contact, not hovering: `buttons` is the\n * tell, and it sends a pen tap down the same route a finger takes.\n *\n * This answers what an *enter* asks. A leave is the other half of a pair and\n * has to be read against the enter that started it — `useHoverGesture` in\n * `lib/hooks/use-hover-gesture` does that, and hover surfaces should use it\n * rather than asking this question twice.\n */\nexport const isHoveringPointer = (event: {\n pointerType: string;\n buttons: number;\n}) => event.pointerType !== \"touch\" && event.buttons === 0;\n"},{"path":"lib/utils.ts","type":"util","content":"import { clsx, type ClassValue } from \"clsx\"\nimport { twMerge } from \"tailwind-merge\"\n\nexport function cn(...inputs: ClassValue[]) {\n return twMerge(clsx(inputs))\n}\n"},{"path":"components/previews/motion/range-slider.preview.tsx","type":"preview","content":"\"use client\";\n\nimport { useState } from \"react\";\n\nimport { RangeSlider } from \"@/components/motion/range-slider\";\n\nexport function RangeSliderPreview() {\n const [value, setValue] = useState(40);\n\n return (\n
\n
\n Drag the handle\n {value}\n
\n \n
\n );\n}\n"}]}