FragiolaDnD
Documentation
Concepts

Sortable lists

Reorder a list, a row or a grid by pointer and keyboard with no wrapper around it. The core previews the move with translate shifts, and your state applies it.

A sortable item is a drag source that knows its place: its group (the list it belongs to) and its index in that list. Items of one group find each other through the document's drag space, so a list needs no wrapper around it: wrap each item, and the list is whatever element holds them.

todo.tsx
import { arrayMove, Sortable } from "@fragiola/dnd-react/sortable";

const [tasks, setTasks] = useState(["login", "export", "guide"]);

<ul className="list">
    {tasks.map((id, index) => (
        <Sortable
            key={id}
            id={id}
            index={index}
            group="todo"
            onSortEnd={(event) => {
                if (!event.canceled) setTasks((now) => arrayMove(now, event.from.index, event.to.index));
            }}
        >
            <li className="task">{id}</li>
        </Sortable>
    ))}
</ul>;

What stays yours: the data and its order, the look of the dragged item and of its neighbours, and the animation of the shifts (animating shifts).

Sortable list
Gallery

The preview is written by the core

While an item is dragged, its neighbours make room for it. The core writes each shifted item's CSS translate (never transform), computed from every item's box at rest, once per frame at most and only when the preview changes:

  • the DOM never moves, so the drag's pointer capture is never lost and React never reconciles anything the core wrote;
  • React does not render during the drag: the items re-render at the sort's start and end only (data-dnd-sorting);
  • the boxes at rest are measured without the shifts (even mid-way through your transition), at the start and after a scroll or a resize, so a shift never feeds back into the place it shows and auto-scroll re-measures without a jump.

The dragged item follows the pointer as a draggable does. With translate={false} (a DragOverlay shows it) it is shifted to where it would land instead, as its own placeholder.

Your state applies the result

onSortEnd reports { id, from: { group, index }, to: { group, index }, canceled }, where to is exactly what the preview showed. Apply it to your own state with the pure helpers, arrayMove for one list or moveBetween for several. The core clears the shifts after your callbacks and the page's listeners ran, so React renders the new order in the same frame the shifts disappear: no jump, no flicker.

the drag endstocanceled
released over a place of a groupwhere the preview put itfalse
released outside every groupthe last place the preview showedfalse
released over a plain Droppable of the scopefrom (the list goes back to rest)false
vetoed by a drop middlewarefromfalse
Escape, pointercancel, a lost capturefromtrue

Strategies

A strategy is a pure function that answers two questions over a group's boxes at rest: where the source goes for the dragged box's centre, and how far every item shifts for that move. Each is its own export, so an app ships only the ones it uses:

strategyfor
verticalList (the default)a column of items of any height
horizontalLista row of items of any width, flowing from the inline start (the right, in RTL)
grida wrapping grid in reading order, RTL aware; best with items of one size
gallery.tsx
import { grid, Sortable } from "@fragiola/dnd-react/sortable";

<Sortable id={photo.id} index={index} group="photos" strategy={grid}>
    <figure />
</Sortable>;

Over an item, the source takes its place; between items (a gap, the end of a row) the place does not change, so the preview never flickers in the gaps. The grid adds hysteresis at row boundaries: entering an item of another row needs the probe a quarter of that item's height inside it. See the strategies for the details.

Sortable grid
Gallery

Right to left

Nothing to configure: the horizontal list and the grid read the item's direction and flow from the right, and the keyboard's forward is the inline end.

Sortable, right to left
Gallery

By keyboard

A sortable item is a tab stop. Space or Enter grabs it, the arrows move it one slot (down and the arrow toward the inline end go forward), on into the next accepting group past a group's end, Space or Enter drops it, and Escape cancels and restores every shift. See keyboard and accessibility.

Several lists

Items of different groups form different lists. A group takes items of another group only when it accepts them, which makes a kanban: see groups and the kanban guide.