react-smooth-dnd

A fast and lightweight drag&drop, sortable library for React with many configuration options covering many d&d scenarios. It uses css transitions for animations so it's hardware accelerated whenever possible.

This library consists wrapper React components over smooth-dnd library.

Show, don't tell !

Demo page

Installation

npm i react-smooth-dnd

Usage

JSX

import React, { Component } from 'react';
import { Container, Draggable } from 'react-smooth-dnd';

class SimpleSortableList extends Component {
  render() {
    return (
      <div>
        <Container onDrop={this.props.onDrop}>
          {this.props.items.map(item => {
            return (
              <Draggable key={item.id}>
                {this.props.renderItem(item)}
              </Draggable>
            );
          })}
        </Container>
      </div>
    );
  }
}

API

Container

Component that contains the draggable elements or components. Each of its children should be wrapped by Draggable component

Props

onDragStart

The function to be called by all container when drag start.

function onDragStart({isSource, payload, willAcceptDrop}) {
  ...
}

Parameters

• isSource : boolean : true if it is called by the container which drag starts from otherwise false.
• payload : object : the payload object that is returned by getChildPayload function. It will be undefined in case getChildPayload is not set.
• willAcceptDrop : boolean : true if the dragged item can be dropped into the container, otherwise false.

onDragEnd

The function to be called by all container when drag ends. Called before onDrop function

function onDragEnd({isSource, payload, willAcceptDrop}) {
  ...
}

Parameters

• isSource : boolean : true if it is called by the container which drag starts from, otherwise false.
• payload : object : the payload object that is returned by getChildPayload function. It will be undefined in case getChildPayload is not set.
• willAcceptDrop : boolean : true if the dragged item can be dropped into the container, otherwise false.

onDropReady

The function to be called by the container which is being drag over, when the index of possible drop position changed in container. Basically it is called each time the draggables in a container slides for opening a space for dragged item. dropResult is the only parameter passed to the function which contains the following properties.

function onDropReady(dropResult) {
  const { removedIndex, addedIndex, payload, element } = dropResult;
  ...
}

Parameters

• dropResult : object
  • removedIndex : number : index of the removed children. Will be null if no item is removed.
  • addedIndex : number : index to add droppped item. Will be null if no item is added.
  • payload : object : the payload object retrieved by calling getChildPayload function.
  • element : DOMElement : the DOM element that is moved

onDrop

The function to be called by any relevant container when drop is over. (After drop animation ends). Source container and any container that could accept drop is considered relevant. dropResult is the only parameter passed to the function which contains the following properties.

function onDrop(dropResult) {
  const { removedIndex, addedIndex, payload, element } = dropResult;
  ...
}

Parameters

• dropResult : object
  • removedIndex : number : index of the removed children. Will be null if no item is removed.
  • addedIndex : number : index to add droppped item. Will be null if no item is added.
  • payload : object : the payload object retrieved by calling getChildPayload function.
  • element : DOMElement : the DOM element that is moved

getChildPayload

The function to be called to get the payload object to be passed onDrop function.

function getChildPayload(index) {
  return {
    ...
  }
}

Parameters

• index : number : index of the child item

Returns

• payload : object

shouldAnimateDrop

The function to be called by the target container to which the dragged item will be droppped. Sometimes dragged item's dimensions are not suitable with the target container and dropping animation can be wierd. So it can be disabled by returning false. If not set drop animations are enabled.

function shouldAnimateDrop(sourceContainerOptions, payload) {
  return false;
}

Parameters

• sourceContainerOptions : object : options of the source container. (parent container of the dragged item)
• payload : object : the payload object retrieved by calling getChildPayload function.

Returns

• boolean : true / false

shouldAcceptDrop

The function to be called by all containers before drag starts to determine the containers to which the drop is possible. Setting this function will override the groupName property and only the return value of this function will be taken into account.

function shouldAcceptDrop(sourceContainerOptions, payload) {
  return true;
}

Parameters

• sourceContainerOptions : object : options of the source container. (parent container of the dragged item)
• payload : object : the payload object retrieved by calling getChildPayload function.

Returns

• boolean : true / false

onDragEnter

The function to be called by the relevant container whenever a dragged item enters its boundaries while dragging.

function onDragEnter() {
  ...
}

onDragLeave

The function to be called by the relevant container whenever a dragged item leaves its boundaries while dragging.

function onDragLeave() {
  ...
}

getGhostParent

The function to be called to get the element that the dragged ghost will be appended. Default parent element is the container itself. The ghost element is positioned as 'fixed' and appended to given parent element. But if any anchestor of container has a transform property, ghost element will be positioned relative to that element which breaks the calculations. Thats why if you have any transformed parent element of Containers you should set this property so that it returns any element that has not transformed parent element.

function getGhostParent() {
  // i.e return document.body;
}

render

By default Container uses a div element for component root. You can define what to render as root element by using render function. If render function is set, children prop of Container will be ignored and return value of the render will be used to render draggables.

function render(ref) {
  // return ReactElement
}

Parameters

• ref : object : React reference object created by React.createRef()

Returns

• React Element

<Container render={(ref) => {
  return (
    <ul ref={ref}>
      ...place your <Draggable/> components here
    </ul>
  )
}}/>

Draggable

Wrapper component for Container's children. Every draggable element should be wrapped with Draggable component.

Make sure to set unique key to Draggable especially when it contains other Container components

Props

render

By default Draggable uses a div element for component root. You can define what to render as root element by using render function. If render function is set, children prop of Draggable will be ignored and return value of the render will be used to render draggable.

<Draggable render={() => {
  return (
    <li>
      ...
    </li>
  )
}}/>

Parameters

• ref : object : React reference object created by React.createRef()

Returns

• React Element