# Sortable
## Installation
To get started, install the sortable preset via `npm` or `yarn`:
```bash
npm install @dnd-kit/sortable
```
## Overview
If you're eager to get started right away, here's the code you'll need:
{% tabs %}
{% tab title="App.jsx" %}
```jsx
import React, {useState} from 'react';
import {
DndContext,
closestCenter,
KeyboardSensor,
PointerSensor,
useSensor,
useSensors,
} from '@dnd-kit/core';
import {
arrayMove,
SortableContext,
sortableKeyboardCoordinates,
verticalListSortingStrategy,
} from '@dnd-kit/sortable';
import {SortableItem} from './SortableItem';
function App() {
const [items, setItems] = useState([1, 2, 3]);
const sensors = useSensors(
useSensor(PointerSensor),
useSensor(KeyboardSensor, {
coordinateGetter: sortableKeyboardCoordinates,
})
);
return (
{items.map(id => )}
);
function handleDragEnd(event) {
const {active, over} = event;
if (active.id !== over.id) {
setItems((items) => {
const oldIndex = items.indexOf(active.id);
const newIndex = items.indexOf(over.id);
return arrayMove(items, oldIndex, newIndex);
});
}
}
}
```
{% endtab %}
{% tab title="SortableItem.jsx" %}
```jsx
import React from 'react';
import {useSortable} from '@dnd-kit/sortable';
import {CSS} from '@dnd-kit/utilities';
export function SortableItem(props) {
const {
attributes,
listeners,
setNodeRef,
transform,
transition,
} = useSortable({id: props.id});
const style = {
transform: CSS.Transform.toString(transform),
transition,
};
return (
{/* ... */}
);
}
```
{% endtab %}
{% endtabs %}
For most sortable lists, we recommend you use a [`DragOverlay`](/api-wen-dang/draggable/drag-overlay.md) if your sortable list is scrollable or if the contents of the scrollable list are taller than the viewport of the window. Check out the[ sortable drag overlay guide](#drag-overlay) below to learn more.
## Architecture
The sortable preset builds on top of the primitives exposed by `@dnd-kit/core` to help building sortable interfaces.
The sortable preset exposes two main concepts: [`SortableContext`](#sortable-context) and the [`useSortable`](#usesortable) hook:
* The `SortableContext` provides information via context that is consumed by the `useSortable` hook.
* The `useSortable` hook is an abstraction that composes the [`useDroppable`](/api-wen-dang/droppable.md) and [`useDraggable`](/api-wen-dang/draggable.md) hooks:
### Single container
At a high level, the application structure to implement a **sortable list with a single container** looks as follows:
### Multiple containers
To implement sortable list with items that can be dropped within **multiple containers**, the application structure is the same, but we add as many `SortableContext` providers as we have containers:
In this example, we would use the `onDragOver` callback of `DndContext` to detect when a draggable element is moved over a different container to insert it in that new container while dragging.
If you paid close attention to the illustration above, you may also have noticed that we added a droppable zone around each sortable context. This isn't required, but will likely be the behaviour most people want. If you move all sortable items from one column into the other, you will need a droppable zone for the empty column so that you may drag sortable items back into that empty column:
## Concepts
### Sortable Context
In addition to the [`DndContext` provider](/jie-shao/getting-started.md#context-provider), the Sortable preset requires its own context provider that contains the **sorted** array of the unique identifiers associated to each sortable item:
```jsx
import React, {useState} from 'react';
import {DndContext} from '@dnd-kit/core';
import {SortableContext} from '@dnd-kit/sortable';
function App() {
const [items] = useState(['1', '2', '3']);
return (
{/* ... */}
);
}
```
The `SortableContext` provides information via context that is consumed by the `useSortable` hook, which is covered in greater detail in the next section.
{% hint style="info" %}
It's important that the `items` prop passed to `SortableContext` be sorted in the same order in which the items are rendered, otherwise you may see unexpected results.
{% endhint %}
It does not expose any callback props. To know when a sortable (draggable) item is being picked or moved over another sortable (droppable) item, use the callback props of `DndContext`:
```jsx
import React, {useState} from 'react';
import {DndContext} from '@dnd-kit/core';
import {SortableContext} from '@dnd-kit/sortable';
function App() {
const [items] = useState(['1', '2', '3']);
return (
{/* ... */}
);
function handleDragEnd(event) {
/* ... */
}
}
```
{% hint style="warning" %}
In order for the `SortableContext` component to function properly, make sure it is a descendant of a `DndContext` provider. You may nest multiple `SortableContext` components within the same parent `DndContext`.
{% endhint %}
### useSortable
As outlined above, the `useSortable` hook combines both the [`useDraggable`](/api-wen-dang/draggable.md) and [`useDroppable`](/api-wen-dang/droppable.md) hooks to connect elements as both draggable sources and drop targets:
{% hint style="info" %}
In most cases, the draggable and droppable hooks will be attached to the same node, and therefore be identical in size. They are represented as different nodes for illustration purposes above.
{% endhint %}
If you're already familiar with the [`useDraggable`](/api-wen-dang/draggable.md) hook, the [`useSortable`](/yu-zhi-neng-li/sortable/usesortable.md) hook should look very familiar, since, it is an abstraction on top of it.
In addition to the `attributes`, `listeners`,`transform` and `setNodeRef` properties, which you should already be familiar with if you've used the `useDraggable` hook before, you'll notice that the `useSortable` hook also provides a `transition` property.
The `transform` property for `useSortable` represents the displacement and change of scale transformation that a sortable item needs to apply to transition to its new position without needing to update the DOM order.
The `transform` property for the `useSortable` hook behaves similarly to the [`transform`](/api-wen-dang/draggable.md#transforms) property of the [`useDraggable`](/api-wen-dang/draggable.md) hook for the active sortable item, when there is no [`DragOverlay`](/api-wen-dang/draggable/drag-overlay.md) being used.
{% tabs %}
{% tab title="SortableItem.jsx" %}
```jsx
import React from 'react';
import {useSortable} from '@dnd-kit/sortable';
import {CSS} from '@dnd-kit/utilities';
function SortableItem(props) {
const {
attributes,
listeners,
setNodeRef,
transform,
transition,
} = useSortable({id: props.id});
const style = {
transform: CSS.Transform.toString(transform),
transition,
};
return (
{/* ... */}
);
}
```
{% endtab %}
{% endtabs %}
The default transition is `250` milliseconds, with an easing function set to `ease`, but you can customize this and pass any valid [CSS transition timing function](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function), or set the transition argument to `null` to disable transitions entirely:
```javascript
const {
transition,
} = useSortable({
id: props.id,
transition: {
duration: 150, // milliseconds
easing: 'cubic-bezier(0.25, 1, 0.5, 1)',
},
});
```
For more details on the `useSortable` hook, read the full [API documentation](/yu-zhi-neng-li/sortable/usesortable.md).
### Sensors
Sensors are an abstraction to manage and listen to different input methods. If you're unfamiliar with the concept of sensors, we recommend you read the [introduction to sensors](/api-wen-dang/sensors.md) first.
By default, the [Keyboard](/api-wen-dang/sensors/keyboard.md) sensor moves the active draggable item by `25` pixels in the direction of the arrow key that was pressed. This is an arbitrary default, and can be customized using the `coordinateGetter` option of the keyboard sensor.
The sortable preset ships with a custom coordinate getter function for the keyboard sensor that moves the active draggable to the closest sortable element in a given direction within the same `DndContext`.
To use it, import the `sortableKeyboardCoordinates` coordinate getter function provided by `@dnd-kit/sortable`, and pass it to the `coordiniateGetter` option of the Keyboard sensor.
In this example, we'll also be setting up the [Pointer](/api-wen-dang/sensors/pointer.md) sensor, which is the other sensor that is enabled by default on `DndContext` if none are defined. We use the `useSensor` and `useSensors` hooks to initialize the sensors:
```jsx
import {
DndContext,
KeyboardSensor,
PointerSensor,
useSensor,
useSensors,
} from '@dnd-kit/core';
import {
SortableContext,
sortableKeyboardCoordinates,
} from '@dnd-kit/sortable';
function App() {
const [items] = useState(['1', '2', '3']);
const sensors = useSensors(
useSensor(PointerSensor),
useSensor(KeyboardSensor, {
coordinateGetter: sortableKeyboardCoordinates,
})
);
return (
{/* ... */}
);
}
```
If you'd like to use the [Mouse](/api-wen-dang/sensors/mouse.md) and [Touch](/api-wen-dang/sensors/touch.md) sensors instead of the [Pointer](/api-wen-dang/sensors/pointer.md) sensor, simply initialize those sensors instead:
```jsx
import {
DndContext,
KeyboardSensor,
MouseSensor,
TouchSensor,
useSensor,
useSensors,
} from '@dnd-kit/core';
import {
SortableContext,
sortableKeyboardCoordinates,
} from '@dnd-kit/sortable';
function App() {
const [items] = useState(['1', '2', '3']);
const sensors = useSensors(
useSensor(MouseSensor, {
// Require the mouse to move by 10 pixels before activating
activationConstraint: {
distance: 10,
},
}),
useSensor(TouchSensor, {
// Press delay of 250ms, with tolerance of 5px of movement
activationConstraint: {
delay: 250,
tolerance: 5,
},
}),
useSensor(KeyboardSensor, {
coordinateGetter: sortableKeyboardCoordinates,
})
);
return (
{/* ... */}
);
}
```
To learn more about sensors, read the in-depth documentation on sensors:
{% content-ref url="/pages/07mieR1hMD06Qq5bC9GI" %}
[Sensors](/api-wen-dang/sensors.md)
{% endcontent-ref %}
### Sorting strategies
The supported use cases of the Sortable preset include vertical lists, horizontal lists, grids, and virtualized lists. Because of the wide variety of use cases supported, it would be difficult to write a single strategy to cover all of these different use cases. Instead, the sortable preset exposes a number of different strategies you can use, that are tailored to these various use cases:
* `rectSortingStrategy`: This is the default value, and is suitable for most use cases. This strategy does not support virtualized lists.
* `verticalListSortingStrategy`: This strategy is optimized for vertical lists, and supports virtualized lists.
* `horizontalListSortingStrategy`: This strategy is optimized for horizontal lists, and supports virtualized lists.
* `rectSwappingStrategy`: Use this strategy to achieve swappable functionality.
Make sure to use the sorting strategy that is the most adapted to the use case you are building for.
### Collision detection algorithm
The default collision detection algorithm of `DndContext` is the [rectangle intersection](/api-wen-dang/context-provider/collision-detection-algorithms.md#rectangle-intersection) algorithm. While the rectangle intersection strategy is well suited for many use cases, it can be unforgiving, since it requires both the draggable and droppable bounding rectangles to come into direct contact and intersect.
For sortable lists, we recommend using a more forgiving collision detection strategy such as the [closest center](/api-wen-dang/context-provider/collision-detection-algorithms.md#closest-center) or [closest corners](/api-wen-dang/context-provider/collision-detection-algorithms.md#closest-corners) algorithms.
In this example, we'll be using the closest center algorithm:
```jsx
import {DndContext, closestCenter} from '@dnd-kit/core';
import {SortableContext} from '@dnd-kit/sortable';
function App() {
const [items] = useState(['1', '2', '3']);
return (
{/* ... */}
);
}
```
To learn more about collision detection algorithms and when to use one over the other, read our guide on collision detection algorithms:
{% content-ref url="/pages/TvLORMoAh2eADxDvARaD" %}
[碰撞检测算法](/api-wen-dang/context-provider/collision-detection-algorithms.md)
{% endcontent-ref %}
## Connecting all the pieces
First, let's go ahead and render all of our sortable items:
{% tabs %}
{% tab title="App.jsx" %}
```jsx
import React, {useState} from 'react';
import {DndContext} from '@dnd-kit/core';
import {SortableContext} from '@dnd-kit/sortable';
import {SortableItem} from './SortableItem';
function App() {
const [items] = useState(['1', '2', '3']);
return (
{items.map(id => )}
);
}
```
{% endtab %}
{% tab title="SortableItem.jsx" %}
```jsx
import React from 'react';
import {useSortable} from '@dnd-kit/sortable';
import {CSS} from '@dnd-kit/utilities';
function SortableItem(props) {
const {
attributes,
listeners,
setNodeRef,
transform,
transition,
} = useSortable({id: props.id});
const style = {
transform: CSS.Transform.toString(transform),
transition,
};
return (
{/* ... */}
);
}
```
{% endtab %}
{% endtabs %}
Next, let's wire up the custom sensors for `DndContext` and add a custom collision detection strategy:
{% tabs %}
{% tab title="App.jsx" %}
```jsx
import React, {useState} from 'react';
import {
DndContext,
closestCenter,
KeyboardSensor,
PointerSensor,
useSensor,
useSensors,
} from '@dnd-kit/core';
import {
SortableContext,
sortableKeyboardCoordinates,
} from '@dnd-kit/sortable';
import {SortableItem} from './SortableItem';
function App() {
const [items] = useState(['1', '2', '3']);
const sensors = useSensors(
useSensor(PointerSensor),
useSensor(KeyboardSensor, {
coordinateGetter: sortableKeyboardCoordinates,
})
);
return (
{items.map(id => )}
);
}
```
{% endtab %}
{% tab title="SortableItem.jsx" %}
```jsx
import {useSortable} from '@dnd-kit/sortable';
import {CSS} from '@dnd-kit/utilities';
export function SortableItem(props) {
const {
attributes,
listeners,
setNodeRef,
transform,
transition,
} = useSortable({id: props.id});
const style = {
transform: CSS.Transform.toString(transform),
transition,
};
return (
{/* ... */}
);
}
```
{% endtab %}
{% endtabs %}
In this example, we'll be building a vertical sortable list, so we will be using the `verticalListSortingStrategy` sorting strategy:
```jsx
import React, {useState} from 'react';
import {
DndContext,
closestCenter,
KeyboardSensor,
PointerSensor,
useSensor,
useSensors,
} from '@dnd-kit/core';
import {
SortableContext,
sortableKeyboardCoordinates,
verticalListSortingStrategy,
} from '@dnd-kit/sortable';
import {SortableItem} from './SortableItem';
function App() {
const [items] = useState(['1', '2', '3']);
const sensors = useSensors(
useSensor(PointerSensor),
useSensor(KeyboardSensor, {
coordinateGetter: sortableKeyboardCoordinates,
})
);
return (
{items.map(id => )}
);
}
```
Finally, we'll need to set up event handlers on the `DndContext` provider in order to update the order of the items on drag end.
```jsx
import React, {useState} from 'react';
import {
DndContext,
closestCenter,
KeyboardSensor,
PointerSensor,
useSensor,
useSensors,
} from '@dnd-kit/core';
import {
arrayMove,
SortableContext,
sortableKeyboardCoordinates,
verticalListSortingStrategy,
} from '@dnd-kit/sortable';
import {SortableItem} from './SortableItem';
function App() {
const [items, setItems] = useState(['1', '2', '3']);
const sensors = useSensors(
useSensor(PointerSensor),
useSensor(KeyboardSensor, {
coordinateGetter: sortableKeyboardCoordinates,
})
);
return (
{items.map(id => )}
);
function handleDragEnd(event) {
const {active, over} = event;
if (active.id !== over.id) {
setItems((items) => {
const oldIndex = items.indexOf(active.id);
const newIndex = items.indexOf(over.id);
return arrayMove(items, oldIndex, newIndex);
});
}
}
}
```
### Drag Overlay
For most sortable lists, we recommend you use a [`DragOverlay`](/api-wen-dang/draggable/drag-overlay.md) if your sortable list is scrollable or if the contents of the scrollable list are taller than the viewport of the window.
The `` component provides a way to render a draggable overlay that is removed from the normal document flow and is positioned relative to the viewport. The drag overlay also implements drop animations.
A **common pitfall** when using the `DragOverlay` component is rendering the same component that calls `useSortable` inside the `DragOverlay`. This will lead to unexpected results, since there will be an `id` collision between the two components both calling `useDraggable` with the same `id`, since `useSortable` is an abstraction on top of `useDraggable`.
Instead, create a presentational version of your component that you intend on rendering in the drag overlay, and another version that is sortable and renders the presentational component. There are two recommended patterns for this, either using [wrapper nodes](/api-wen-dang/draggable/drag-overlay.md#wrapper-nodes) or[ ref forwarding](/api-wen-dang/draggable/drag-overlay.md#ref-forwarding).
In this example, we'll use the [ref forwarding](/api-wen-dang/draggable/drag-overlay.md#ref-forwarding) pattern to avoid introducing wrapper nodes:
{% tabs %}
{% tab title="App.jsx" %}
```jsx
import React, {useState} from 'react';
import {
closestCenter,
DndContext,
DragOverlay,
KeyboardSensor,
PointerSensor,
useSensor,
useSensors,
} from '@dnd-kit/core';
import {
arrayMove,
SortableContext,
sortableKeyboardCoordinates,
verticalListSortingStrategy,
} from '@dnd-kit/sortable';
import {SortableItem} from './SortableItem';
import {Item} from './Item';
function App() {
const [activeId, setActiveId] = useState(null);
const [items, setItems] = useState(['1', '2', '3']);
const sensors = useSensors(
useSensor(PointerSensor),
useSensor(KeyboardSensor, {
coordinateGetter: sortableKeyboardCoordinates,
})
);
return (
{items.map(id => )}
{activeId ? -
{value}
);
}
```
{% endtab %}
{% tab title="Item.jsx" %}
```jsx
import React, {forwardRef} from 'react';
export const Item = forwardRef(({id, ...props}, ref) => {
return (
{id}
)
});
```
{% endtab %}
{% endtabs %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.dndkit.cn/yu-zhi-neng-li/sortable.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.