UnflowUI
ComponentsHooks

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

ParamTypeDescription
keysK[]Required. Item keys in their current order. Used to tell whether a drop lands before or after the target
enabledbooleanWhether rows can be dragged. Defaults to true
onReorder(from: K, to: K) => voidRequired. Called on drop with the dragged key and the key it was dropped on

Return value

FieldTypeDescription
getItemProps(key: K) => objectSpread onto each row
isDragged(key: K) => booleantrue for the row being dragged
dropSide(key: K) => DropSide | null'before' or 'after' for the row under the pointer, null otherwise

getItemProps(key) returns

PropDescription
draggabletrue when enabled, false otherwise
onDragStart, onDragOver, onDragLeave, onDrop, onDragEndDrag 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.