react-native-reanimated-dnd

The DragDropContext (exported as SlotsContext) is the central React context that provides the infrastructure for drag-and-drop functionality in react-native-reanimated-dnd. It is automatically created by the DropProvider and serves as the communication layer between draggable and droppable components.

It manages several core responsibilities:

• Drop Zone Registration: Tracking all registered droppable areas.
• Active State Management: Monitoring which drop zones are currently hovered/active.
• Position Updates: Handling layout changes and recalculating positions.
• Dropped Items Tracking: Maintaining state of which items are dropped where.
• Capacity Management: Enforcing drop zone capacity limits.
• Event Coordination: Coordinating drag events across the component tree.

The hook provides several lifecycle callbacks for managing state and side effects during the drag-and-drop process:

• onMove(id, from, to): Triggered when an item's index changes. Use this to update your underlying data model (e.g., reordering an array).
• onDragStart(id, position): Triggered when a drag begins. Useful for haptic feedback or updating global UI states like isDragging.
• onDrop(id, position): Triggered when the drag ends. Use this to finalize data changes or trigger success notifications.
• onDragging(id, overItemId, xPosition): Triggered continuously during the drag. Use this for real-time feedback like hover states or scroll hints based on xPosition relative to the containerWidth.

The useDraggable hook tracks the lifecycle of a drag interaction via the DraggableState enum:

• IDLE: The item is at its rest position.
• DRAGGING: The user is actively moving the item.
• DROPPED: The item was successfully dropped on a valid droppable.

Transitions:

• IDLE → DRAGGING: User starts dragging.
• DRAGGING → DROPPED: Successful drop on a droppable.
• DRAGGING → IDLE: Drag ends without a successful drop.
• DROPPED → IDLE: Animation completes and item returns to position.

To maintain high performance and avoid jank:

• Sortable Remounting: Note that the Sortable component remounts the entire list whenever the data array changes (using a hash of IDs as the key). This resets scroll position and animation state. For more granular control, use the hooks API (useSortableList + useSortable) directly.
• Lightweight Handlers: Keep onDragging handlers lightweight. They fire approximately 20 times per second and bridge from the UI thread to JS. Heavy computation here will cause frame drops.
• Grid Efficiency: Unlike Sortable, SortableGrid does not remount the entire list on data changes, making it more efficient for frequent updates.

The Draggable component tracks its lifecycle through three distinct states, which can be monitored via the onStateChange callback:

• IDLE: The component is at its rest position.
• DRAGGING: The component is being actively moved by the user.
• DROPPED: The component has been successfully dropped.

You can use these states to apply conditional styling or trigger animations.

enum DraggableState {
  IDLE = "IDLE",
  DRAGGING = "DRAGGING",
  DROPPED = "DROPPED",
}

SortableItem and its parent Sortable component maintain internal state for high performance. Do not update external state directly in sortable callbacks (like onMove), as this will break the internal state management and cause issues with reordering.

Correct Usage

• Use onMove only for side effects like logging or analytics.
• Use onDrop with the allPositions argument for read-only position tracking.
• Let the sortable system handle the actual reordering of items automatically.

Incorrect Usage

• Never call reorderTasks(), setItems(), or similar inside onMove.
• Never update arrays, Redux stores, or Zustand stores directly from drag events.
• Never manually splice or modify external arrays during drag operations.

Depending on your layout requirements, you may want to use these related abstractions instead of or alongside useHorizontalSortable:

• useHorizontalSortableList: Use this for managing the state and logic of an entire horizontal sortable list.
• useSortable: Use this for vertical sortable items.
• SortableItem: A high-level component that simplifies the implementation of sortable items.
• Horizontal Sortable Example: A complete implementation reference for horizontal layouts.

The hook automatically calculates the contentWidth used for the contentContainerStyle of the ScrollView. The formula used is:

contentWidth = (itemsCount * itemWidth) + ((itemsCount - 1) * gap) + (paddingHorizontal * 2)

Example Calculation:

• 5 items × 120px width = 600px
• 4 gaps × 10px gap = 40px
• 2 × 16px padding = 32px
• Total: 672px

You can control how a draggable item detects collisions with droppables using the collisionAlgorithm option. This is useful for different UX requirements:

• intersect (Default): Collision is detected when any part of the draggable overlaps a droppable. Best for general drag-and-drop.
• center: Collision is detected only when the center point of the draggable is over a droppable. Best for precise placement or grid layouts.
• contain: Collision is detected only when the entire draggable item is within the boundaries of a droppable. Best for strict containment like folder systems.

const { animatedViewProps, gesture } = useDraggable({
  data: { id: "3", name: "Collision Test" },
  collisionAlgorithm: "center", // Options: "intersect", "center", "contain"
});