react-native-step-slider 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ismnoiet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+
+<div align="center">
+
+<table>
+  <tr>
+    <th align="center">iOS</th>
+    <th align="center">Android</th>
+  </tr>
+  <tr>
+    <td align="center">
+      <img src="https://github.com/ismnoiet/detailed-react-native-dot-slider/blob/main/step-slider-ios-demos.gif" width="300" height="700" alt="iOS demo" />
+    </td>
+    <td align="center">
+      <img src="https://github.com/ismnoiet/detailed-react-native-dot-slider/blob/main/step-slider-android-demos.gif" width="300" height="700" alt="Android demo" />
+    </td>
+  </tr>
+</table>
+
+
+<h1>react-native-step-slider</h1>
+
+<p>A beautifully animated step slider for React Native — with spring snap and tap-to-select gestures.</p>
+
+<p>
+  <img src="https://img.shields.io/npm/v/react-native-step-slider.svg?style=flat-square" alt="Version" />
+  <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" />
+  <img src="https://img.shields.io/badge/platform-iOS%20%7C%20Android-blue.svg" alt="Platform" />
+  <img src="https://img.shields.io/badge/PRs-welcome-purple.svg" alt="PRs Welcome" />
+</p>
+
+</div>
+
+---
+
+## ✨ Features
+
+- 📱 **Works on iOS & Android** — consistent behaviour and look across both platforms
+- 🎨 **Fully customisable** — colours, dot count, size and layout
+- ⚡ **Silky smooth performance** — animations and gestures never block your UI
+- 🎯 **Tap to jump** — tap any dot to jump straight to that step
+- 🟣 **Active dot pulse** — the selected dot pops with a springy highlight
+- 🌊 **Progress fill** — a live fill tracks your position across the slider
+
+---
+
+## Installation
+
+```sh
+npm install react-native-step-slider
+# or
+yarn add react-native-step-slider
+```
+
+### Peer dependencies
+
+Install all three peer packages if they aren't already in your project:
+
+```sh
+npm install @shopify/react-native-skia react-native-reanimated react-native-gesture-handler
+```
+
+| Package | Minimum version |
+|---|---|
+| `@shopify/react-native-skia` | `>= 1.0.0` |
+| `react-native-reanimated` | `>= 3.0.0` |
+| `react-native-gesture-handler` | `>= 2.0.0` |
+| `react` | `>= 18` |
+| `react-native` | `>= 0.72` |
+
+### iOS
+
+```sh
+cd ios && pod install
+```
+
+### Babel config
+
+Make sure `react-native-reanimated/plugin` is the **last** item in your `babel.config.js` plugins array:
+
+```js
+// babel.config.js
+module.exports = {
+  presets: ['module:@react-native/babel-preset'],
+  plugins: ['react-native-reanimated/plugin'],
+};
+```
+
+---
+
+## Quick start
+
+Wrap your app in `GestureHandlerRootView` (once, at the root) and drop in `DotSlider`:
+
+```tsx
+import React, { useState } from 'react';
+import { Text, View } from 'react-native';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import { DotSlider } from 'react-native-step-slider';
+
+export default function App() {
+  const [step, setStep] = useState(5);
+
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <View style={{ padding: 32 }}>
+        <Text>Step {step + 1} of 11</Text>
+        <DotSlider dotCount={11} defaultIndex={5} onValueChange={setStep} />
+      </View>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `dotCount` | `number` | `11` | Number of selectable steps. |
+| `defaultIndex` | `number` | `Math.floor(dotCount / 2)` | Initially selected dot index (0-based). |
+| `width` | `number` | `screenWidth − 64` | Total width of the slider track in dp. |
+| `trackHeight` | `number` | `56` | Height of the pill-shaped track in dp. |
+| `colors` | `DotSliderColors` | *(blue theme)* | Override any or all colour tokens. |
+| `onValueChange` | `(index: number) => void` | `undefined` | Called every time the selected index changes. |
+
+---
+
+## DotSliderColors
+
+All fields are optional — only provide the tokens you want to override.
+
+| Field | Default | Description |
+|---|---|---|
+| `track` | `'#e8f0fe'` | Track background fill. |
+| `fill` | `'#4f86f7'` | Progress fill (left of thumb). |
+| `dotActive` | `'#1a56f0'` | Selected dot colour. |
+| `dotInactive` | `'#a8c3fa'` | Unselected dot colour. |
+| `thumb` | `'#1a56f0'` | Thumb pill colour. |
+| `thumbShadow` | `'rgba(26,86,240,0.4)'` | Thumb drop-shadow colour. |
+
+```tsx
+<DotSlider
+  dotCount={7}
+  colors={{
+    track: '#fdf2f8',
+    fill: '#fbcfe8',
+    dotActive: '#ec4899',
+    dotInactive: '#f9a8d4',
+    thumb: '#ec4899',
+    thumbShadow: 'rgba(236,72,153,0.45)',
+  }}
+  onValueChange={(i) => console.log('selected:', i)}
+/>
+```
+
+---
+
+## Example app
+
+A runnable demo is in [`Demos.tsx`](./Demos.tsx) at the root of the repo. It shows a wide variety of real-world use cases — volume, brightness, font size, filters, ratings and more.
+
+---
+
+## How it works
+
+The slider is rendered on a single hardware-accelerated canvas, so every dot, the progress fill and the animated thumb are drawn in one efficient pass — no layout thrashing. Animations run on a dedicated UI thread, meaning dragging and snapping stay perfectly smooth even when your JavaScript is busy. The `onValueChange` callback is only fired when the selected step actually changes, keeping unnecessary re-renders to a minimum.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please open an issue first to discuss what you'd like to change.
+
+---
+
+## License
+
+MIT © [ismnoiet](https://github.com/ismnoiet) — see [LICENSE](./LICENSE) for details.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "react-native-step-slider",
+  "version": "1.0.0",
+  "description": "A smooth, customisable step slider for React Native with spring snap, animated progress fill and tap-to-select.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src/"
+  ],
+  "keywords": [
+    "react-native",
+    "slider",
+    "step",
+    "stepper",
+    "steps",
+    "dot",
+    "dots",
+    "smooth",
+    "interactive",
+    "skia",
+    "reanimated",
+    "gesture-handler",
+    "animation",
+    "component"
+  ],
+  "author": "ismnoiet",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ismnoiet/react-native-step-slider.git"
+  },
+  "peerDependencies": {
+    "@shopify/react-native-skia": ">=1.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0",
+    "react-native-gesture-handler": ">=2.0.0",
+    "react-native-reanimated": ">=3.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/react-native": "^0.73.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/DotSlider.tsx

@@ -0,0 +1,400 @@
+/**
+ * DotSlider
+ *
+ * A smooth, fully Skia-rendered horizontal slider with dot step markers,
+ * animated progress fill, spring snap, and tap-to-select.
+ *
+ * Peer dependencies:
+ *   @shopify/react-native-skia    >= 1.0.0
+ *   react-native-reanimated       >= 3.0.0 | 4.x
+ *   react-native-gesture-handler  >= 2.0.0
+ */
+
+import React from 'react';
+import { Dimensions, StyleSheet, View } from 'react-native';
+
+import {
+  Canvas,
+  Circle,
+  Group,
+  RoundedRect,
+  Shadow,
+  rect,
+  rrect,
+} from '@shopify/react-native-skia';
+
+import {
+  Easing,
+  interpolate,
+  runOnJS,
+  useDerivedValue,
+  useSharedValue,
+  withSpring,
+  withTiming,
+} from 'react-native-reanimated';
+
+import {
+  Gesture,
+  GestureDetector,
+} from 'react-native-gesture-handler';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface DotSliderColors {
+  /** Background colour of the pill track. @default '#dbeafe' */
+  track?: string;
+  /** Colour of the progress fill (left of thumb). @default '#bfdbfe' */
+  fill?: string;
+  /** Active dot colour (left of / at thumb). @default '#3b82f6' */
+  dotActive?: string;
+  /** Inactive dot colour (right of thumb). @default '#93c5fd' */
+  dotInactive?: string;
+  /** Thumb colour. @default '#3b82f6' */
+  thumb?: string;
+  /** Thumb shadow colour. @default 'rgba(59,130,246,0.5)' */
+  thumbShadow?: string;
+}
+
+export interface DotSliderProps {
+  /**
+   * Number of selectable dot positions.
+   * Must be >= 2. Odd values place a dot at the exact centre.
+   * @default 11
+   */
+  dotCount?: number;
+
+  /**
+   * Zero-based index of the initially selected dot.
+   * Clamped to [0, dotCount - 1].
+   * @default Math.floor(dotCount / 2)
+   */
+  defaultIndex?: number;
+
+  /**
+   * Width of the slider track in dp.
+   * Defaults to screen width minus 64 dp of horizontal padding.
+   */
+  width?: number;
+
+  /** Height of the pill track in dp. @default 56 */
+  trackHeight?: number;
+
+  /**
+   * Corner radius of the track.
+   * @default trackHeight / 2  (full pill / stadium shape)
+   */
+  trackRadius?: number;
+
+  /**
+   * Radius of each dot in dp.
+   * The active dot pulses up to 1.45× this value.
+   * @default 3.5
+   */
+  dotRadius?: number;
+
+  /**
+   * Width of the thumb pill in dp.
+   * @default 10
+   */
+  thumbWidth?: number;
+
+  /**
+   * Height of the thumb pill in dp.
+   * Defaults to 57 % of trackHeight.
+   */
+  thumbHeight?: number;
+
+  /**
+   * Show the gloss sheen overlay on the thumb.
+   * @default true
+   */
+  showThumbGloss?: boolean;
+
+  /**
+   * Extra space (in dp) between the track's left edge and the first dot.
+   * Defaults to the track corner radius so the first dot sits visually
+   * inside the pill.
+   */
+  dotPaddingStart?: number;
+
+  /**
+   * Extra space (in dp) between the last dot and the track's right edge.
+   * Defaults to the track corner radius so the last dot sits visually
+   * inside the pill.
+   */
+  dotPaddingEnd?: number;
+
+  /** Colour overrides — any unset key falls back to its default. */
+  colors?: DotSliderColors;
+
+  /**
+   * Called whenever the selected dot index changes (0-based).
+   * Fired on gesture end after the spring snap target is determined.
+   */
+  onValueChange?: (index: number) => void;
+}
+
+// ─── SliderDot (internal sub-component) ──────────────────────────────────────
+
+interface SliderDotProps {
+  cx: number;
+  cy: number;
+  dotStep: number;
+  dotRadius: number;
+  thumbX: ReturnType<typeof useSharedValue<number>>;
+  colorActive: string;
+  colorInactive: string;
+}
+
+function SliderDot({
+  cx,
+  cy,
+  dotStep,
+  dotRadius,
+  thumbX,
+  colorActive,
+  colorInactive,
+}: SliderDotProps) {
+  const color = useDerivedValue(() =>
+    cx <= thumbX.value ? colorActive : colorInactive,
+  );
+
+  const r = useDerivedValue(() => {
+    const dist = Math.abs(cx - thumbX.value);
+    const pulse = interpolate(dist, [0, dotStep], [1.3, 1.0], 'clamp');
+    return dotRadius * pulse;
+  });
+
+  return <Circle cx={cx} cy={cy} r={r} color={color} />;
+}
+
+// ─── DotSlider ────────────────────────────────────────────────────────────────
+
+export function DotSlider({
+  dotCount        = 11,
+  defaultIndex,
+  width,
+  trackHeight     = 56,
+  trackRadius,
+  dotRadius       = 3.5,
+  thumbWidth,
+  thumbHeight,
+  showThumbGloss  = true,
+  dotPaddingStart,
+  dotPaddingEnd,
+  colors          = {},
+  onValueChange,
+}: DotSliderProps) {
+  // ── Layout ─────────────────────────────────────────────────────────────────
+
+  const { width: SW } = Dimensions.get('window');
+  const TRACK_W  = width  ?? SW - 64;
+  const TRACK_H  = trackHeight;
+  const TRACK_R  = trackRadius ?? TRACK_H / 2;
+  const CANVAS_H = TRACK_H + 32;
+  const CY       = CANVAS_H / 2;
+
+  const THUMB_W  = thumbWidth  ?? 7;
+  const THUMB_H  = thumbHeight ?? Math.round(TRACK_H * 0.62);
+  const THUMB_R  = THUMB_W / 2;
+
+  const PAD_START = dotPaddingStart ?? TRACK_R;
+  const PAD_END   = dotPaddingEnd   ?? TRACK_R;
+  const N        = Math.max(2, dotCount);
+  const DOT_AREA = TRACK_W - PAD_START - PAD_END;
+  const DOT_STEP = DOT_AREA / (N - 1);
+  const DOT_XS   = Array.from({ length: N }, (_, i) => PAD_START + i * DOT_STEP);
+
+  const THUMB_MIN = DOT_XS[0];
+  const THUMB_MAX = DOT_XS[N - 1];
+
+  const initIdx  = defaultIndex !== undefined
+    ? Math.max(0, Math.min(N - 1, defaultIndex))
+    : Math.floor(N / 2);
+  const INIT_X   = DOT_XS[initIdx];
+
+  // ── Colours ────────────────────────────────────────────────────────────────
+
+  const C = {
+    track:        colors.track        ?? '#dbeafe',
+    fill:         colors.fill         ?? '#bfdbfe',
+    dotActive:    colors.dotActive    ?? '#3b82f6',
+    dotInactive:  colors.dotInactive  ?? '#93c5fd',
+    thumb:        colors.thumb        ?? '#3b82f6',
+    thumbShadow:  colors.thumbShadow  ?? 'rgba(59,130,246,0.5)',
+  };
+
+  // Pill clip path (keeps progress fill inside the track boundary)
+  const pillClip = rrect(rect(0, CY - TRACK_H / 2, TRACK_W, TRACK_H), TRACK_R, TRACK_R);
+
+  // ── Shared values ──────────────────────────────────────────────────────────
+
+  const thumbX   = useSharedValue(INIT_X);
+  const dragging = useSharedValue(0);
+  const startX   = useSharedValue(INIT_X);
+
+  // ── Derived values ─────────────────────────────────────────────────────────
+
+  const thumbScaleY = useDerivedValue(() =>
+    interpolate(dragging.value, [0, 1], [1.0, 1.08]),
+  );
+  const thumbScaleX = useDerivedValue(() =>
+    interpolate(dragging.value, [0, 1], [1.0, 0.88]),
+  );
+
+  const thumbTransform = useDerivedValue(() => [
+    { translateX:  thumbX.value },
+    { translateY:  CY },
+    { scaleX:      thumbScaleX.value },
+    { scaleY:      thumbScaleY.value },
+    { translateX: -thumbX.value },
+    { translateY: -CY },
+  ]);
+
+  const progressW = useDerivedValue(() =>
+    Math.min(thumbX.value + THUMB_W / 2 + DOT_STEP / 2, TRACK_W + TRACK_R),
+  );
+
+  const thumbRectX  = useDerivedValue(() => thumbX.value - THUMB_W / 2);
+  const thumbRectY  = useDerivedValue(() => CY - THUMB_H / 2);
+  const shadowBlur  = useDerivedValue(() =>
+    interpolate(dragging.value, [0, 1], [3, 10]),
+  );
+
+  // ── Snap helper (worklet) ──────────────────────────────────────────────────
+
+  const snapNearest = (x: number): number => {
+    'worklet';
+    let best = DOT_XS[0];
+    let bestD = Math.abs(x - best);
+    for (let i = 1; i < DOT_XS.length; i++) {
+      const d = Math.abs(x - DOT_XS[i]);
+      if (d < bestD) { bestD = d; best = DOT_XS[i]; }
+    }
+    return best;
+  };
+
+  const notifyChange = (snappedX: number) => {
+    const idx = DOT_XS.findIndex(x => Math.abs(x - snappedX) < 0.5);
+    if (idx !== -1) onValueChange?.(idx);
+  };
+
+  // ── Gesture ────────────────────────────────────────────────────────────────
+
+  const pan = Gesture.Pan()
+    .minDistance(0)
+    .onBegin(() => {
+      'worklet';
+      startX.value   = thumbX.value;
+      dragging.value = withTiming(1, { duration: 100, easing: Easing.out(Easing.quad) });
+    })
+    .onUpdate((e: { translationX: number }) => {
+      'worklet';
+      thumbX.value = Math.max(THUMB_MIN, Math.min(THUMB_MAX, startX.value + e.translationX));
+    })
+    .onEnd(() => {
+      'worklet';
+      dragging.value = withTiming(0, { duration: 200 });
+      const nearest  = snapNearest(thumbX.value);
+      thumbX.value   = withSpring(nearest, { damping: 28, stiffness: 320, mass: 0.5 });
+      runOnJS(notifyChange)(nearest);
+    });
+
+  const tap = Gesture.Tap()
+    .onEnd((e: { x: number }) => {
+      'worklet';
+      const nearest  = snapNearest(e.x);
+      dragging.value = withTiming(1, { duration: 80 });
+      thumbX.value   = withSpring(
+        nearest,
+        { damping: 28, stiffness: 320, mass: 0.5 },
+        () => { dragging.value = withTiming(0, { duration: 200 }); },
+      );
+      runOnJS(notifyChange)(nearest);
+    });
+
+  const gesture = Gesture.Race(tap, pan);
+
+  // ── Render ─────────────────────────────────────────────────────────────────
+
+  return (
+    <GestureDetector gesture={gesture}>
+      <View style={styles.wrap}>
+        <Canvas style={{ width: TRACK_W, height: CANVAS_H }}>
+
+            {/* Track background with inset shadow */}
+            <RoundedRect
+              x={0} y={CY - TRACK_H / 2}
+              width={TRACK_W} height={TRACK_H}
+              r={TRACK_R} color={C.track}
+            >
+              <Shadow dx={0} dy={1} blur={3} color="rgba(0,0,0,0.08)" inner />
+            </RoundedRect>
+
+            {/* Progress fill — clipped to pill */}
+            <Group clip={pillClip}>
+              <RoundedRect
+                x={0} y={CY - TRACK_H / 2}
+                width={progressW} height={TRACK_H}
+                r={TRACK_R} color={C.fill}
+              />
+            </Group>
+
+            {/* Dots */}
+            {DOT_XS.map(cx => (
+              <SliderDot
+                key={cx}
+                cx={cx}
+                cy={CY}
+                dotStep={DOT_STEP}
+                dotRadius={dotRadius}
+                thumbX={thumbX}
+                colorActive={C.dotActive}
+                colorInactive={C.dotInactive}
+              />
+            ))}
+
+            {/* Thumb */}
+            <Group transform={thumbTransform}>
+              {/* Shadow layer */}
+              <RoundedRect
+                x={thumbRectX} y={thumbRectY}
+                width={THUMB_W} height={THUMB_H}
+                r={THUMB_R} color="transparent"
+              >
+                <Shadow dx={0} dy={1} blur={shadowBlur} color={C.thumbShadow} />
+              </RoundedRect>
+              {/* Body */}
+              <RoundedRect
+                x={thumbRectX} y={thumbRectY}
+                width={THUMB_W} height={THUMB_H}
+                r={THUMB_R} color={C.thumb}
+              />
+              {/* Gloss — thin top-edge strip only */}
+              {showThumbGloss && (
+                <RoundedRect
+                  x={thumbRectX} y={thumbRectY}
+                  width={THUMB_W} height={THUMB_H * 0.28}
+                  r={THUMB_R} color="rgba(255,255,255,0.12)"
+                />
+              )}
+            </Group>
+
+        </Canvas>
+      </View>
+    </GestureDetector>
+  );
+}
+
+// ─── Styles ───────────────────────────────────────────────────────────────────
+
+const styles = StyleSheet.create({
+  wrap: {
+    alignItems: 'center',
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 1 },
+    shadowOpacity: 0.06,
+    shadowRadius: 4,
+    elevation: 2,
+  },
+});

package/src/index.ts

@@ -0,0 +1,2 @@
+export { DotSlider } from './DotSlider';
+export type { DotSliderProps, DotSliderColors } from './DotSlider';