react-native-nested-drag

Overview

This library is a declarative drag-and-drop system for React Native, written in TypeScript. It is designed to be flexible and powerful with the goal of supporting many use cases. Default settings should cover the most common scenarios with minimal configuration.

Screenshots

More screenshots

More screenshots

Snack

There is an example on snack though it works fine only on real device.

Installation

npm i react-native-nested-drag

or using yarn

yarn add react-native-nested-drag

Usage

Import the library components:

import { DragView, DropView, DragProvider } from 'react-native-nested-drag'

Basic example

<DragProvider>
  <DropView>
    <Text>drop here!</Text>
  </DropView>
  <DragView>
    <Text>drag me</Text>
  </DragView>
</DragProvider>

DragProvider

Wrap the part of your application that you want to enable drag and drop for inside DragProvider.

<DragProvider>
  {/*  */}
</DragProvider>

Props

All props are optional.

Prop	Type	Default	Description
mockEventManager	IDndEventManager		Only for testing
overlapMode	OverlapMode	'last'	Specifies events call order when multiple DropView in same area. After sorting with comparer, DropView events will be called last to first. You can't change it dynamically.

DragView

The element that you want to make draggable.

The DragView won't be actually dragged, instead a copy appears on DragStart to make sure element always on top.

      <DragView payload={1}>
        <View style={styles.itemContainer}>
          <Text>+1</Text>
        </View>
      </DragView>

Props

All props are optional.

Available all ViewProps except for GestureResponderHandlers

Prop	Type	Default	Description
payload	any		An arbitrary value (often) unique to this draggable that can later be used to determine which draggable item was dropped onto a droppable
style	ViewStyle		Style applied while this view is NOT being dragged
dragStyle	ViewStyle		Style applied while this view is being dragged
overStyle	ViewStyle		Style applied while this view is being dragged over a receiver
copyDragStyle	ViewStyle		Style applied to the copy while this view is being dragged
copyOverStyle	ViewStyle		Style applied to the copy while this view is being dragged over a receiver
disabled	boolean	false	Specifies whether this view can be dragged
longPressDelay	number	0	Time interval in ms after which this view can be dragged
vibroDuration	number	0	Vibration duration on drag start in ms
movable	boolean	false	Specifies whether this view stays where it has been dragged
movableOffset	IPosition	{x:0,y:0}	It useful only when you want nested movable DragView appear correctly inside the draggable copy or for restoring movable state. This prop shouldn't be used just for formatting
onDragStart	DraggableDragStart		Callback that is triggerd when user starts dragging the DragView
onDrag	DraggableDragStart		Callback that is triggered repeatedly when user dragging the DragView not over any receiver
onEnter	DraggableEnterOver		Callback that is triggered when the DragView initially dragged over a new receiver
onOver	DraggableEnterOver		Callback that is triggered repeatedly when the DragView dragged over a receiver
onExit	DraggableExit		Callback that is triggered when the DragView leaves the droppable area
onDragEnd	DraggableEnd		Callback that is triggered when the DragView drag ends not over any receiver or is cancelled
onDrop	DraggableDrop		Callback that is triggered when the DragView drag ends over a receiver
animationEndOptions	SpringAnimationConfig	{ overshootClamping: true}	Animated.SpringAnimationConfig to customize dragEnd animation
animationDropOptions	TimingAnimationConfig		Animated.TimingAnimationConfig to customize drop fadeout animation

DragHandleView

DragHandleView is useful when you want to restrict area where drag can start.

Just place one or more inside DragView. Notice that Button and TouchableOpacity work inside DragView and also restrict possible drag start area (you can't start drag on buttons).

    <DragView>
        <Text>part 1</Text>
        <DragHandleView style={styles.handle}>
          <Text>drag here!</Text>
        </DragHandleView>
    </DragView>

Props

All props are optional.

Available all ViewProps except for GestureResponderHandlers

DropView

The element that you want to receive droppable events.

  const drop = (_, payload) => {
    console.log(payload)
  }
  //...
  
    <DropView onDrop={add}>
      <Text>drop here!</Text>
    </DropView>

Props

All props are optional.

Available all ViewProps

Prop	Type	Default	Description
payload	any		An arbitrary value (often) unique to this DropView that can later be used to determine in which DropView the DragView was dropped to
style	ViewStyle		Style applied while over this DropView is NOT dragging a DragView
overStyle	ViewStyle		Style applied while dragging a DragView over this DropView
disabled	boolean	false	Specifies whether this view receives DnD events
onEnter	DroppableEnterExit		Callback that is triggered when a DragView initially dragged over this DropView
onOver	DroppableDropOver		Callback that is triggered repeatedly when a DragView dragged over this DropView
onExit	DroppableEnterExit		Callback that is triggered when a DragView leaves this DropView
onDrop	DroppableDropOver		Callback that is triggered when a DragView dragging ends over this DropView

Testing

Import the library components:

import { DragProvider, MockDndEventManager } from 'react-native-nested-drag'

Create mockEventManager:

const mockEventManager = new MockDndEventManager()

Wrap your component for test render:

<DragProvider mockEventManager={mockEventManager}>
  <YourComponent>
</DragProvider>

Call DnD action like so:

mockEventManager.drop(mockEventManager.draggables[0], mockEventManager.droppables[0])

If you have animation errors set before the action:

jest.mock('react-native/Libraries/Animated/NativeAnimatedHelper')
jest.useFakeTimers()

Full example with 'testing-library/react-native'

License

This software library is licensed under the MIT License.

Caveats and tips

• If nested elements rendered base on own state clone appears as initial state. Possible workaround is move that state outside DragProvider (e.g. state management library).

• If you want to store offset for movable DragView (may be because previous point) onDragEnd and onDrop receives it as parameter.

• Don't put these styles on DragView (if necessary add View inside or outside):

  • margin
  • transform
  • position
  • opasity (allowed for dragStyle and overStyle only)

• % width style doesn't work well in many cases.

• There is useEffect listeners on props so make sure your props won't change on every render.

For example:

instead

...movableOffset={{x:50, y:-10}}...

use

...
const [movableOffset] = useState({x:50, y:-10});

...movableOffset={movableOffset}...

• Available option for overlap handling is next callback (for onDrop and onOver)

• Overlapping DropView is tricky especially when nested.

Explanation

Droppables is plain array registered on first render so if on screen they are:

graph LR;
    A-->B;
    A-->C;
    D;

where B and C nested to A.

Droppables order: [B, C, A, D]

Moreover if you are using dynamic 'disabled' prop, which causes unregister order may become completely unpredictable.

You may try to use next callback or comparer function for overlapMode but much easier just avoid overlapping whenever it's possible.

• onLayout event probably still calls only once (when component renders first time) inside DragView and DropView (also don't use it inside 'View' with onLayout if elements may change positions on screen besides dragging.)