react-native-reanimated-dnd

React Native Reanimated DnD 🎯

https://github.com/user-attachments/assets/023c0a9c-194a-45a9-bb88-ac8f16f5ffd5

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

1. Install Expo Go on your phone (SDK 55)
2. Scan the QR code with your camera
3. 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

https://github.com/user-attachments/assets/6493c05f-571c-416d-b81d-90bee98738b4

Features: Auto-scrolling • Drag handles • Smooth transitions

⇌ Horizontal Sortable

Reorderable horizontal scrolling list

https://github.com/user-attachments/assets/909c687e-146d-4233-a6e9-4bc3e7b69a35

Features: Horizontal scroll • Handle & full item modes

🔲 Grid Sortable

2D grid reordering with insert & swap

https://github.com/user-attachments/assets/9647af01-098c-485f-92ba-cfc39d1bba0c

Features: Grid layout • Insert & swap modes

↕ Dynamic Heights

Sortable list with variable item heights

https://github.com/user-attachments/assets/b53078ca-51ab-4675-9389-e8fe69492370

Features: Variable heights • Expand/collapse • Auto-scroll

🎯 Basic Drag & Drop

Drag items to drop zones

https://github.com/user-attachments/assets/05859d25-6749-41b7-ae7e-cad5f864a268

Features: Drop zones • Pre-drag delay • Visual feedback

🎭 Drag Handles

Dedicated regions for drag control

https://github.com/user-attachments/assets/f8be7bea-0f24-4446-83be-06ede43fa02a

Features: Full handle • Bar handle • Header handle

✨ Active Drop Styles

Visual hover effects on drop zones

https://github.com/user-attachments/assets/d4124110-6eb7-4a15-8f97-3e58b392d62e

Feedback: Pulse effect • Glow effect • Hover states

📐 Alignment & Offset

Precise drop positioning with offsets

https://github.com/user-attachments/assets/07fd39d0-a0d8-471c-86be-b73d70027163

Features: 9-point alignment • X/Y offset controls

📦 Bounded Dragging

Constrain movement within boundaries

https://github.com/user-attachments/assets/ce43a226-ec42-49c1-b528-df6599d294e1

Constraints: Container bounds • Axis-locked • Custom limits

🎪 Collision Detection

Center, intersect & contain algorithms

https://github.com/user-attachments/assets/1ac1860a-acc1-469a-ae3e-644a22393b86

Algorithms: Center • Intersect • Contain

🗺️ Dropped Items Map

Track items across multiple zones

https://github.com/user-attachments/assets/e4effc88-7161-4c5c-af6e-c06152cfbd09

Features: Multi-zone tracking • Real-time mapping

⚡ Drag State

State lifecycle tracking & callbacks

https://github.com/user-attachments/assets/bceb9e7c-8f29-4630-81b0-945a7bcf29c5

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