Elastic slider

ProReact Native · Expo

A slider on a rubber band: the thumb follows the finger 1:1 along the line, the band bends toward the finger when the thumb is pulled above or below it and twangs back with a damped wobble on release, while a value balloon leans against the drag and swings upright again.

View as Markdown

Installation

$ npx shadcn@latest add @goodui-native-pro/elastic-slider

Then run npx expo install --fix so react-native-gesture-handler, react-native-reanimated, react-native-svg match your Expo SDK. Files land in components/goodui-native/elastic-slider.

Pro components and screens install from the license-gated @goodui-native-pro registry. Setup: Pro access.

Usage

import { useState } from "react";
import { ElasticSlider } from "@/components/goodui-native/elastic-slider/elastic-slider";

export function TipPicker() {
  const [tip, setTip] = useState(15);
  return (
    <ElasticSlider
      accessibilityLabel="Tip"
      min={0}
      max={30}
      value={tip}
      onChange={setTip}
      marks={[10, 15, 20]}
      formatValue={(v) => `${v}%`}
    />
  );
}

When to use

Use it for
  • A value the person plays with rather than sets precisely: a tip, a mood, intensity, playback speed, a budget.
  • The one hero control of a screen, where the motion is part of the product's character.
  • A small set of stepped values that should feel physical: marks ride on the band and tick as the thumb crosses them.
Reach for something else
  • Settings lists and dense forms with several sliders: use slider, which is quiet and has a range variant.
  • A range with two thumbs: use slider's RangeSlider.
  • An exact number the person types: use text-field. Small counts changed by one: use quantity-stepper.
  • Right above or below controls that must stay readable while dragging: the band bends up to `stretch` points over its neighbors.

Examples

Stepped, a dot on every step, balloon always visible

<ElasticSlider accessibilityLabel="Playback speed" min={0.5} max={2} step={0.25} marks showValue="always" value={speed} onChange={setSpeed} formatValue={(v) => `${v}x`} />

Save only when the finger lifts

<ElasticSlider accessibilityLabel="Price ceiling" tone="success" min={0} max={500} step={10} value={price} onChange={setPrice} onChangeEnd={(v) => api.saveCeiling(v)} formatValue={(v) => `$${v}`} />

A scripted hint: pull the band and let it twang

const slider = useRef<ElasticSliderHandle>(null);

// for example once, the first time the screen opens
slider.current?.dragTo(60, -40, 800);
setTimeout(() => slider.current?.release(), 900);

<ElasticSlider ref={slider} accessibilityLabel="Intensity" value={value} onChange={setValue} />

API reference

PropTypeDefault
value
The value (controlled). Pair it with `onChange`.
number—
defaultValue
Initial value when uncontrolled. Defaults to `min`.
number—
onChange
Called while dragging, each time the snapped value changes.
(value: number) => void—
onChangeEnd
Called once when the finger lifts, with the final value. Save or fetch here.
(value: number) => void—
min
Lowest value. Default 0.
number0
max
Highest value. Default 100.
number100
step
Values snap to multiples of this. Default 1. `0` is continuous.
number1
marks
Dots that ride on the band: `true` puts one on every step (40 steps or fewer), an array puts them at those values. Crossing one ticks.
boolean | number[]false
formatValue
Text for a value in the balloon and for screen readers, for example `(v) => \`$${v}\``.
(value: number) => string—
showValue
Value balloon above the thumb: `drag` inflates while dragging, `always` stays, `never`.
"drag" | "always" | "never""drag"
stretch
How far the band can be pulled off the line, in points. Default 56. `0` keeps it straight.
number56
tone
Color of the filled part and the balloon. `accent` by default; status tones only when the value means a status.
"success" | "warning" | "danger" | "accent""accent"
disabled
Dims the control and ignores presses.
booleanfalse
haptic
`false` silences the mark and edge haptics.
booleantrue
accessibilityLabel*
Screen reader name, for example "Tip".
string—
ref
Imperative handle: `ref.current?.dragTo(60, -40)` then `ref.current?.release()`.
Ref<ElasticSliderHandle>—
style
Style for the outer container.
StyleProp<ViewStyle>—
testID
Identifier for end-to-end tests.
string—

Motion and haptics

  • Touch down: the thumb grows to 1.12 and the balloon inflates out of it on the snappy spring. Touched away from the thumb, the thumb glides to the finger on snappy while it already tracks it.
  • Drag: the thumb follows the finger 1:1 along the line, with about 10 pt of give past either end. Off the line it follows through an iOS-style rubber band (1:1 at first, never past `stretch`); the band is redrawn every frame as two straight pulls from its anchors to the thumb, thins as it stretches, and its shoulders trail the thumb, so a quick move whips it.
  • The balloon is a pendulum hanging off the thumb: thumb speed pushes it back against the motion (up to about 34 degrees) and it swings upright again when the thumb stops.
  • Release: the thumb settles on its step on the bouncy spring with the finger's velocity (a small wobble), the band twangs back to the line on a lightly damped spring (three to four visible swings), and the balloon deflates half a second later.
  • Outside value changes and keyboard steps move the thumb on the bouncy spring.
  • Reduced motion: the thumb still follows the finger along the line, but the band stays straight, nothing swings, wobbles or lags, the balloon appears without growing, and releases and outside changes jump into place.
  • Haptic: select when the thumb crosses a mark, and when it reaches the minimum or the maximum
  • Haptic: `haptic={false}` silences both
  • The drag, the band's path and the mark positions run on the UI thread: Gesture Handler writes a virtual finger into shared values, the SVG path's `d` is built in a worklet from 24 sample points per frame.
  • The band's shoulders and the balloon's swing are integrated in a frame callback that runs only while something moves and goes to sleep about ten frames after everything is at rest.
  • React renders only when the snapped value changes (for the balloon text and onChange). With step={1} over a wide range that is one render per step crossed, so keep the parent's render light or raise `step`.
  • Each mark is one animated circle: `marks` on every step is capped at 40 steps.

Accessibility

  • The thumb is one adjustable element with the required accessibilityLabel; accessibilityValue carries min, max, now and the formatted text.
  • Screen readers cannot drag: the increment and decrement actions (swipe up and down in VoiceOver, volume keys in TalkBack) step the value by `step`, or by a twentieth of the range when the slider is continuous. Each step also fires onChangeEnd.
  • On the web the thumb is focusable with role slider and aria-valuenow / aria-valuetext; the arrow keys step it (the arrow toward the maximum increases, so Left and Right swap under RTL) and the balloon shows while it has focus.
  • The balloon is hidden from screen readers: its text is already the element's value.
  • No built-in strings.

Notes for AI

  • accessibilityLabel is required. Pass value + onChange (controlled) or defaultValue. The callbacks are onChange and onChangeEnd, not onValueChange / onSlidingComplete as on slider.
  • It stretches to its parent's width and is 48 pt tall. The band bends up to `stretch` points (default 56) above and below that, and the balloon needs about 44 pt above the thumb: leave that much free space, or wrap it in a View with paddingTop and paddingBottom. With showValue="always" the component reserves the balloon's space itself.
  • Do not put it inside a horizontally scrolling container. Inside a vertical ScrollView it claims touches that start on its 48 pt band, so the page cannot be scrolled from there.
  • Use formatValue for units ('%', '$', 'x'); the same text is read by screen readers. Do not render your own label over the thumb.
  • marks={true} needs step > 0 and at most 40 steps; otherwise pass the values to mark as an array.
  • stretch={0} turns the vertical pull off and leaves a slider with the balloon and the settling wobble.
  • The ref handle (dragTo, release) is for hints and demos. dragTo holds the thumb until release is called, and a real touch takes over from it.
  • One per screen is plenty; for ordinary settings use slider.
  • Requires GestureHandlerRootView at the app root (see the foundation setup).