react-native-reanimated-drag-list

A high-performance draggable list component for React Native, built with Reanimated 4 and Gesture Handler. Runs entirely on the UI thread for buttery smooth 60fps animations.

Features

• 🚀 UI Thread Performance - All animations run on the UI thread via Reanimated
• 📜 Progressive Auto-scroll - Automatically scrolls when dragging near edges with exponential speed curve
• ⏱️ Long Press Activation - Hold to drag, tap to scroll - configurable delay
• 🎯 Smooth Animations - Spring animations for natural feeling interactions
• 📱 Fabric Ready - Built for the new React Native architecture
• 🪆 Nestable Lists - Multiple draggable lists within a single scrollable container
• 📏 Dynamic Heights - Support for items with variable heights
• 🚫 Drag Disabled Zones - Exclude interactive elements from triggering drag

Requirements

• React Native 0.71+
• react-native-reanimated 4.x
• react-native-gesture-handler 2.x
• react-native-worklets

Installation

npm install react-native-reanimated-drag-list

Make sure you have the peer dependencies installed:

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

Usage

Basic Usage

import { DraggableList, type RenderItemParams } from 'react-native-reanimated-drag-list';
import { View, Text, StyleSheet } from 'react-native';

type Item = {
  id: string;
  title: string;
};

const data: Item[] = [
  { id: '1', title: 'Item 1' },
  { id: '2', title: 'Item 2' },
  { id: '3', title: 'Item 3' },
  // ... more items
];

function App() {
  const [items, setItems] = useState(data);

  const renderItem = ({ item, index }: RenderItemParams<Item>) => (
    <View style={styles.item}>
      <Text>{item.title}</Text>
    </View>
  );

  return (
    <DraggableList
      data={items}
      itemHeight={60}
      renderItem={renderItem}
      keyExtractor={(item) => item.id}
      onDragEnd={setItems}
      style={styles.list}
    />
  );
}

const styles = StyleSheet.create({
  list: {
    flex: 1,
  },
  item: {
    height: 60,
    backgroundColor: '#fff',
    justifyContent: 'center',
    paddingHorizontal: 16,
    borderBottomWidth: 1,
    borderBottomColor: '#eee',
  },
});

Nesting Multiple Draggable Lists

You can render multiple NestableDraggableFlatList components within a single scrollable parent using NestableScrollContainer. This is useful when you have multiple categories or sections that each need their own reorderable list.

Note: When using NestableDraggableFlatList, React Native warnings about nested VirtualizedLists are automatically suppressed.

import {
  NestableScrollContainer,
  NestableDraggableFlatList,
} from 'react-native-reanimated-drag-list';

function App() {
  const [data1, setData1] = useState(initialData1);
  const [data2, setData2] = useState(initialData2);
  const [data3, setData3] = useState(initialData3);

  const renderItem = ({ item }) => (
    <View style={styles.item}>
      <Text>{item.label}</Text>
    </View>
  );

  const keyExtractor = (item) => item.id;

  return (
    <NestableScrollContainer style={styles.container}>
      <Text style={styles.header}>Shopping List</Text>
      <NestableDraggableFlatList
        data={data1}
        itemHeight={60}
        renderItem={renderItem}
        keyExtractor={keyExtractor}
        onDragEnd={setData1}
      />

      <Text style={styles.header}>Tasks</Text>
      <NestableDraggableFlatList
        data={data2}
        itemHeight={60}
        renderItem={renderItem}
        keyExtractor={keyExtractor}
        onDragEnd={setData2}
      />

      <Text style={styles.header}>Favorites</Text>
      <NestableDraggableFlatList
        data={data3}
        itemHeight={60}
        renderItem={renderItem}
        keyExtractor={keyExtractor}
        onDragEnd={setData3}
      />
    </NestableScrollContainer>
  );
}

Dynamic Item Heights

NestableDraggableFlatList supports items with variable heights. Simply omit the itemHeight prop and let items measure themselves:

import {
  NestableScrollContainer,
  NestableDraggableFlatList,
} from 'react-native-reanimated-drag-list';

function App() {
  const [items, setItems] = useState(data);

  const renderItem = ({ item }) => (
    <View style={styles.item}>
      <Text style={styles.title}>{item.title}</Text>
      {item.description && (
        <Text style={styles.description}>{item.description}</Text>
      )}
    </View>
  );

  return (
    <NestableScrollContainer style={styles.container}>
      <NestableDraggableFlatList
        data={items}
        // No itemHeight - heights are measured automatically
        estimatedItemHeight={80} // Optional: helps with initial layout
        renderItem={renderItem}
        keyExtractor={(item) => item.id}
        onDragEnd={setItems}
      />
    </NestableScrollContainer>
  );
}

Drag Disabled Zones

Use DragDisabledZone to wrap interactive elements (buttons, inputs, etc.) that should not trigger drag activation:

import {
  NestableScrollContainer,
  NestableDraggableFlatList,
  DragDisabledZone,
} from 'react-native-reanimated-drag-list';

function App() {
  const [items, setItems] = useState(data);

  const renderItem = ({ item }) => (
    <View style={styles.item}>
      <Text>{item.title}</Text>
      <DragDisabledZone>
        <TouchableOpacity 
          style={styles.deleteButton}
          onPress={() => deleteItem(item.id)}
        >
          <Text>Delete</Text>
        </TouchableOpacity>
      </DragDisabledZone>
    </View>
  );

  return (
    <NestableScrollContainer>
      <NestableDraggableFlatList
        data={items}
        itemHeight={60}
        renderItem={renderItem}
        keyExtractor={(item) => item.id}
        onDragEnd={setItems}
      />
    </NestableScrollContainer>
  );
}

API Reference

DraggableList Props

Prop	Type	Required	Default	Description
data	T[]	✅	-	Array of items to render
itemHeight	number	✅	-	Height of each item (must be consistent)
renderItem	(params: RenderItemParams<T>) => ReactNode	✅	-	Function to render each item
keyExtractor	(item: T) => string	✅	-	Function to extract unique key from item
onDragEnd	(data: T[]) => void	✅	-	Callback with reordered data after drag ends
style	ViewStyle	❌	-	Style for the ScrollView container
contentContainerStyle	ViewStyle	❌	-	Style for the content container
dragActivationDelay	number	❌	200	Milliseconds to hold before drag activates

NestableScrollContainer Props

Extends all ScrollView props from react-native-gesture-handler. Supports ref forwarding to access the underlying ScrollView.

Prop	Type	Required	Description
children	ReactNode	✅	Content including NestableDraggableFlatList components
measureKey	number or string	❌	When this value changes, the container re-measures its position on screen. Useful when the container is inside an animated parent like a BottomSheet.
onScroll	ScrollViewProps['onScroll']	❌	Scroll event handler
onScrollBeginDrag	ScrollViewProps['onScrollBeginDrag']	❌	Called when user begins dragging the scroll view
onScrollEndDrag	ScrollViewProps['onScrollEndDrag']	❌	Called when user stops dragging the scroll view
onMomentumScrollEnd	ScrollViewProps['onMomentumScrollEnd']	❌	Called when momentum scroll animation ends

Usage with BottomSheet

When using NestableScrollContainer inside a BottomSheet, pass the bottom sheet's index as measureKey to ensure auto-scroll works correctly when the sheet animates:

import BottomSheet from '@gorhom/bottom-sheet';
import { NestableScrollContainer, NestableDraggableFlatList } from 'react-native-reanimated-drag-list';

function MyComponent() {
  const [bottomSheetIndex, setBottomSheetIndex] = useState(1);

  return (
    <BottomSheet
      index={1}
      snapPoints={['25%', '55%']}
      onChange={setBottomSheetIndex}
    >
      <NestableScrollContainer measureKey={bottomSheetIndex}>
        <NestableDraggableFlatList
          data={data}
          itemHeight={100}
          renderItem={renderItem}
          onDragEnd={handleDragEnd}
          keyExtractor={(item) => item.id}
        />
      </NestableScrollContainer>
    </BottomSheet>
  );
}

NestableDraggableFlatList Props

Prop	Type	Required	Default	Description
data	T[]	✅	-	Array of items to render
itemHeight	number	❌	-	Fixed height for all items. If omitted, heights are measured dynamically.
estimatedItemHeight	number	❌	60	Estimated item height for initial layout (only used when itemHeight is not provided)
renderItem	(params: RenderItemParams<T>) => ReactNode	✅	-	Function to render each item
keyExtractor	(item: T) => string	✅	-	Function to extract unique key from item
onDragEnd	(data: T[]) => void	✅	-	Callback with reordered data after drag ends
style	ViewStyle	❌	-	Style for the list container
contentContainerStyle	ViewStyle	❌	-	Style for the content container
dragActivationDelay	number	❌	200	Milliseconds to hold before drag activates
ListHeaderComponent	ReactNode	❌	-	Component rendered above list items
ListFooterComponent	ReactNode	❌	-	Component rendered below list items
autoScrollThreshold	number	❌	100	Distance from edge (in px) to trigger auto-scroll
autoScrollMaxSpeed	number	❌	12	Maximum auto-scroll speed (px per frame)
autoScrollMinSpeed	number	❌	1	Minimum auto-scroll speed (px per frame)
autoScrollSmoothing	number	❌	0.15	Smoothing factor for velocity transitions (0-1). Lower = smoother.

DragDisabledZone

A wrapper component that prevents drag activation on its children. Use this for buttons, inputs, or other interactive elements within draggable items.

import { DragDisabledZone } from 'react-native-reanimated-drag-list';

<DragDisabledZone>
  <Button onPress={handlePress} title="Click me" />
</DragDisabledZone>

RenderItemParams

type RenderItemParams<T> = {
  item: T;           // The item data
  index: number;     // Current index in the list
  drag: () => void;  // Function to initiate drag (for custom handles)
  isActive: boolean; // Whether this item is being dragged
};

How It Works

1. Long press an item to activate drag mode (default 200ms)
2. Drag the item to reorder - other items animate out of the way
3. Release to drop the item in its new position
4. Scroll normally with quick swipes - dragging only activates on hold

Auto-scroll Behavior

The list automatically scrolls when you drag an item near the top or bottom edges:

• Direction-aware: Only scrolls when you're actively moving toward the edge
• Progressive speed: Uses an exponential curve - gentle near the threshold, rapid at the edge
• Smooth integration: The dragged item follows the scroll seamlessly

License

MIT