npm package: @luudoanh/react-native-reanimated-dnd
Description: A powerful drag-and-drop library for React Native using Reanimated 4 - Updated for compatibility
Author: luudoanh
Latest version: 1.3.0

# React Native Reanimated DnD 🎯

> **🚀 Reanimated v4 Compatible Fork**  
> This is a fork of the original [react-native-reanimated-dnd](https://github.com/entropyconquers/react-native-reanimated-dnd) library, updated for compatibility with React Native Reanimated v4. All features and APIs remain the same, with improved performance and stability.

<p align="center">
  <img src="https://github.com/user-attachments/assets/dba6226e-c407-4a12-9feb-e8f588d6c1e3" alt="React Native Reanimated DnD Demo" style="max-width: 100%; width: 100%;" />
</p>
<div align="center">
  
**A drag-and-drop library that _finally_ works on React Native** ✨

_Powerful, performant, and built for the modern React Native developer_

[![npm version](https://badge.fury.io/js/react-native-reanimated-dnd.svg)](https://badge.fury.io/js/react-native-reanimated-dnd)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![React Native](https://img.shields.io/badge/React%20Native-0.60+-green.svg)](https://reactnative.dev/)

<br />

<a href="https://www.npmjs.com/package/react-native-reanimated-dnd" target="_blank">
  <img src="https://img.shields.io/badge/📦%20View%20on%20NPM-cb3837?style=for-the-badge&logo=npm&logoColor=white&labelColor=1e293b&fontSize=24" alt="NPM Package" height="36"/>
</a>
<a href="https://react-native-reanimated-dnd.netlify.app/" target="_blank">
  <img src="https://img.shields.io/badge/📖%20Read%20the%20Docs-4f46e5?style=for-the-badge&logo=gitbook&logoColor=white&labelColor=1e293b&color=6366f1&fontSize=24" alt="Documentation"  height="36"/>
</a>
<a href="#-interactive-examples" target="_blank">
  <img src="https://img.shields.io/badge/📱%20Try%20Live%20Demo-fcba03?style=for-the-badge&logo=expo&logoColor=white&labelColor=1e293b&fontSize=24" alt="Live Demo" height="36"/>
</a>

</div>

---

## 🚀 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 3 for buttery-smooth 60fps animations
- 🏗️ **Full RN Fabric Support** - Works seamlessly with both New Architecture and Old Architecture
- 📦 **Expo Compatible** - Zero configuration needed, works out of the box with Expo
- 🪶 **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
- ⚡ **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 **15 interactive demos** showcasing every feature and use case.

<div align="center">

### 🎮 Try the Example App

<table>
<tr>
<td align="center" width="50%">

**📱 Scan & Play**

<img src="https://github.com/user-attachments/assets/80f923f6-7c5f-42e9-9817-7770ee27a70b" alt="Expo QR Code" width="200" height="200" />

_Scan with your camera or Expo Go app_

</td>
<td align="center" width="50%">

**🚀 Quick Start**

1. Install [Expo Go](https://expo.dev/client) on your phone
2. Scan the QR code with your camera
3. Open the link in Expo Go
4. Explore 15 interactive examples!

**Or browse the code:**
[**📂 View Example App →**](./example-app/README.md)

</td>
</tr>
</table>

### 📚 Complete Documentation

<a href="https://react-native-reanimated-dnd.netlify.app/" target="_blank">
  <img src="https://img.shields.io/badge/📖%20Documentation-Visit%20Docs-4f46e5?style=for-the-badge&logo=gitbook&logoColor=white&labelColor=1e293b" alt="Documentation" />
</a>

_Comprehensive guides, API reference, and interactive examples_

</div>

The example app includes:

- 🎵 **Sortable Music Queue** - Complete list reordering with handles
- 🎯 **Collision Detection** - Different algorithms in action
- 🎬 **Custom Animations** - Spring, timing, and easing variations
- 📦 **Boundary Constraints** - Axis-locked and bounded dragging
- ✨ **Visual Feedback** - Active styles and state management
- ⚙️ **Advanced Patterns** - Custom implementations and hooks

## 🎬 Video Showcase

**See the library in action** with these demos showcasing some of the key features and use cases.

<div align="center">

<table>
<tr>
<td align="center" width="50%">

### 📋 Sortable Lists

_Drag and drop to reorder items with smooth animations_

https://github.com/user-attachments/assets/1cd1929c-724b-4dda-a916-f3e69f917f7b

**Features:** Auto-scrolling • Drag handles • Smooth transitions

</td>
<td align="center" width="50%">

### 🎯 Collision Detection

_Multiple algorithms for precise drop targeting_

https://github.com/user-attachments/assets/379040d7-8489-430b-bae4-3fcbde34264e

**Algorithms:** Center • Intersect • Contain

</td>
</tr>
<tr>
<td align="center" width="50%">

### 🎪 Drag Handles

_Precise control with dedicated drag areas_

https://github.com/user-attachments/assets/ec051d5b-8ba0-41b7-86ae-379de26a97dd

**Features:** Touch-friendly • Visual feedback • Accessibility

</td>
<td align="center" width="50%">

### 📦 Bounded Dragging

_Constrain movement within specific boundaries_

https://github.com/user-attachments/assets/7bd5045b-47c4-4d9b-a0c5-eb89122ec9c0

**Constraints:** Axis-locked • Container bounds • Custom limits

</td>
</tr>
<tr>
<td align="center" width="50%">

### ✨ Active Drop Styles

_Visual feedback during drag operations_

https://github.com/user-attachments/assets/3b8a3d00-38ad-4532-bd42-173037ea61b9

**Feedback:** Hover states • Drop zones • Visual cues

</td>
<td align="center" width="50%">

### 🔄 State Management

_Complete lifecycle tracking and callbacks_

https://github.com/user-attachments/assets/da5e526f-f2d2-4dc5-96b5-3fecc4faf57a

**States:** Idle • Dragging • Animating • Dropped

</td>
</tr>
</table>

</div>

## 🚀 Installation

```bash
npm install @luudoanh/react-native-reanimated-dnd
```

### Peer Dependencies

**⚠️ Important:** This fork requires React Native Reanimated v4.0.0 or higher.

```bash
npm install react-native-reanimated@^4.0.0 react-native-gesture-handler
```

Follow the setup guides:

- [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/installation)
- [React Native Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler/docs/installation)

## 📋 Requirements

### Data Structure

All items in your data array **MUST** have an `id` property of type string:

```typescript
interface YourDataType {
  id: string; // Required!
  // ... your other properties
}
```

This is essential for the library to track items during reordering.

**Example:**

```typescript
// ✅ 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 Draggable

```tsx
import React from "react";
import { View, Text, StyleSheet } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { Draggable, DropProvider } from "@luudoanh/react-native-reanimated-dnd";

export default function App() {
  return (
    <GestureHandlerRootView style={styles.container}>
      <DropProvider>
        <View style={styles.content}>
          <Draggable data={{ id: "1", title: "Drag me!" }}>
            <View style={styles.draggableItem}>
              <Text style={styles.itemText}>🎯 Drag me around!</Text>
            </View>
          </Draggable>
        </View>
      </DropProvider>
    </GestureHandlerRootView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: "#000000",
  },
  content: {
    flex: 1,
    padding: 20,
    justifyContent: "center",
    alignItems: "center",
  },
  draggableItem: {
    padding: 20,
    backgroundColor: "#1C1C1E",
    borderRadius: 12,
    borderWidth: 1,
    borderColor: "#3A3A3C",
    shadowColor: "#000",
    shadowOffset: { width: 0, height: 2 },
    shadowOpacity: 0.25,
    shadowRadius: 4,
    elevation: 3,
  },
  itemText: {
    color: "#FFFFFF",
    fontSize: 16,
    fontWeight: "600",
    textAlign: "center",
  },
});
```

### Drag & Drop with Multiple Zones

```tsx
import React from "react";
import { Alert, StyleSheet, Text, View } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import {
  Draggable,
  Droppable,
  DropProvider,
} from "react-native-reanimated-dnd";

export default function DragDropExample() {
  const handleDrop = (data: any, zoneId: string) => {
    Alert.alert("Item Dropped", `"${data.title}" dropped in ${zoneId}`);
  };

  return (
    <GestureHandlerRootView style={styles.container}>
      <DropProvider>
        <View style={styles.content}>
          {/* Drop Zones */}
          <View style={styles.dropZonesSection}>
            <Text style={styles.sectionTitle}>Drop Zones</Text>

            <Droppable
              onDrop={(data) => handleDrop(data, "Zone 1")}
              activeStyle={styles.dropZoneActive}
              style={styles.droppable}
            >
              <View style={[styles.dropZoneBlue, styles.dropZone]}>
                <Text style={styles.dropZoneText}>🎯 Zone 1</Text>
                <Text style={styles.dropZoneSubtext}>Drop here</Text>
              </View>
            </Droppable>

            <Droppable
              onDrop={(data) => handleDrop(data, "Zone 2")}
              activeStyle={styles.dropZoneActive}
              style={styles.droppable}
            >
              <View style={[styles.dropZone, styles.dropZoneGreen]}>
                <Text style={styles.dropZoneText}>🎯 Zone 2</Text>
                <Text style={styles.dropZoneSubtext}>Drop here</Text>
              </View>
            </Droppable>
          </View>

          {/* Draggable Item */}
          <View style={styles.draggableSection}>
            <Text style={styles.sectionTitle}>Draggable Item</Text>
            <Draggable data={{ id: "1", title: "Task Item" }}>
              <View style={styles.draggableItem}>
                <Text style={styles.itemText}>📦 Drag me to a zone</Text>
              </View>
            </Draggable>
          </View>
        </View>
      </DropProvider>
    </GestureHandlerRootView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: "#000000",
  },
  content: {
    flex: 1,
    padding: 20,
    justifyContent: "space-between",
  },
  sectionTitle: {
    color: "#FFFFFF",
    fontSize: 18,
    fontWeight: "700",
    marginBottom: 20,
    textAlign: "center",
  },
  draggableSection: {
    alignItems: "center",
    paddingVertical: 40,
  },
  draggableItem: {
    padding: 20,
    backgroundColor: "#1C1C1E",
    borderRadius: 12,
    borderWidth: 1,
    borderColor: "#3A3A3C",
    shadowColor: "#000",
    shadowOffset: { width: 0, height: 2 },
    shadowOpacity: 0.25,
    shadowRadius: 4,
    elevation: 3,
  },
  itemText: {
    color: "#FFFFFF",
    fontSize: 16,
    fontWeight: "600",
    textAlign: "center",
  },
  dropZonesSection: {
    flex: 1,
    paddingVertical: 40,
  },
  droppable: {
    marginBottom: 20,
    overflow: "hidden",
    borderRadius: 16,
  },
  dropZone: {
    height: 140,
    borderWidth: 2,
    borderStyle: "dashed",
    borderRadius: 16,
    justifyContent: "center",
    alignItems: "center",
    padding: 20,
  },
  dropZoneBlue: {
    borderColor: "#58a6ff",
    backgroundColor: "rgba(88, 166, 255, 0.08)",
  },
  dropZoneGreen: {
    borderColor: "#3fb950",
    backgroundColor: "rgba(63, 185, 80, 0.08)",
  },
  dropZoneActive: {
    backgroundColor: "rgba(255, 255, 255, 0.1)",
    borderStyle: "solid",
    transform: [{ scale: 1.02 }],
  },
  dropZoneText: {
    color: "#FFFFFF",
    fontSize: 18,
    fontWeight: "600",
    textAlign: "center",
    marginBottom: 8,
  },
  dropZoneSubtext: {
    color: "#8E8E93",
    fontSize: 14,
    textAlign: "center",
  },
});
```

### Vertical Sortable List

```tsx
import React, { useCallback, useState } from "react";
import { StyleSheet, Text, View } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import {
  Sortable,
  SortableItem,
  SortableRenderItemProps,
} from "react-native-reanimated-dnd";

interface Task {
  id: string;
  title: string;
  completed: boolean;
}

export default function SortableExample() {
  const [tasks, setTasks] = useState<Task[]>([
    { id: "1", title: "Learn React Native", completed: false },
    { id: "2", title: "Build an app", completed: false },
    { id: "3", title: "Deploy to store", completed: true },
    { id: "4", title: "Celebrate success", completed: false },
  ]);

  const renderTask = useCallback(
    (props: SortableRenderItemProps<Task>) => {
      const {
        item,
        id,
        positions,
        lowerBound,
        autoScrollDirection,
        itemsCount,
        itemHeight,
      } = props;
      return (
        <SortableItem
          key={id}
          data={item}
          id={id}
          positions={positions}
          lowerBound={lowerBound}
          autoScrollDirection={autoScrollDirection}
          itemsCount={itemsCount}
          itemHeight={itemHeight}
          onMove={(itemId, from, to) => {
            console.log(`Task ${itemId} moved from ${from} to ${to}`);
            // Only log - do NOT update state here
          }}
          onDrop={(itemId, position, allPositions) => {
            if (allPositions) {
              console.log("All positions:", allPositions);
              // Use for tracking, analytics, etc. - NOT for reordering state
            }
          }}
          style={styles.taskItem}
        >
          <View style={styles.taskContent}>
            <View style={styles.taskInfo}>
              <Text style={styles.taskTitle}>{item.title}</Text>
              <Text style={styles.taskStatus}>
                {item.completed ? "✅ Completed" : "⏳ Pending"}
              </Text>
            </View>

            {/* Drag Handle */}
            <SortableItem.Handle style={styles.dragHandle}>
              <View style={styles.dragIconContainer}>
                <View style={styles.dragColumn}>
                  <View style={styles.dragDot} />
                  <View style={styles.dragDot} />
                  <View style={styles.dragDot} />
                </View>
                <View style={styles.dragColumn}>
                  <View style={styles.dragDot} />
                  <View style={styles.dragDot} />
                  <View style={styles.dragDot} />
                </View>
              </View>
            </SortableItem.Handle>
          </View>
        </SortableItem>
      );
    },
    [tasks]
  );

  return (
    <GestureHandlerRootView style={styles.container}>
      <View style={styles.header}>
        <Text style={styles.headerTitle}>📋 My Tasks</Text>
        <Text style={styles.headerSubtitle}>Drag to reorder</Text>
      </View>

      <Sortable
        data={tasks}
        renderItem={renderTask}
        itemHeight={80}
        style={styles.list}
      />
    </GestureHandlerRootView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: "#000000",
  },
  header: {
    padding: 20,
    paddingBottom: 16,
    borderBottomWidth: 1,
    borderBottomColor: "#2C2C2E",
  },
  headerTitle: {
    color: "#FFFFFF",
    fontSize: 24,
    fontWeight: "700",
    marginBottom: 4,
  },
  headerSubtitle: {
    color: "#8E8E93",
    fontSize: 14,
  },
  list: {
    flex: 1,
    backgroundColor: "#000000",
    marginTop: 20,
    paddingHorizontal: 20,
    borderRadius: 20,
    overflow: "hidden",
  },
  taskItem: {
    height: 80,

    backgroundColor: "transparent",
  },
  taskContent: {
    flex: 1,
    flexDirection: "row",
    alignItems: "center",
    paddingHorizontal: 20,
    backgroundColor: "#1C1C1E",

    borderWidth: 1,
    borderColor: "#3A3A3C",
  },
  taskInfo: {
    flex: 1,
    paddingRight: 16,
  },
  taskTitle: {
    color: "#FFFFFF",
    fontSize: 16,
    fontWeight: "600",
    marginBottom: 4,
  },
  taskStatus: {
    color: "#8E8E93",
    fontSize: 14,
  },
  dragHandle: {
    padding: 12,
    borderRadius: 8,
    backgroundColor: "rgba(255, 255, 255, 0.05)",
  },
  dragIconContainer: {
    flexDirection: "row",
    alignItems: "center",
    gap: 3,
  },
  dragColumn: {
    flexDirection: "column",
    gap: 2,
  },
  dragDot: {
    width: 3,
    height: 3,
    borderRadius: 1.5,
    backgroundColor: "#6D6D70",
  },
});
```

### Horizontal Sortable List

```tsx
import React, { useState } from "react";
import { StyleSheet, Text, View } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import {
  Sortable,
  SortableItem,
  SortableRenderItemProps,
  SortableDirection,
} from "react-native-reanimated-dnd";

interface Tag {
  id: string;
  label: string;
  color: string;
}

export default function HorizontalSortableExample() {
  const [tags, setTags] = useState<Tag[]>([
    { id: "1", label: "React", color: "#61dafb" },
    { id: "2", label: "TypeScript", color: "#3178c6" },
    { id: "3", label: "React Native", color: "#0fa5e9" },
    { id: "4", label: "JavaScript", color: "#f7df1e" },
    { id: "5", label: "Node.js", color: "#339933" },
  ]);

  const renderTag = (props: SortableRenderItemProps<Tag>) => {
    const {
      item,
      id,
      positions,
      leftBound,
      autoScrollHorizontalDirection,
      itemsCount,
      itemWidth,
      gap,
      paddingHorizontal,
    } = props;

    return (
      <SortableItem
        key={id}
        data={item}
        id={id}
        positions={positions}
        leftBound={leftBound}
        autoScrollHorizontalDirection={autoScrollHorizontalDirection}
        itemsCount={itemsCount}
        direction={SortableDirection.Horizontal}
        itemWidth={itemWidth}
        gap={gap}
        paddingHorizontal={paddingHorizontal}
        onMove={(itemId, from, to) => {
          console.log(`Tag ${itemId} moved from ${from} to ${to}`);
          // Only log - do NOT update state here
        }}
        onDrop={(itemId, position, allPositions) => {
          if (allPositions) {
            console.log("All positions:", allPositions);
            // Use for tracking, analytics, etc. - NOT for reordering state
          }
        }}
        style={styles.tagItem}
      >
        <View style={[styles.tagContent, { backgroundColor: item.color }]}>
          <Text style={styles.tagText}>{item.label}</Text>
        </View>
      </SortableItem>
    );
  };

  return (
    <GestureHandlerRootView style={styles.container}>
      <View style={styles.header}>
        <Text style={styles.headerTitle}>🏷️ Tech Tags</Text>
        <Text style={styles.headerSubtitle}>Drag horizontally to reorder</Text>
      </View>

      <Sortable
        data={tags}
        renderItem={renderTag}
        direction={SortableDirection.Horizontal}
        itemWidth={120}
        gap={12}
        paddingHorizontal={20}
        style={styles.horizontalList}
      />
    </GestureHandlerRootView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: "#000000",
  },
  header: {
    padding: 20,
    paddingBottom: 16,
  },
  headerTitle: {
    color: "#FFFFFF",
    fontSize: 24,
    fontWeight: "700",
    marginBottom: 4,
  },
  headerSubtitle: {
    color: "#8E8E93",
    fontSize: 14,
  },
  horizontalList: {
    height: 100,
    marginTop: 20,
  },
  tagItem: {
    width: 120,
    height: 60,
  },
  tagContent: {
    flex: 1,
    borderRadius: 30,
    justifyContent: "center",
    alignItems: "center",
    paddingHorizontal: 16,
  },
  tagText: {
    color: "#FFFFFF",
    fontSize: 14,
    fontWeight: "600",
    textAlign: "center",
  },
});
```

## 📚 API Reference

### Components

#### `<Draggable>`

Makes any component draggable with extensive customization options.

```tsx
<Draggable
  data={any}                                    // Data associated with the item
  onDragStart={(data) => void}                  // Called when dragging starts
  onDragEnd={(data) => void}                    // Called when dragging ends
  onDragging={(position) => void}               // Called during dragging
  onStateChange={(state) => void}               // Called on state changes
  dragDisabled={boolean}                        // Disable dragging
  collisionAlgorithm="center|intersect|contain" // Collision detection method
  dragAxis="x|y|both"                          // Constrain movement axis
  dragBoundsRef={RefObject}                    // Boundary container reference
  animationFunction={(toValue) => Animation}    // Custom animation function
  style={StyleProp<ViewStyle>}                 // Component styling
>
  {children}
</Draggable>
```

#### `<Droppable>`

Creates drop zones with visual feedback and capacity management.

```tsx
<Droppable
  onDrop={(data) => void}                      // Called when item is dropped
  onActiveChange={(isActive) => void}          // Called on hover state change
  dropDisabled={boolean}                       // Disable drop functionality
  dropAlignment="top-left|center|bottom-right|..." // Drop positioning
  dropOffset={{ x: number, y: number }}       // Position offset
  activeStyle={StyleProp<ViewStyle>}           // Style when active
  capacity={number}                            // Maximum items allowed
  droppableId={string}                         // Unique identifier
>
  {children}
</Droppable>
```

#### `<Sortable>`

High-level component for sortable lists with auto-scrolling. Supports both vertical and horizontal directions.

```tsx
<Sortable
  data={Array<{ id: string }>} // Array of items to render
  renderItem={(props) => ReactNode} // Render function for items
  direction={SortableDirection} // "vertical" | "horizontal" (default: vertical)
  itemHeight={number} // Height of each item (required for vertical)
  itemWidth={number} // Width of each item (required for horizontal)
  gap={number} // Gap between items (horizontal only)
  paddingHorizontal={number} // Horizontal padding (horizontal only)
  itemKeyExtractor={(item) => string} // Custom key extractor
  useFlatList={boolean} // Use FlatList for performance (default: true)
  style={StyleProp<ViewStyle>} // List container style
  contentContainerStyle={StyleProp<ViewStyle>} // Content container style
/>
```

#### `<SortableItem>`

Individual item within a sortable list with gesture handling.

```tsx
<SortableItem
  id={string}                                 // Unique identifier
  data={any}                                  // Item data
  positions={SharedValue}                     // Position tracking
  onMove={(id, from, to) => void}                        // Called when item moves
  onDragStart={(id, position) => void}                   // Called when dragging starts
  onDrop={(id, position, allPositions?) => void}        // Called when item is dropped
  onDragging={(id, overItemId, y) => void}               // Called during dragging
  style={StyleProp<ViewStyle>}               // Item styling
  animatedStyle={StyleProp<AnimatedStyle>}   // Animated styling
>
  {children}
</SortableItem>
```

### Hooks

#### `useDraggable(options)`

Core hook for implementing draggable functionality.

#### `useDroppable(options)`

Core hook for implementing droppable functionality.

#### `useSortable(options)`

Hook for individual sortable items with position management.

#### `useSortableList(options)`

Hook for managing entire vertical sortable lists with auto-scrolling.

#### `useHorizontalSortable(options)`

Core hook for implementing horizontal sortable functionality for individual items.

#### `useHorizontalSortableList(options)`

Hook for managing entire horizontal sortable lists with auto-scrolling.

### Context

#### `<DropProvider>`

Required context provider that manages global drag-and-drop state.

```tsx
<DropProvider>{/* All draggable and droppable components */}</DropProvider>
```

### Types & Enums

#### `DraggableState`

```tsx
enum DraggableState {
  IDLE = "idle",
  DRAGGING = "dragging",
  ANIMATING = "animating",
}
```

#### `CollisionAlgorithm`

```tsx
type CollisionAlgorithm = "center" | "intersect" | "contain";
```

#### `DropAlignment`

```tsx
type DropAlignment =
  | "top-left"
  | "top-center"
  | "top-right"
  | "center-left"
  | "center"
  | "center-right"
  | "bottom-left"
  | "bottom-center"
  | "bottom-right";
```

#### `SortableDirection`

```tsx
enum SortableDirection {
  Vertical = "vertical",
  Horizontal = "horizontal",
}
```

#### `HorizontalScrollDirection`

```tsx
enum HorizontalScrollDirection {
  None = "none",
  Left = "left",
  Right = "right",
}
```

## 🎨 Advanced Usage

### Custom Animations

```tsx
import { withTiming, withSpring, Easing } from "react-native-reanimated";

// Smooth timing animation
const smoothAnimation = (toValue) => {
  "worklet";
  return withTiming(toValue, {
    duration: 300,
    easing: Easing.bezier(0.25, 0.1, 0.25, 1),
  });
};

// Spring animation
const springAnimation = (toValue) => {
  "worklet";
  return withSpring(toValue, {
    damping: 15,
    stiffness: 150,
  });
};

<Draggable animationFunction={springAnimation}>{/* content */}</Draggable>;
```

### Enhanced onDrop Callback with Positions

The `onDrop` callback now includes an optional third parameter containing all item positions, making it easier to update your state with the new order:

```tsx
import { SortableItem } from "react-native-reanimated-dnd";

// Enhanced onDrop with allPositions parameter
const handleDrop = (
  id: string,
  position: number,
  allPositions?: { [id: string]: number }
) => {
  console.log(`Item ${id} dropped at position ${position}`);

  if (allPositions) {
    // allPositions contains all current item positions
    console.log("All positions:", allPositions);

    // IMPORTANT: Use this ONLY for read-only tracking
    // DO NOT update your state arrays directly with this data
    // Use for: analytics, external state synchronization, logging
  }
};

<SortableItem id={item.id} onDrop={handleDrop} {...otherProps}>
  {/* item content */}
</SortableItem>;
```

**Backward Compatibility**: The `allPositions` parameter is optional, so existing code continues to work unchanged. The parameter provides additional position data for advanced use cases where you need complete visibility into all item positions.

**Important**: The `allPositions` parameter is for **read-only tracking only**. Do not use it to automatically update your external state arrays, as this will break the internal state management. Programmatic list operations (add, update, delete, reorder) will be added in future releases.

### Collision Detection Strategies

```tsx
// Precise center-point collision
<Draggable collisionAlgorithm="center">
  {/* Requires center point to be over drop zone */}
</Draggable>

// Forgiving intersection collision (default)
<Draggable collisionAlgorithm="intersect">
  {/* Any overlap triggers collision */}
</Draggable>

// Strict containment collision
<Draggable collisionAlgorithm="contain">
  {/* Entire draggable must be within drop zone */}
</Draggable>
```

### Drag Handles

```tsx
<SortableItem id={item.id} {...props}>
  <View style={styles.itemContainer}>
    <Text>{item.title}</Text>

    {/* Only this handle area can initiate dragging */}
    <SortableItem.Handle style={styles.dragHandle}>
      <View style={styles.handleIcon}>
        <View style={styles.dot} />
        <View style={styles.dot} />
        <View style={styles.dot} />
      </View>
    </SortableItem.Handle>
  </View>
</SortableItem>
```

### Bounded Dragging

```tsx
const containerRef = useRef<View>(null);

<View ref={containerRef} style={styles.container}>
  <Draggable
    data={data}
    dragBoundsRef={containerRef}
    dragAxis="x" // Constrain to horizontal movement
  >
    {/* content */}
  </Draggable>
</View>;
```

### Drop Zone Capacity

```tsx
<Droppable
  capacity={3}
  onDrop={(data) => {
    if (currentItems.length < 3) {
      addItem(data);
    }
  }}
  activeStyle={{
    backgroundColor: currentItems.length < 3 ? "#e8f5e8" : "#ffe8e8",
  }}
>
  <Text>Drop Zone ({currentItems.length}/3)</Text>
</Droppable>
```

## 🏃‍♂️ Running the Example App

1. Clone the repository:

```bash
git clone https://github.com/entropyconquers/react-native-reanimated-dnd.git
cd react-native-reanimated-dnd
```

2. Install dependencies:

```bash
npm install
cd example-app
npm install
```

3. Run the example app:

```bash
# iOS
npx expo run:ios

# Android
npx expo run:android
```

The example app includes all 15 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:

### 🎯 Next Release (v2.0.0)

**Focus: Enhanced Functionality & Bug Fixes**

- 🐛 **Bug Fixes & Issues Resolution**
  - Address existing reported issues
  - Performance optimizations
  - Gesture handling improvements
  - API Improvements

- 📐 **Sortable Grids**
  - 2D grid drag-and-drop support
  - Flexible grid layouts (2x2, 3x3, custom)
  - Smart auto-positioning and gap management
  - Responsive grid behavior

- ↔️ **Horizontal Sortable Lists**
  - Full horizontal scrolling support
  - Auto-scroll for out-of-view items
  - Customizable scroll behavior

- 🪆 **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](https://github.com/entropyconquers/react-native-reanimated-dnd/issues/new?assignees=&labels=enhancement&template=feature_request.md) and let me know!

## 🤝 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**](CONTRIBUTING.md) for detailed information on:

- Setting up the development environment
- Code style guidelines
- Pull request process
- Testing requirements
- Community guidelines

## 📄 License

MIT © [Vishesh Raheja](https://github.com/entropyconquers)

## 🙏 Acknowledgments

- Built with [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/) for smooth 60fps animations
- Gesture handling powered by [React Native Gesture Handler](https://docs.swmansion.com/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

<div align="center">
<body>
If this library has helped you build amazing apps, consider supporting its development!
</br></br>
    <a href="https://www.buymeacoffee.com/entropyconquers" target="_blank">
        <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me a Coffee" style="height: 60px; width: 217px;">
    </a>
    </br>
</br>
  Your support helps maintain and improve this library for the entire React Native community! 🚀
</body>
</html>

</div>
<br/>

---

<div align="center">

**Made with ❤️ for the React Native community**

[⭐ Star on GitHub](https://github.com/entropyconquers/react-native-reanimated-dnd) • [📱 Try the Demo](https://github.com/entropyconquers/react-native-reanimated-dnd/tree/main/example-app) • [📖 Documentation](https://github.com/entropyconquers/react-native-reanimated-dnd#readme)

</div>