Sortable

modelValue is the list itself, bound with v-model — pick a row up, drag it past its neighbours, and the whole array comes back in its new order. Nothing is stored inside the component: the rows animate during the drag, but where they land is decided by the array you assign back.

orientation is the axis rows travel along. horizontal lays them out in a row and drags them left and right — for column orders, tab strips, anything read across rather than down — and it swaps the arrow keys that move a picked-up item to match.

handle moves the drag onto a grip at the start of each row and leaves the rest of the row alone. Reach for it the moment rows contain their own controls — without it a press on the button below would be the start of a drag as easily as a click.

itemKey names the property Vue keys each row by. It matters as soon as a row holds state of its own: keyed by identity the text you typed travels with the field it belongs to, keyed by position it would stay behind on the row number instead. Type into a field below, then drag it somewhere else.

variant decides what surface each row brings. card rings and tints every row; solid, subtle and soft are the same three surfaces Card offers, so a list can match the cards around it; ghost draws nothing until hovered; plain does the same with a tighter gap, for a list already sitting inside a card of its own. On the lighter surfaces the grip steps up a shade so it stays visible.

size is the padding inside each row — the same three steps the rest of the library uses. It changes the row height and nothing else; the drag geometry is measured off whatever the rows actually render at.

lockAxis keeps the dragged row on its own axis, which is what makes a list feel like a list. Turn it off and the row follows the pointer in both directions — it reads as lifting the row off the stack rather than sliding it along, and the drop still lands on the axis either way.

disabled freezes the whole list — no drags, no keyboard pick-ups, no tab stops. A single item opts out on its own with disabled on the item instead, which stops it being picked up but doesn't pin it in place: its neighbours can still move around it, and its index changes when they do.

label is the list's accessible name, announced when focus first reaches a row. The default says only that the list is sortable, which is enough when there's one on the page and not nearly enough when there are two — name them after what they order.

nested turns the list into a tree. Items name their parent, children hang off it on a line, and a drag has three outcomes: drop onto a row to nest the item under it, into a gap to place it there at that level, or below the last row to make it top-level. Children travel with their parent. By keyboard, ← takes an item out of its group and → tucks it under the item above.

parentKey names the property that holds an item's parent — the parent's itemKey value, or nothing for a top-level item. It defaults to parentId; point it at whatever your data already calls the column, so the array can go back to a server unchanged.

maxDepth caps how far below the top level a tree may go. With 1, items can have children but not grandchildren: dropping anything onto a child is refused, and so is nesting an item that already has children of its own, since its children would land a level too deep.

Every row is a tab stop. Space or enter picks one up, the arrow keys move it — Home and End send it to either end — space or enter drops it, and escape puts it back where it started. The row follows along as you go, the list announces each move to a screen reader, and focus stays on the item after it lands, so a second move needs no re-aiming.

Drag a row to the top or bottom edge below and the container scrolls to meet it, faster the closer you get. The list finds the scrolling ancestor itself when the drag starts, so this needs nothing at the call site — and it falls back to scrolling the page when the list isn't inside a scroller of its own.

The item slot replaces the row's contents and nothing else — the surface, the padding and the grip stay with the component, so a custom row still lines up with a plain one and still drags the same way. Anything focusable inside it is left clickable: presses that land on a button, link or input never start a drag, and data-sortable-ignore extends that to anything else.

The actions slot renders next to each row, outside its surface — for a remove button that shouldn't read as part of the item it removes. It gets the same scope as item, including depth in a nested list.

update:model-value hands back the reordered array; reorder hands back the move that produced it — the item, the index it left and the index it landed on. That's the one to send to a server, since it's a description of what changed rather than a whole list to diff.