react-native-scroll-track

✨ A customizable, interactive scroll indicator for React Native. Tap or drag to scroll, with animated thumb and auto-hide behavior.

🚀 Features

• 🧭 Drag or tap the scroll track to jump to content
• 💡 Auto-hide logic with optional persistent mode
• 📏 Dynamic thumb height based on content size
• 🎨 Customizable colors, shadows, sizes
• 🔄 Inverted list support for chat-style interfaces
• ⚡ Optimized performance with native animations
• 🎯 Callback functions for haptic feedback and interaction handling
• ✅ Supports ScrollView, FlatList, SectionList, FlashList, DraggableFlatList, etc.
• 🆕 Ref forwarding support – integrate cleanly with parent gestures and carousels

🧪 Live Demo

Try out the scroll track interactively on Expo Snack: 👉 Open in Snack

📦 Installation

npm install react-native-scroll-track

Peer Dependencies

npm install react-native-reanimated react-native-gesture-handler

Additional Setup

• Ensure react-native-reanimated/plugin is the last plugin in your babel.config.js
• Follow setup guides for:
  • react-native-reanimated
  • react-native-gesture-handler Important: Make sure react-native-reanimated/plugin is the last plugin in your babel.config.js.

⚠️ Required Setup

Critical: You must wrap your app (or at least the component using ScrollableContainer) with GestureHandlerRootView from react-native-gesture-handler. Without this, you'll get the error:

PanGestureHandler must be used as a descendant of GestureHandlerRootView

Wrap your app with GestureHandlerRootView:

import { GestureHandlerRootView } from 'react-native-gesture-handler';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <YourComponent />
    </GestureHandlerRootView>
  );
}

✅ Recommended Usage (Hook API)

import { useScrollTrack } from 'react-native-scroll-track';

const MyScreen = () => {

    // These are optional, displayed for illustrative purposes.
    const scrollTrackOptions: ScrollTrackOptions = {
        inverted: false,
        styling: {
            thumbColor: 'white',
            trackColor: 'steelblue',
        },
        onPressStart: () => console.log("on press start event"),
        onPressEnd: () => console.log("on press end event"),
    };

    const { scrollProps, ScrollTrack } = useScrollTrack(scrollTrackOptions);

  return (
    <View style={{ flex: 1 }}>
      <FlatList {...scrollProps} data={data} renderItem={renderItem} />
      {ScrollTrack}
    </View>
  );
};

❌ Deprecated: ScrollableContainer

The ScrollableContainer component is deprecated and will be removed in the next major version. Use useScrollTrack instead.

<ScrollableContainer>
  {({ scrollRef, onScroll, ...props }) => (
    <FlatList
      ref={scrollRef}
      onScroll={onScroll}
      {...props}
      data={data}
      renderItem={renderItem}
    />
  )}
</ScrollableContainer>

🎛️ useScrollTrack Hook Options

| Option | Type | Default | Description | |----------------------------|------------|-------------|-------------| | alwaysVisible | boolean | false | Prevents auto-hide behavior | | disableGestures | boolean | false | Disables tap/drag on scrollbar | | fadeOutDelay | number | 1000 | Delay before fading track (ms) | | hitSlop | number | 36 | Increases the touchable area of the thumb| | inverted | boolean | false | Reverses track direction (chat-style) | | minScrollDistanceToShow | number | 20 | Min scrollable height before track appears | | scrollThrottle | number | 1 | Throttle for scroll events | | styling | object | {} | Styling for track and thumb | | onPressStart | function | | Callback when interaction starts | | onPressEnd | function | | Callback when interaction ends | | onDragStart | function | | Callback when thumb drag starts | | onDragEnd | function | | Callback when thumb drag ends | | externalRef | ref | | Supply your own list ref (FlatList, ScrollView, FlashList) |

styling Options

| Key | Type | Description | |--------------------|----------|-------------| | thumbColor | string | Thumb color | | trackColor | string | Track background color | | trackVisible | boolean| Show/hide track background | | trackOpacity | number | Opacity of the track | | thumbOpacity | number | Opacity of the thumb | | trackWidth | number | Width of the track | | thumbHeight | number | Fixed height for the thumb | | thumbBorderRadius| number | Border radius of the thumb | | thumbShadow | object | Shadow style for thumb | | zIndex | number | z-index of the track |

thumbShadow Options

| Key | Type | Description | |---------|----------|-------------| | color| string | Shadow color | | opacity | number | Shadow opacity | | radius | number | Blur radius | | offset | object | { width, height } offset |

Inverted Scroll Behavior

When inverted is set to true, the scroll track behavior is flipped:

• Tapping at the bottom of the track scrolls to the beginning of the content (position 0)
• Tapping at the top of the track scrolls to the end of the content
• The thumb position is also inverted to match this behavior

This is useful when working with inverted FlatLists or when you want the scroll track to behave in the opposite direction from the default.

Note: The inverted prop has currently only been tested with FlatLists. Behavior with other scrollable components may vary.

    // These are optional, displayed for illustrative purposes.
    const scrollTrackOptions: ScrollTrackOptions = {
        inverted: true,
    };

    const { scrollProps, ScrollTrack } = useScrollTrack(scrollTrackOptions);

    return (
        <View style={{ flex: 1 }}>
            <FlatList {...scrollProps} data={data} renderItem={renderItem} />
            {ScrollTrack}
        </View>
    );
};

🎯 Haptic Feedback Example

With Haptic Feedback

The onPressStart and onPressEnd callbacks are perfect for implementing haptic feedback to provide tactile responses when users interact with the scroll track. You can use packages like react-native-haptic-feedback to add native haptic responses:

import ReactNativeHapticFeedback from "react-native-haptic-feedback";
import { Platform, Vibration } from "react-native";

// Optional: Configure haptic feedback options
const hapticOptions = {
  enableVibrateFallback: true,
  ignoreAndroidSystemSettings: false,
};

// Custom vibration patterns for Android
const ANDROID_VIBRATION_PATTERNS: Record<HapticType, number[]> = {
    impactLight: [0, 5], // 5ms vibration - extremely subtle
    impactMedium: [0, 10], // 10ms vibration - very light
    impactHeavy: [0, 20], // 20ms vibration - medium
    notificationSuccess: [0, 20, 50, 20], // Success pattern
    notificationWarning: [0, 30, 50, 30], // Warning pattern
    notificationError: [0, 40, 50, 40], // Error pattern
    selection: [0, 5], // Selection - extra light
};

// Define haptic types for different interactions
export type HapticType =
    | "impactLight" // Light tap, for subtle UI interactions
    | "impactMedium" // Medium tap, for more significant actions
    | "impactHeavy" // Strong tap, for important or destructive actions
    | "notificationSuccess" // Success notification pattern
    | "notificationWarning" // Warning notification pattern
    | "notificationError" // Error notification pattern
    | "selection"; // Selection feedback pattern

/**
 * Triggers haptic feedback using native APIs when available
 * @param type The type of haptic feedback to trigger
 * @param options Optional configuration for the haptic feedback
 */
export const triggerHapticFeedback = (
    type: HapticType = "impactLight",
    options = hapticOptions
) => {
    try {
        if (Platform.OS === "android") {
            // Use custom vibration patterns for Android
            const pattern = ANDROID_VIBRATION_PATTERNS[type];
            Vibration.vibrate(pattern, false);
        } else {
            // Use standard haptic feedback for iOS
            ReactNativeHapticFeedback.trigger(type, {
                ...options,
                ignoreAndroidSystemSettings: false,
            });
        }
    } catch (error) {
        console.warn("Haptic feedback not available:", error);
    }
};

// Helper functions for common haptic patterns
export const HapticFeedback = {
    light: () => triggerHapticFeedback("impactLight"),
    medium: () => triggerHapticFeedback("impactMedium"),
    heavy: () => triggerHapticFeedback("impactHeavy"),
    success: () => triggerHapticFeedback("notificationSuccess"),
    warning: () => triggerHapticFeedback("notificationWarning"),
    error: () => triggerHapticFeedback("notificationError"),
    selection: () => triggerHapticFeedback("selection"),
};

import ReactNativeHapticFeedback from "react-native-haptic-feedback";
import { useScrollTrack } from "react-native-scroll-track";

const MyScreen = () => {
  const { scrollProps, ScrollTrack } = useScrollTrack({
    styling: { thumbColor: '#007AFF' },
    onPressStart: () => triggerHapticFeedback("impactLight"),
    onPressEnd: () => triggerHapticFeedback("impactMedium"),
  });

  return (
    <View style={{ flex: 1 }}>
      <FlatList {...scrollProps} data={myData} renderItem={renderItem} />
      {ScrollTrack}
    </View>
  );
};

Installation:

npm install react-native-haptic-feedback

Note: Haptic feedback requires additional platform-specific setup. Follow the installation guide for react-native-haptic-feedback to ensure proper functionality across iOS and Android.

🚨 Troubleshooting

Common Issues

"PanGestureHandler must be used as a descendant of GestureHandlerRootView"

Make sure you've wrapped your app with GestureHandlerRootView as shown in the setup section.

Scroll track not appearing

Check that your content height is greater than the container height. The scroll track only appears when content is scrollable.

Jerky scrolling

Ensure react-native-reanimated/plugin is the last plugin in your babel.config.js.

TypeScript errors

The package includes TypeScript definitions. Make sure your TypeScript version is compatible with React Native.

Haptic feedback not working

• Ensure you've installed react-native-haptic-feedback correctly
• Check that haptic feedback is enabled in device settings
• Test on a physical device (haptic feedback doesn't work in simulators)

Performance Optimization

The component is optimized for performance with:

• Native animations using react-native-reanimated
• Efficient gesture handling with react-native-gesture-handler
• Minimal re-renders through memoization
• Smooth scrolling with throttled updates

🛠️ Compatibility

• React Native: 0.60+
• Expo: SDK 49+
• iOS: 10.0+
• Android: API 21+

📄 License

MIT License

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

💖 Support

If you like this package:

• ⭐ Starring the repository on GitHub
• 📦 Sharing the package with your React Native community

Built with ❤️ for the React Native community