react-native-reanimated-dnd

v2.0.0

Published

a month ago

A powerful drag-and-drop library for React Native using Reanimated 4 and Worklets

0High
0Medium
0Low

entropyconquers

react-native drag-and-drop reanimated sortable dnd gesture-handler

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

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

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:

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

Clone the repository:

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

Install dependencies (uses npm workspaces):

npm install

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

🙏 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

Made with ❤️ for the React Native community

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