react-sortablejs

What is react-sortablejs?

react-sortablejs is a React wrapper for the SortableJS library, which provides drag-and-drop functionality for lists and grids. It allows for easy reordering of items within a list or grid, with support for various customization options and event handling.

What are react-sortablejs's main functionalities?

Basic Drag-and-Drop

This feature allows you to create a simple drag-and-drop list. The items in the list can be reordered by dragging and dropping.

import React from 'react';
import Sortable from 'react-sortablejs';

const SimpleList = () => {
  const items = ['Item 1', 'Item 2', 'Item 3'];
  return (
    <Sortable tag="ul">
      {items.map((item, index) => (
        <li key={index}>{item}</li>
      ))}
    </Sortable>
  );
};

export default SimpleList;

Handling Events

This feature demonstrates how to handle events such as the end of a drag-and-drop action. The `onEnd` event handler logs the event details when an item is moved.

import React from 'react';
import Sortable from 'react-sortablejs';

const EventHandlingList = () => {
  const items = ['Item 1', 'Item 2', 'Item 3'];

  const handleEnd = (evt) => {
    console.log('Item moved:', evt);
  };

  return (
    <Sortable tag="ul" onEnd={handleEnd}>
      {items.map((item, index) => (
        <li key={index}>{item}</li>
      ))}
    </Sortable>
  );
};

export default EventHandlingList;

Custom Drag Handle

This feature allows you to specify a custom handle for dragging items. In this example, only the elements with the class `handle` can be used to drag the list items.

import React from 'react';
import Sortable from 'react-sortablejs';

const CustomHandleList = () => {
  const items = ['Item 1', 'Item 2', 'Item 3'];
  return (
    <Sortable tag="ul" handle=".handle">
      {items.map((item, index) => (
        <li key={index}>
          <span className="handle">::</span> {item}
        </li>
      ))}
    </Sortable>
  );
};

export default CustomHandleList;

Other packages similar to react-sortablejs

react-beautiful-dnd

react-beautiful-dnd is a drag-and-drop library for React that focuses on providing a beautiful and accessible drag-and-drop experience. It offers more advanced features like automatic scrolling and customizable drag handles. Compared to react-sortablejs, it provides a more polished user experience but may have a steeper learning curve.

react-dnd

react-dnd is a flexible drag-and-drop library for React that is built on top of the HTML5 drag-and-drop API. It provides a more low-level API compared to react-sortablejs, allowing for greater customization and control over the drag-and-drop interactions. It is suitable for more complex use cases where fine-grained control is required.

react-draggable

react-draggable is a library for making elements draggable in React. It is more focused on providing basic drag-and-drop functionality for individual elements rather than lists or grids. It is simpler and more lightweight compared to react-sortablejs, making it a good choice for basic drag-and-drop needs.

README

react-sortablejs

React component wrapping SortableJS!

We're now on version 2.0! A major API overhaul with typescript types.

Consider trying it out if you had any troubles earlier.

Table of Contents

• Features
  • SortableJS
  • Component Specific
• Installation
• Learn
• Usage/Examples
  • Function Component
  • Class Component
• Plugins
• Sortable API
• React API
  • id, className, style
  • list
  • setList
  • clone
  • tag
    • HTML Element
    • Custom Component
• How does it work?
• Caveats / Gotchas
  • key !== index
  • Nesting
    • Problem
    • What does work?
    • Solutions

Features

SortableJS

Everything you love about SortableJS, including to but not limited to:

• Drag and Drop between lists
• Multidrag and Swap plugin support.

Component Specific

• Calculates items in list automatically
• Updated API via props. Feels more like react than ever before.
• Compatible with third part UI libraries
• SortableJS Plugin Support

If you find any features lacking, create an issue and/or pull request.

Installation

npm install --save react-sortablejs
# OR
yarn add react-sortablejs

Please note that sortablejs is not required, as it's bundled in this component.

Learn

Here is the TLDR of what sortable is:

- Shopping List: # list of items / sortable. This represents `react-sortablejs`
  - eggs # list item. These are all the items in the list and is what you move around.
  - bread # list item
  - milk # list item

Usage/Examples

Function Component

import React, { FC, useState } from "react";
import { ReactSortable } from "react-sortablejs";

interface ItemType {
  id: number;
  name: string;
}

export const BasicFunction: FC = (props) => {
  const [state, setState] = useState<ItemType[]>([
    { id: 1, name: "shrek" },
    { id: 2, name: "fiona" },
  ]);

  return (
    <ReactSortable list={state} setList={setState}>
      {state.map((item) => (
        <div key={item.id}>{item.name}</div>
      ))}
    </ReactSortable>
  );
};

Class Component

import React, { Component } from "react";
import { ReactSortable } from "react-sortablejs";

interface BasicClassState {
  list: { id: string; name: string }[];
}

export class BasicClass extends Component<{}, BasicClassState> {
  state: BasicClassState = {
    list: [{ id: "1", name: "shrek" }],
  };
  render() {
    return (
      <ReactSortable
        list={this.state.list}
        setList={(newState) => this.setState({ list: newState })}
      >
        {this.state.list.map((item) => (
          <div key={item.id}>{item.name}</div>
        ))}
      </ReactSortable>
    );
  }
}

Plugins

Sortable has some pretty cool plugins such as MultiDrag and Swap.

By Default:

• AutoScroll is premounted and enabled.
• OnSpill is premounted and NOT enabled.
• MultiDrag and Swap and NOT premounted and NOT enabled

You must mount mount the plugin with sortable ONCE ONLY.

import React from "react";
import { ReactSortable, Sortable, MultiDrag, Swap } from "react-sortablejs";

// mount whatever plugins you'd like to. These are the only current options.
Sortable.mount(new MultiDrag(), new Swap());

const App = () => {
  const [state, setState] = useState([
    { id: 1, name: "shrek" },
    { id: 2, name: "fiona" },
  ]);

  return (
    <ReactSortable
      multiDrag // enables mutidrag
      // OR
      swap // enables swap
    >
      {state.map((item) => (
        <div key={item.id}>{item.name}</div>
      ))}
    </ReactSortable>
  );
};

Sortable API

For a comprehensive list of options, please visit https://github.com/SortableJS/Sortable#options.

Those options are applied as follows.

Sortable.create(element, {
  group: " groupName",
  animation: 200,
  delayOnTouchStart: true,
  delay: 2,
});

// --------------------------
// Will now be..
// --------------------------

import React from "react";
import { ReactSortable } from "react-sortablejs";

const App = () => {
  const [state, setState] = useState([
    { id: 1, name: "shrek" },
    { id: 2, name: "fiona" },
  ]);

  return (
    <ReactSortable
      // here they are!
      group="groupName"
      animation={200}
      delayOnTouchStart={true}
      delay={2}
    >
      {state.map((item) => (
        <div key={item.id}>{item.name}</div>
      ))}
    </ReactSortable>
  );
};

React API

id, className, style

Thes are all defaults DOM attributes. Nothing special here.

list

The same as state in const [ state, setState] = useState([{ id: 1}, {id: 2}])

state must be an array of items, with each item being an object that has the following shape:

  /** The unique id associated with your item. It's recommended this is the same as the key prop for your list item. */
  id: string | number;
  /** When true, the item is selected using MultiDrag */
  selected?: boolean;
  /** When true, the item is deemed "chosen", which basically just a mousedown event. */
  chosen?: boolean;
  /** When true, it will not be possible to pick this item up in the list. */
  filtered?: boolean;
  [property: string]: any;

setList

The same as setState in const [ state, setState] = useState([{ id: 1}, {id: 2}])

clone

If you're using {group: { name: 'groupName', pull: 'clone'}}, this means your in 'clone' mode. You should provide a function for this.

Check out the source code of the clone example for more information. I'll write it here soon.

tag

ReactSortable is a div element by default. This can be changed to be any HTML element (for example ul, ol) or can be a React component.

This value, be the component or the HTML element should be passed down under props.tag.

Let's explore both here.

HTML Element

Here we will use a ul. You can use any HTML. Just add the string and ReactSortable will use a li instead of a div.

import React, { FC, useState } from "react";
import { ReactSortable } from "react-sortablejs";

export const BasicFunction: FC = (props) => {
  const [state, setState] = useState([{ id: "1", name: "shrek" }]);

  return (
    <ReactSortable tag="ul" list={state} setList={setState}>
      {state.map((item) => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ReactSortable>
  );
};

Custom Component

When using a custom component in the tag prop, the only component it allows is a forwardRef component. Currently we only support components who use the React.forwardRef API.

If it doesn't have one, you can add one using React.forwardRef().

todo: Some third party UI components may have nested elements to create the look they're after. This could be an issue and not sure how to fix.

import React, { FC, useState, forwardRef } from "react";
import { ReactSortable } from "react-sortablejs";

// This is just like a normal component, but now has a ref.
const CustomComponent = forwardRef<HTMLDivElement, any>((props, ref) => {
  return <div ref={ref}>{props.children}</div>;
});

export const BasicFunction: FC = (props) => {
  const [state, setState] = useState([
    { id: 1, name: "shrek" },
    { id: 2, name: "fiona" },
  ]);

  return (
    <ReactSortable tag={CustomComponent} list={state} setList={setState}>
      {state.map((item) => (
        <div key={item.id}>{item.name}</div>
      ))}
    </ReactSortable>
  );
};

How does it work?

Sortable affects the DOM, adding, and removing nodes/css when it needs to in order to achieve the smooth transitions we all know an love. This component reverses many of it's actions of the DOM so React can handle this when the state changes.

Caveats / Gotchas

key !== index

DO NOT use the index as a key for your list items. Sorting will not work.

In all the examples above, I used an object with an ID. You should do the same!

I may even enforce this into the design to eliminate errors.

Nesting

Problem

Basically the child updates the state twice. I'm working on this.

What does work?

Our usage indicates that as long as we only move items between lists that don't use the same setState function.

I hope to provide an example soon.

Solutions

We don't have anything that works 100%, but here I'd like to spit ball some potential avenues to look down.

• Use onMove to handle state changes instead of onAdd,onRemove, etc.
• Create a Sortable plugin specifically for react-sortbalejs