useDragReorder
Native drag-and-drop reordering for a keyed list, with the dragged row and drop edge exposed for styling. Used by ListEditor and ColumnsPanel.
Overview
useDragReorder adds HTML5 drag-and-drop reordering to any list whose items have a stable key. Spread getItemProps(key) onto each row; the hook tracks which row is being dragged and which edge of the hovered row it would land on, and calls onReorder(from, to) on drop. Moving the item in your data is up to you.
It is used by ListEditor and by the columns panel in the DataTable toolbar.
Import
import { useDragReorder } from '@unflowio/ui/hooks/useDragReorder';
import type { DropSide } from '@unflowio/ui/hooks/useDragReorder';Parameters
| Param | Type | Description |
|---|---|---|
keys | K[] | Required. Item keys in their current order. Used to tell whether a drop lands before or after the target |
enabled | boolean | Whether rows can be dragged. Defaults to true |
onReorder | (from: K, to: K) => void | Required. Called on drop with the dragged key and the key it was dropped on |
Return value
| Field | Type | Description |
|---|---|---|
getItemProps | (key: K) => object | Spread onto each row |
isDragged | (key: K) => boolean | true for the row being dragged |
dropSide | (key: K) => DropSide | null | 'before' or 'after' for the row under the pointer, null otherwise |
getItemProps(key) returns
| Prop | Description |
|---|---|
draggable | true when enabled, false otherwise |
onDragStart, onDragOver, onDragLeave, onDrop, onDragEnd | Drag handlers. Only present when enabled |
Usage
import { useDragReorder } from '@unflowio/ui/hooks/useDragReorder';
function moveItem<T>(items: T[], from: number, to: number): T[] {
const next = [...items];
next.splice(to, 0, ...next.splice(from, 1));
return next;
}
interface Step {
id: string;
label: string;
}
function StepList({ steps, onChange }: { steps: Step[]; onChange: (next: Step[]) => void }) {
const keys = steps.map((step) => step.id);
const { getItemProps, isDragged, dropSide } = useDragReorder({
keys,
enabled: steps.length > 1,
onReorder: (from, to) => onChange(moveItem(steps, keys.indexOf(from), keys.indexOf(to))),
});
return (
<ul>
{steps.map((step) => (
<li
key={step.id}
{...getItemProps(step.id)}
data-dragged={isDragged(step.id) || undefined}
data-drop={dropSide(step.id) ?? undefined}
className="data-[dragged]:opacity-50 data-[drop=after]:border-b-2 data-[drop=before]:border-t-2"
>
{step.label}
</li>
))}
</ul>
);
}Implementation notes
Drop edge. dropSide is 'after' when the dragged item comes from above the target and 'before' when it comes from below, which matches removing the item at from and inserting it at to, as moveItem above does.
Keys must be stable. Use ids, not indices: indices change as soon as the list moves.
Pointer only. HTML5 drag-and-drop does not work with touch on most mobile browsers, nor with the keyboard.
Accessibility
Dragging has no keyboard or screen reader equivalent. Always pair it with buttons that move a row up and down (as ListEditor does) and announce the new position if the list is long.
useDeferredFocus
Moves focus after a controlled value changes, once the element to focus exists in its new place. Used by ListEditor.
useArrowNavigation
Fires previous/next callbacks on a pair of arrow keys anywhere on the page, without hijacking typing in fields. Used by ItemNav, Pagination, Toolbar and DataTable.