A React component to sort items in lists or grids
npm install react-easy-sortA React component to sort items in lists or grids
[![version][version-badge]][package] [![Monthly downloads][npmstats-badge]][npmstats] ![gzip size][brotli-badge] [![MIT License][license-badge]][license] [![PRs Welcome][prs-badge]][prs]
The goal of this component is to allow sorting elements with drag and drop.
It is mobile friendly by default. It doesn't block scrolling the page when swiping inside it:
the user needs to press an item during at least 200ms to start the drag gesture.
On non-touch devices, the drag gesture only starts after moving an element by at least one pixel.
This is done to avoid blocking clicks on clickable elements inside an item.
- Supports horizontal and vertical lists
- Supports grid layouts
- Mobile-friendly
- IE11 support 🙈
Check out the examples:
- Example with grid layout
- Example with vertical list layout
- Example with horizontal list layout
- Interactive avatars demo
- Example with custom knobs
``shell`
yarn add react-easy-sort
or
`shell`
npm install react-easy-sort --save
`js
import SortableList, { SortableItem } from 'react-easy-sort'
import { arrayMoveImmutable } from 'array-move'
const App = () => {
const [items, setItems] = React.useState(['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I'])
const onSortEnd = (oldIndex: number, newIndex: number) => {
setItems((array) => arrayMoveImmutable(array, oldIndex, newIndex))
}
return (
{items.map((item) => (
{item}
))}
)
}
`
| Name | Description | Type | Default |
|--------------------------|:-------------------------------------------------------------------------------:|:----------------------------------------------:|----------------:|
| as | Determines html tag for the container element | keyof JSX.IntrinsicElements | div |() => void
| onSortStart | Called when the user starts a sorting gesture | | - |(newIndex: number) => void
| onSortMove | Called when the dragged item changes position during a sorting gesture | | - |(oldIndex: number, newIndex: number) => void
| onSortEnd\* | Called when the user finishes a sorting gesture. | | - |string
| draggedItemClassName | Class applied to the item being dragged | | - |'x'
| lockAxis | Determines if an axis should be locked | or 'y' | |boolean
| allowDrag | Determines whether items can be dragged | | true |React.RefObject
| customHolderRef | Ref of an element to use as a container for the dragged item | | document.body |ReactNode
| dropTarget | React element to use as a dropTarget | | |boolean
| autoScroll | Determines whether the containing element (or window) should scroll during sort | | false |
This component doesn't take any other props than its child. This child should be a single React element that can receives a ref. If you pass a component as a child, it needs to be wrapped with React.forwardRef().
You can use this component if you don't want the whole item to be draggable but only a specific area of it.
`js
import SortableList, { SortableItem, SortableKnob } from 'react-easy-sort'
import arrayMove from 'array-move'
const App = () => {
const [items, setItems] = React.useState(['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I'])
const onSortEnd = (oldIndex: number, newIndex: number) => {
setItems((array) => arrayMove(array, oldIndex, newIndex))
}
return (
{items.map((item) => (
Drag me
{item}
))}
)
}
`
This component doesn't take any other props than its child. This child should be a single React element that can receive a ref. If you pass a component as a child, it needs to be wrapped with React.forwardRef().
To disable browser default behaviors that can interfer with the dragging experience, we recommend adding the following declarations on the "items":
- user-select: none;: disable the selection of content inside the item (the blue box)pointer-events: none;
- : required for some browsers if your items contain images (see the Interactive avatars demo)
`shell`
yarn
yarn start
Now, open http://localhost:3001/index.html` and start hacking!
This project is maintained by Valentin Hervieu.
This project was originally part of @ricardo-ch organisation because I (Valentin) was working at Ricardo.
After leaving this company, they gracefully accepted to transfer the project to me. ❤️
- https://github.com/clauderic/react-sortable-hoc : before creating this library, I was using it and it was also supporting grid layouts. However, we had a lot of errors reported to our Sentry and this project was not maintained anymore.
- https://github.com/atlassian/react-beautiful-dnd: another great library for sorting items. However, it doesn't support grid layouts (as of 2021-02-05).
[npm]: https://www.npmjs.com/
[node]: https://nodejs.org
[version-badge]: https://img.shields.io/npm/v/react-easy-sort.svg?style=flat-square
[package]: https://www.npmjs.com/package/react-easy-sort
[downloads-badge]: https://img.shields.io/npm/dm/react-easy-sort.svg?style=flat-square
[npmstats]: https://npm-stat.com/charts.html?package=react-easy-sort&from=2021-02-01
[npmstats-badge]: https://img.shields.io/npm/dm/react-easy-sort.svg?style=flat-square
[brotli-badge]: http://img.badgesize.io/https://unpkg.com/react-easy-sort/umd/react-easy-sort.min.js?compression=brotli&style=flat-square&1
[license-badge]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square
[license]: https://github.com/ValentinH/react-easy-sort/blob/main/LICENSE
[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
[prs]: http://makeapullrequest.com