Sortable List

InstallCopy Anchor Link

pnpm exec vegastack-design verify sortable-list

pnpm dlx shadcn@4.21.0 add @vegastack/sortable-list

UsageCopy Anchor Link

import { SortableList } from "@/components/ui/sortable-list";

<SortableList
  aria-label="Pipeline stages"
  items={stages}
  renderItem={(stage) => <span>{stage.label}</span>}
  onReorder={({ id, to }) => moveStage(id, to.index)}
/>;

SortableList is the single-list consumer of use-drag-reorder (the system's one drag-engine seam). It is controlled: items arrive in display order, onReorder requests a move, and the host applies — or refuses — it.

Each row has a drag handle, its content, optional inline actions (renderActions), and — with onRemove — a small × named Remove {label}. A host that needs more than remove passes getItemActions for a ⋯ menu named Actions for {label} (actionsLabel renames it). A row with disabled: true is locked: it keeps its place, shows no ×, and other rows move past it. layout="grid" wraps the same list into image tiles. List rows are as dense as a DataList's — compact padding and a subtle wash on hover — and the × and ⋯ show on row hover or focus, always on a touch screen.

ScopeCopy Anchor Link

ExamplesCopy Anchor Link

With inline renameCopy Anchor Link

When a row's content is a text field, drag starts only from the handle, so typing (Space included) never lifts the row. renderActions puts a delete button at the row's end.

RemoveCopy Anchor Link

onRemove(item) puts a small ghost × in each row's trailing corner, named Remove {label}. It shows on hover or focus within the row, and always on a coarse pointer (a touch screen), where there is no hover. Focus moves to the row that takes the removed row's place. A locked row shows no ×. Controls a row carries, like this "Required" checkbox from renderActions, drag with it: the drag image is a copy of the row alone.

footer is the list's one row that is not an item — an "Add a value" field and its Add button. It sits on the rows' grid: its content starts after the handle gutter and stops before the × gutter, so the field is exactly as wide as the values above it. It never drags, and it renders when the list is empty too.

header is the same kind of row above the list, full width with no gutters, for an add field whose new value is inserted first. flush drops the rows' hover wash and the side padding kept for it, so rows whose content is its own bordered control (an editable Input) run edge to edge.

align="start" pins the handle, the × and the ⋯ to a row's first line instead of its middle, for tall rows such as a card whose title line sits over an expandable body.

With row actionsCopy Anchor Link

When a row needs more than remove, getItemActions(item) returns its own RowActions — rename, delete — in a ⋯ menu: one menu per row, named Actions for {label} (Board's cards take the same accessor). No actions, no menu. A disabled action stays reachable and reads its disabledReason. They stay available on a locked row, and an action that removes its row leaves focus on the row that took its place. menuItems is the deprecated name of the same accessor.

Locked rowsCopy Anchor Link

Set disabled: true on an item to lock it. Its handle becomes a spacer of the same size, so the handles stay aligned, and it shows no ×. Its getItemActions menu stays, and lockedReason is the row's accessible description. Other rows still move past a locked row: the lock fixes the row, not the positions around it.

Image gridCopy Anchor Link

layout="grid" wraps the list into tiles at least --spacing(28) wide, as many per row as fit — or at most columns a row (2–6), fewer as the container narrows. The handle and the actions sit in the tile's top-left and top-right overlay slots. A drop lands left or right of a tile, and in keyboard move mode ←/→ step one tile while ↑/↓ step a whole row. The column count is measured, so the row step is right at any width.

PreviewCode

Landscape

Portrait 1

Portrait 2

Portrait 3

Landscape 2

Attachments in a gridCopy Anchor Link

tile="bare" drops the tile's own border and padding, so an Attachment inside is the tile's one frame — no card inside a card. The attachment keeps its own states: the progress bar while uploading, the dashed border when idle, the destructive border and message on error.

columns={4} is a cap, not a fixed count: four tiles a row on a wide container, three and then two as it narrows (never below 8.5rem a tile) — the same grid AttachmentGroup layout="tiles" uses. minTileWidth raises that floor for a wider tile: a card with a name and a meta line passes 240, one card a row on a phone and four on a desktop. columns="cards" lays the tiles on DataList's dense card grid instead — one a row, two from a 32rem list, three from 48rem and four from 72rem, 12px apart — so a sortable row of MediaCards lines up with the DataList grids around it. The drag handle ⠿ sits in the tile's top-left overlay slot and the × in its top-right one, inset from the corner on a blurred scrim; both show on hover or focus within the tile, always on a touch screen.

Give each Attachment a file and wrap the list in AttachmentPreview: a click or tap on a tile — or Enter or Space on it — opens the FileViewer, paging through every tile. That coexists with reordering because a drag starts only from the handle (or a touch long-press, which never ends in a click), and a click on the handle or the × never opens the viewer.

PreviewCode

40%

x

Upload failed.

Server-gated movesCopy Anchor Link

Return a promise from onReorder: the moved row shimmers while the write is in flight; a rejection announces the snap-back — the host never applied the move, so the order simply stays.

TouchCopy Anchor Link

On a touch screen, press and hold a row or tile for a quarter second without moving — the same long-press Board uses — and it lifts; drag it, and the drop line shows where it will land. A swipe that moves before the hold completes scrolls the page as usual, the page does not scroll under a lifted row, and the long-press menu is suppressed. The list scrolls when the finger nears its scroll container's edge.

Where the grip would sit over the content on a phone (a card's type icon), pass handle="fine": the grip shows only on a mouse or pen, and on a touch screen the long-press is the way to drag. The handle stays in the tab order and reappears while it has keyboard focus, so Space-to-move still works with a keyboard.

Drag handleCopy Anchor Link

handle="auto" shows the grip only while two or more rows can move; with one row the handle's column stays reserved but empty, so a row's content never moves when a second row arrives (a one-key SortBuilder). With flush, rows carry no hover wash and no side padding — the shape a list takes inside a popover, where the popover is the one surface.

Only the handle starts a pointer drag — the rest of the row stays free for text selection and the controls inside it. That holds even when the handle mounts after its row, such as a row that was disabled and becomes editable: the row's drag source is rebuilt around the handle as it is now.

API ReferenceCopy Anchor Link

ItemCopy Anchor Link

AccessibilityCopy Anchor Link

• Every reorder is reachable three ways: pointer drag on the handle, a touch long-press on the row, and the keyboard move mode (Space lifts, arrows commit one announced step at a time, Escape ends).
• Each step announces through a polite live region ("Moved to position 2 of 3"); a refused move announces "Move rejected — position restored".
• Handles, remove buttons and menu triggers are named per row ("Reorder Alpha", "Remove Alpha", "Actions for Alpha"); drop position shows as a 2px indicator line, and a lifted row dims. The × is always shown on a coarse pointer.
• A locked row has no handle, only a hidden spacer, and no ×; lockedReason is its description.

Do / Don'tCopy Anchor Link