Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sahilaggarwal2004/react-reorder-list

A simple react component that facilitates the reordering of JSX/HTML elements through drag-and-drop functionality, allowing for easy position changes.
https://github.com/sahilaggarwal2004/react-reorder-list

component dnd drag-and-drop javascript-library list npm-package react react-library reorder reorderable-list typescript

Last synced: about 1 month ago
JSON representation

A simple react component that facilitates the reordering of JSX/HTML elements through drag-and-drop functionality, allowing for easy position changes.

Awesome Lists containing this project

README 

        
# react-reorder-list



A simple react component that facilitates the reordering of JSX/HTML elements through drag-and-drop functionality, allowing for easy position changes.



## Features



- Reorders list of elements using drag and drop.

- Easy to use

- Smooth transition using animation.

- Listens to children updates. See [listen to children updates](#listen-to-children-updates)

- Disables reordering for individual children. See [disable reordering for individual children](#disable-reordering-for-individual-children)

- Handles nested lists easily. See [nested list usage](#nested-list-usage)



## Installation



To install react-reorder-list



```bash

  # with npm:

  npm install react-reorder-list --save



  # with yarn:

  yarn add react-reorder-list



  # with pnpm:

  pnpm add react-reorder-list



  # with bun:

  bun add react-reorder-list

```



## Usage



`react-reorder-list` default exports `` component which encapsulates all the list items as its children.



Items in this list can be reordered by simply dragging an item and dropping it in place of another item.



#### Basic Usage



Each `
` component inside `` can now be drag-and-dropped to another `
` to reorder them.



```jsx

import React from "react";

import ReorderList from "react-reorder-list";



export default function App() {

  return (

    

      {[0, 1, 2, 3, 4].map((i) => {

        return 
Item {i}
; // Having a unique key is important

      })}

    

  );

}

```



#### Usage with ReorderIcon



The dragging behavior can be changed using the `useOnlyIconToDrag` prop of `` component.



If set to `false`, an item can be dragged by clicking anywhere inside the item.



If set to `true`, an item can be dragged only using the `` present inside the item.



```jsx

import React from 'react'

import ReorderList, { ReorderIcon } from 'react-reorder-list'



export default function App() {

  return 

    {[0, 1, 2, 3, 4].map(i => {

      return 


         {/* Default icon */}

        

          {/* Custom icon/component */}

        

        {i}

      


    })}

  

}

```



#### Listen to Children Updates



`` can listen to updates to it's children components using the `watchChildrenUpdates` prop as shown below.



If set to `false`, any updates made in children component except reordering by user won't reflect.



If set to `true`, updates to children like state changes, additions/omissions of children components will reflect in real time.


Further if `preserveOrder` is set to false, the order in which new children appear will be maintained.


Whereas if `preserveOrder` is set to true, the order of existing items will be preserved as before the update occured and new items will be placed at the end irrespective of their order in children. Also, if an item is being dragged and an update occurs at that moment, that item will be placed at respective location and `onPositionChange` will be called to prevent any inconsistency.



NOTE: The props `watchChildrenUpdates` and `preserveOrder` should be used carefully to avoid any unexpected behaviour



```jsx

import React, { useState } from "react";

import ReorderList from "react-reorder-list";



export default function App() {

  const [array, setArray] = useState([0, 1, 2, 3, 4]);



  function setNewArray() {

    setArray((prev) => {

      const array = [];

      prev.forEach((_) => {

        do {

          var item = Math.floor(Math.random() * 9);

        } while (array.includes(item));

        array.push(item);

      });

      return array;

    });

  }



  return (

    


      

        {array.map((i) => (

          
Item {i}


        ))}

      

      Click me

    


  );

}

```



#### Disable reordering for individual children



```jsx

import React from "react";

import ReorderList from "react-reorder-list";



export default function App() {

  return (

    

      


        This div cannot be reordered

      


      {[0, 1, 2, 3, 4].map((i) => {

        return 
Item {i}
; // Having a unique key is important

      })}

      


        This p cannot be reordered either

      


    

  );

}

```



#### Nested List Usage



```jsx

import React from "react";

import ReorderList, { ReorderIcon } from "react-reorder-list";



export default function App() {

  return (

    

      {[0, 1, 2].map((i) => {

        return (

          


            

            {"Parent" + i}

            

              {[0, 1, 2].map((j) => {

                return (

                  


                    

                    {"Child" + i + j}

                  


                );

              })}

            

          


        );

      })}

    

  );

}

```



## ReorderList Component API Reference



Here is the full API for the `` component, these properties can be set on an instance of ReorderList:

| Parameter | Type | Required | Default | Description |

| - | - | - | - | - |

| `useOnlyIconToDrag` | `boolean` | No | false | See [usage with ReorderIcon](#usage-with-reordericon) |

| `selectedItemOpacity` | `number (0 to 1)` | No | 0.5 | This determines the opacity of the item being dragged, until released. |

| `animationDuration` | `number` | No | 400 | The duration (in ms) of swapping animation between items. If set to 0, animation will be disabled. |

| `watchChildrenUpdates` | `boolean` | No | false | Enable this to listen to any updates in children of `` and update the state accordingly. See [listen to children updates](#listen-to-children-updates) |

| `preserveOrder` | `boolean` | No | false | Works along woth `watchChildrenUpdates` to determine whether to preserve existing order or not. See [listen to children updates](#listen-to-children-updates) |

| `onPositionChange` | [`PositionChangeHandler`](#positionchangehandler) | No | - | Function to be executed on item position change. |

| `disabled` | `boolean` | No | false | When set to true, `` will work as a plain `div` with no functionality. |

| `props` | `React.DetailedHTMLProps` | No | - | Props to customize the `` component. |



### Types



#### PositionChangeHandler



```typescript

import { ReactNode } from "react";

type RevertHandler = () => void;

type PositionChangeParams = {

  start?: number; // Index of the item being dragged

  end?: number; // Index of the item being displaced by the starting item

  oldItems?: ReactNode[]; // Array of children before reordering

  newItems?: ReactNode[]; // Array of children after reordering

  revert: RevertHandler; // A fallback handler to revert the reordering

};

type PositionChangeHandler = (params?: PositionChangeParams) => void;

```



## Author



[Sahil Aggarwal](https://www.github.com/SahilAggarwal2004)