React Native Reanimated DnD 🎯

launch-video.mp4

A drag-and-drop library that finally works on React Native ✨

Powerful, performant, and built for the modern React Native developer

---

🚀 Why This Library?

After countless attempts with drag-and-drop solutions that don't work or are simply outdated, this is something that finally works. And it is not just another DnD library, but a complete ecosystem built from the ground up for React Native, offering a best-in-class developer experience and production-ready performance.

Highly feature-packed with every interaction pattern you'll ever need, yet simple enough to get started in minutes. Built for developers who demand both power and simplicity.

✨ Features

• 🚀 High Performance - Built with Reanimated 4 and Worklets for buttery-smooth 60fps animations
• 🏗️ New Architecture Ready - Built for the modern React Native architecture used by Expo SDK 55+
• 📦 Expo Compatible - Tested against Expo SDK 55 and React Native 0.83
• 🪶 Tiny Bundle Size - Only 70kb unpacked size, won't bloat your app
• 🎯 Flexible API - From simple drag-and-drop to complex sortable lists
• 📱 React Native First - Designed specifically for mobile, not ported from web
• 🔧 TypeScript Ready - Full type safety with comprehensive definitions
• 🎨 Infinitely Customizable - Every animation, behavior, and style is configurable
• 📦 Complete Component Suite - Draggable, Droppable, Sortable, and more
• 🎪 Smart Collision Detection - Multiple algorithms (center, intersect, contain)
• 📜 Vertical & Horizontal Sortable Lists - Drag and drop to sort lists in any direction with automatic scrolling
• 🔲 Sortable Grids - 2D grid drag-and-drop with flexible layouts, insert and swap modes
• ↕ Dynamic Heights - Sortable lists with variable item heights
• ⚡ FlatList Performance - Optional FlatList rendering for large datasets with virtualization
• 🎭 Drag Handles - Precise control with dedicated drag areas
• 🎬 Custom Animations - Spring, timing, or bring your own animation functions
• 📐 Pixel-Perfect Positioning - 9-point alignment system with custom offsets
• 📦 Boundary Constraints - Keep draggables within specific areas
• ⚡ State Management - Complete lifecycle tracking and callbacks
• 🎯 Developer Experience - Intuitive APIs, helpful warnings, and extensive examples

📱 Interactive Examples

See it in action! A comprehensive example app with 18 interactive demos showcasing every feature and use case.

🎮 Try the Example App

📱 Scan & Play Scan with Expo Go to try the demo instantly

🚀 Quick Start Install Expo Go on your phone (SDK 55) Scan the QR code with your camera Explore 18 interactive examples! Or browse the code: 📂 View Example App →

📚 Complete Documentation

Comprehensive guides, API reference, and interactive examples

The example app includes:

• 🎵 Sortable Music Queue - Complete list reordering with drag handles
• ⇌ Horizontal Sortable - Reorderable horizontal scrolling list
• 🔲 Sortable Grid - 2D grid reordering with insert/swap modes
• ↕ Dynamic Heights - Sortable list with variable item heights
• 🎯 Basic Drag & Drop - Drag items to drop zones with pre-drag delay
• 🎪 Drag Handles - Dedicated drag regions for precise control
• 🎬 Custom Animations - Spring, timing, bounce & easing curves
• ✨ Active Drop Styles - Visual feedback on hover
• 📐 Alignment & Offset - Precise drop positioning with offsets
• 📦 Boundary Constraints - Axis-locked and bounded dragging
• 🎯 Collision Detection - Center, intersect & contain algorithms
• 🗺️ Dropped Items Map - Track items across multiple zones
• ⚡ Drag State - State enum & onStateChange lifecycle
• ⚙️ Custom Draggable - useDraggable hook implementation

🎬 Demo Showcase

🎵 Sortable Music Queue Vertical list reordering with drag handles sortable-music-queue.mp4 Features: Auto-scrolling • Drag handles • Smooth transitions	⇌ Horizontal Sortable Reorderable horizontal scrolling list horizontal-sortable.mp4 Features: Horizontal scroll • Handle & full item modes	🔲 Grid Sortable 2D grid reordering with insert & swap grid-sortable.mp4 Features: Grid layout • Insert & swap modes
↕ Dynamic Heights Sortable list with variable item heights dynamic-heights.mp4 Features: Variable heights • Expand/collapse • Auto-scroll	🎯 Basic Drag & Drop Drag items to drop zones basic-drag-drop.mp4 Features: Drop zones • Pre-drag delay • Visual feedback	🎭 Drag Handles Dedicated regions for drag control drag-handles.mp4 Features: Full handle • Bar handle • Header handle
✨ Active Drop Styles Visual hover effects on drop zones active-drop-styles.mp4 Feedback: Pulse effect • Glow effect • Hover states	📐 Alignment & Offset Precise drop positioning with offsets alignment-offset.mp4 Features: 9-point alignment • X/Y offset controls	📦 Bounded Dragging Constrain movement within boundaries bounded-dragging.mp4 Constraints: Container bounds • Axis-locked • Custom limits
🎪 Collision Detection Center, intersect & contain algorithms collision-detection.mp4 Algorithms: Center • Intersect • Contain	🗺️ Dropped Items Map Track items across multiple zones dropped-items-map.mp4 Features: Multi-zone tracking • Real-time mapping	⚡ Drag State State lifecycle tracking & callbacks drag-state.mp4 States: Idle • Dragging • Dropped

🚀 Installation

npm install react-native-reanimated-dnd

Peer Dependencies

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

Follow the setup guides:

• React Native Worklets
• React Native Reanimated
• React Native Gesture Handler

Make sure your Babel config uses "react-native-worklets/plugin" as the last plugin and that your app is running on the New Architecture, which is required by Reanimated 4.

📋 Requirements

Data Structure

All items in your data array MUST have an id property of type string:

interface YourDataType {
  id: string; // Required!
  // ... your other properties
}

This is essential for the library to track items during reordering.

Example:

// ✅ Good - Each item has a unique string id
const tasks = [
  { id: "1", title: "Learn React Native", completed: false },
  { id: "2", title: "Build an app", completed: false },
  { id: "3", title: "Deploy to store", completed: true },
];

// ❌ Bad - Missing id properties
const badTasks = [{ title: "Task 1" }, { title: "Task 2" }];

// ❌ Bad - Non-string ids
const badTasksWithNumbers = [
  { id: 1, title: "Task 1" },
  { id: 2, title: "Task 2" },
];

The library includes runtime validation in development mode that will warn you if items are missing valid ID properties.

State Management Guidelines

IMPORTANT: Sortable components maintain their own internal state for optimal performance and animation consistency.

Do NOT Do This

• Never update external state (arrays, Redux, Zustand, etc.) directly in onMove callbacks
• Never call setItems(), setTasks(), or similar functions during drag operations
• Never manually splice or reorder external arrays in response to drag events

Correct Approach

• Use onMove for logging, analytics, or side effects only
• Use onDrop with allPositions parameter for read-only position tracking
• Let sortable components handle their internal reordering automatically
• Use external state only for the initial data and for non-reordering updates

Future Features

Programmatic list operations (add, update, delete, reorder items) that work correctly with internal state management will be added in upcoming releases. This will provide safe methods to modify sortable lists externally.

🏃‍♂️ Quick Start

Basic Drag & Drop

import { GestureHandlerRootView } from "react-native-gesture-handler";
import { Draggable, Droppable, DropProvider } from "react-native-reanimated-dnd";

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <DropProvider>
        <Droppable onDrop={(data) => console.log("Dropped:", data)}>
          <View style={styles.dropZone}>
            <Text>Drop here</Text>
          </View>
        </Droppable>

        <Draggable data={{ id: "1", title: "Drag me!" }}>
          <View style={styles.item}>
            <Text>Drag me around!</Text>
          </View>
        </Draggable>
      </DropProvider>
    </GestureHandlerRootView>
  );
}

Sortable List

import { Sortable, SortableItem, SortableRenderItemProps } from "react-native-reanimated-dnd";

const tasks = [
  { id: "1", title: "Learn React Native" },
  { id: "2", title: "Build an app" },
  { id: "3", title: "Deploy to store" },
];

function TaskList() {
  const renderItem = useCallback((props: SortableRenderItemProps<typeof tasks[0]>) => {
    const { item, id, ...rest } = props;
    return (
      <SortableItem key={id} id={id} data={item} {...rest}>
        <View style={styles.task}>
          <Text>{item.title}</Text>
          <SortableItem.Handle>
            <Text>⋮⋮</Text>
          </SortableItem.Handle>
        </View>
      </SortableItem>
    );
  }, []);

  return <Sortable data={tasks} renderItem={renderItem} itemHeight={60} />;
}

Sortable Grid

import { SortableGrid, SortableGridItem } from "react-native-reanimated-dnd";

const apps = [
  { id: "1", label: "Photos" },
  { id: "2", label: "Music" },
  { id: "3", label: "Settings" },
  { id: "4", label: "Mail" },
];

function AppGrid() {
  const renderItem = useCallback((props) => {
    const { item, id, ...rest } = props;
    return (
      <SortableGridItem key={id} id={id} {...rest}>
        <View style={styles.gridItem}>
          <Text>{item.label}</Text>
        </View>
      </SortableGridItem>
    );
  }, []);

  return (
    <SortableGrid
      data={apps}
      renderItem={renderItem}
      dimensions={{ columns: 4, itemWidth: 80, itemHeight: 80, rowGap: 12, columnGap: 12 }}
    />
  );
}

More examples: Quick Start Guide · Sortable Lists · Sortable Grids · All Examples

📚 Documentation

Visit reanimated-dnd-docs.vercel.app for the full documentation:

• Getting Started — Installation, setup, and quick start
• Components — Draggable, Droppable, Sortable, SortableGrid, SortableItem
• Hooks — useDraggable, useDroppable, useSortable, useGridSortable
• Guides — Animations, collision algorithms, performance, accessibility
• Examples — Interactive code examples for every feature
• API Reference — Complete types, enums, and utilities

🏃‍♂️ Running the Example App

1. Clone the repository:

git clone https://github.com/entropyconquers/react-native-reanimated-dnd.git
cd react-native-reanimated-dnd

2. Install dependencies (uses npm workspaces):

npm install

3. Run the example app:

# iOS
npm run start --workspace example-app
# then press 'i' for iOS or 'a' for Android

# Or run directly:
npx expo run:ios --cwd example-app
npx expo run:android --cwd example-app

Note: Reanimated 4 requires the New Architecture, so you must use a development build (npx expo run:ios / npx expo run:android), not Expo Go.

The example app includes all 18 interactive examples showcasing every feature of the library.

🗺️ Project Roadmap

I am constantly working to improve React Native Reanimated DnD. Here's what's coming next:

✅ v2.0.0 (Current)

Reanimated 4 + Worklets Migration

• 🚀 Reanimated 4 & Worklets - Migrated from Reanimated 3 to Reanimated 4 with react-native-worklets
• 🏗️ New Architecture - Built for React Native's New Architecture (required by Reanimated 4)
• 📦 Expo SDK 55 - Tested and compatible with Expo SDK 55 and React Native 0.83
• 🔧 Handle Registration - Replaced tree-walking handle detection with a registration pattern
• ⚡ Improved Scheduling - Uses scheduleOnRN/scheduleOnUI for better worklet-to-JS communication
• 🎯 Pre-drag Delay - New preDragDelay prop for distinguishing taps from drags
• 📐 npm Workspaces - Example app now uses workspace-based development setup
• 🔲 Sortable Grids - 2D grid drag-and-drop with flexible layouts and insert/swap modes
• ↕ Dynamic Heights - Sortable list support for variable item heights

🎯 Next Release

Focus: Enhanced Functionality & New Features

• 🐛 Bug Fixes & Issues Resolution

  • Address existing reported issues
  • Performance optimizations
  • Gesture handling improvements
  • API Improvements

• 🪆 Nested Sortable Lists

  • Multi-level hierarchy support
  • Collapse/expand functionality
  • Parent-child relationship management
  • Tree-like data structure handling

• 📋 Kanban Board Support

  • Cross-list dragging capabilities
  • Multiple column support
  • Inter-list item transfer
  • Board-level state management

💡 Community Requests

Vote on features you'd like to see by raising an issue.

Have an idea? Open a feature request and let me know!

🤖 AI Integration Skill

Speed up development with the official agent skill. It teaches AI coding agents (Claude Code, Codex, Cursor, Gemini CLI, Copilot, and 30+ more) the full API so they generate correct code — no hallucinated props.

# Install via npx skills (auto-detects your agents)
npx skills add entropyconquers/react-native-reanimated-dnd

# Or install globally
npx skills add entropyconquers/react-native-reanimated-dnd -g

Once installed, just describe what you want:

"Add a sortable list where I can reorder items by dragging"

"Create a drag and drop interface with drop zones"

"Make a reorderable 3-column grid"

Your agent will generate complete, working implementations with correct imports, props, and state management.

The skill ships in both .claude/skills/ (Claude Code) and .agents/skills/ (Codex, Cursor, Gemini CLI, Copilot, and others) for universal agent compatibility. See the AI Integration Skill docs for all installation options and the full agent compatibility table.

🤝 Contributing

Contributions are always welcome! We believe in building this library together with the community.

Ways to contribute:

• 🐛 Report bugs and issues
• ✨ Suggest new features
• 🔧 Submit pull requests
• 📚 Improve documentation
• 🧪 Write tests
• 💬 Help others in discussions

Please see our Contributing Guide for detailed information on:

• Setting up the development environment
• Code style guidelines
• Pull request process
• Testing requirements
• Community guidelines

📄 License

MIT © Vishesh Raheja

🙏 Acknowledgments

• Built with React Native Reanimated for smooth 60fps animations
• Gesture handling powered by React Native Gesture Handler
• Inspired by the React ecosystem's drag-and-drop libraries
• Special thanks to the React Native community for feedback and contributions

☕ Support the Project

If this library has helped you build amazing apps, consider supporting its development!



Your support helps maintain and improve this library for the entire React Native community! 🚀

---

Made with ❤️ for the React Native community

⭐ Star on GitHub • 📱 Try the Demo • 📖 Documentation