# Elastic slider

> 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.

- Type: Component (inputs)
- Access: Pro
- Page: https://goodui.dev/native/components/elastic-slider
- Markdown: https://goodui.dev/native/components/elastic-slider.md
- Registry item: https://goodui.dev/native/r/elastic-slider.json
- Dependencies: react-native-gesture-handler, react-native-reanimated, react-native-svg
- Keywords: react native elastic slider, rubber band slider, bouncy slider reanimated, slider with value balloon, svg path slider, playful slider expo, stretchy range input

## When to use

- 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.

## When not to use

- 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.

## Installation

With the shadcn CLI (needs a components.json in the Expo app), then `npx expo install --fix` so native dependencies match your Expo SDK. The foundation comes along the first time.

```bash
npx shadcn@latest add @goodui-native-pro/elastic-slider
npx expo install --fix
```

Pro: add `"@goodui-native-pro": { "url": "https://goodui.dev/native/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${GOODUI_LICENSE_KEY}" } }` to the `registries` of components.json and put your license key in .env.local.

The component lands in `components/goodui-native/elastic-slider/` and imports the foundation from `components/goodui-native/foundation/` with relative paths; it also installs locale.

Built-in strings follow `<GooduiLocaleProvider>` (one [language pack](https://goodui.dev/native/r/locale-tr.json) translates the whole kit); the `labels` prop overrides them for one instance.

## Usage

```tsx
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}%`}
    />
  );
}
```

## Examples

### Stepped, a dot on every step, balloon always visible

```tsx
<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

```tsx
<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

```tsx
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

### ElasticSlider

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

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

## 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.

## Motion

- 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.

## Haptics

- select when the thumb crosses a mark, and when it reaches the minimum or the maximum
- `haptic={false}` silences both

## Performance

- 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.

## 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).

## Related

- [Slider](https://goodui.dev/native/components/slider.md): Single and range sliders whose thumbs follow the finger 1:1 and settle onto the nearest step on release, with a value bubble that grows out of the thumb while dragging and optional step ticks that tick.
- [Quantity stepper](https://goodui.dev/native/components/quantity-stepper.md): A − value + stepper whose value rolls in the direction of change. Hold a button to repeat with acceleration; the ends push back with a rubber-band bounce and a warning haptic. In a cart the − turns into a trash button at the minimum.
- [Wheel picker](https://goodui.dev/native/components/wheel-picker.md): iOS-style wheel: rows sit on a cylinder in 3D perspective, follow the finger 1:1, keep the fling's momentum and settle exactly on a row with a select tick for every row that passes. Compose several into one picker with WheelPickerGroup. On the web it scrolls with the mouse wheel and drags with the mouse.

## Guidance for AI tools

Elastic slider: 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. Use only the documented props. Keep accessibility, reduced motion and both color schemes intact when adapting it.

Full library index: https://goodui.dev/native/llms.txt
