Rows or cards a person puts in order by drag, keyboard or Move buttons, announcing each move.
<p>Drag a row by its grip; or press Space on the grip, move it with the arrow keys and press Space to drop it (Escape puts it back); or use Move up and Move down. The page hears the new order and writes it below.</p>
<div class="sortable-sample">
<ol class="cap-sortable" data-cap="sortable-list" aria-label="Scenes in 01 The riverbed" id="scenes">
<li class="cap-sortable-item" data-value="low-water">
<button type="button" class="cap-sortable-handle" aria-describedby="sort-help"><svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" aria-hidden="true" focusable="false"><circle cx="6" cy="3.5" r="1.25"/><circle cx="10" cy="3.5" r="1.25"/><circle cx="6" cy="8" r="1.25"/><circle cx="10" cy="8" r="1.25"/><circle cx="6" cy="12.5" r="1.25"/><circle cx="10" cy="12.5" r="1.25"/></svg><span class="cap-sr-only">Move Low water</span></button>
<div class="cap-sortable-body"><span class="cap-sortable-label"><span>Low water</span></span><span class="cap-sortable-detail">Ines, 2,140 words</span></div>
<span class="cap-sortable-steps"><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="up"><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 13V3M3.5 7.5 8 3l4.5 4.5"/></svg><span class="cap-sr-only">Move Low water up</span></button><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="down"><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 3v10M3.5 8.5 8 13l4.5-4.5"/></svg><span class="cap-sr-only">Move Low water down</span></button></span>
</li>
<li class="cap-sortable-item" data-value="tracks">
<button type="button" class="cap-sortable-handle" aria-describedby="sort-help"><svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" aria-hidden="true" focusable="false"><circle cx="6" cy="3.5" r="1.25"/><circle cx="10" cy="3.5" r="1.25"/><circle cx="6" cy="8" r="1.25"/><circle cx="10" cy="8" r="1.25"/><circle cx="6" cy="12.5" r="1.25"/><circle cx="10" cy="12.5" r="1.25"/></svg><span class="cap-sr-only">Move Tracks in the limestone</span></button>
<div class="cap-sortable-body"><span class="cap-sortable-label"><span>Tracks in the limestone</span></span><span class="cap-sortable-detail">Wade, 2,610 words</span></div>
<span class="cap-sortable-steps"><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="up"><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 13V3M3.5 7.5 8 3l4.5 4.5"/></svg><span class="cap-sr-only">Move Tracks in the limestone up</span></button><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="down"><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 3v10M3.5 8.5 8 13l4.5-4.5"/></svg><span class="cap-sr-only">Move Tracks in the limestone down</span></button></span>
</li>
<li class="cap-sortable-item" data-value="notebook">
<button type="button" class="cap-sortable-handle" aria-describedby="sort-help"><svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" aria-hidden="true" focusable="false"><circle cx="6" cy="3.5" r="1.25"/><circle cx="10" cy="3.5" r="1.25"/><circle cx="6" cy="8" r="1.25"/><circle cx="10" cy="8" r="1.25"/><circle cx="6" cy="12.5" r="1.25"/><circle cx="10" cy="12.5" r="1.25"/></svg><span class="cap-sr-only">Move The ranger's notebook</span></button>
<div class="cap-sortable-body"><span class="cap-sortable-label"><span>The ranger's notebook</span></span><span class="cap-sortable-detail">Ines, 1,460 words</span></div>
<span class="cap-sortable-steps"><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="up"><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 13V3M3.5 7.5 8 3l4.5 4.5"/></svg><span class="cap-sr-only">Move The ranger's notebook up</span></button><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="down"><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 3v10M3.5 8.5 8 13l4.5-4.5"/></svg><span class="cap-sr-only">Move The ranger's notebook down</span></button></span>
</li>
<li class="cap-sortable-item" data-value="crossing">
<button type="button" class="cap-sortable-handle" aria-describedby="sort-help"><svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" aria-hidden="true" focusable="false"><circle cx="6" cy="3.5" r="1.25"/><circle cx="10" cy="3.5" r="1.25"/><circle cx="6" cy="8" r="1.25"/><circle cx="10" cy="8" r="1.25"/><circle cx="6" cy="12.5" r="1.25"/><circle cx="10" cy="12.5" r="1.25"/></svg><span class="cap-sr-only">Move Night at the crossing</span></button>
<div class="cap-sortable-body"><span class="cap-sortable-label"><span>Night at the crossing</span></span><span class="cap-sortable-detail">Wade, 980 words</span></div>
<span class="cap-sortable-steps"><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="up"><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 13V3M3.5 7.5 8 3l4.5 4.5"/></svg><span class="cap-sr-only">Move Night at the crossing up</span></button><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="down"><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 3v10M3.5 8.5 8 13l4.5-4.5"/></svg><span class="cap-sr-only">Move Night at the crossing down</span></button></span>
</li>
</ol>
<p class="cap-sr-only" id="sort-help">To move an item with the keyboard, press Space or Enter on its handle, move it with the arrow keys, and press Space or Enter to drop it. Escape puts it back.</p>
<output class="sortable-sample-out" id="scenes-out" for="scenes">Order: low-water, tracks, notebook, crossing.</output>
</div>
Installation
// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/sortable-list.css";
import { enhance } from "capsomer/behavior/sortable-list";
enhance();import "capsomer/tokens.css";
import "capsomer/sortable-list.css";
import { SortableList, SortableBoard } from "capsomer/react/sortable-list";Usage
<ol class="cap-sortable" data-cap="sortable-list" aria-label="Scenes in 01 The riverbed">
<li class="cap-sortable-item" data-value="low-water">
<button type="button" class="cap-sortable-handle" aria-describedby="sort-help"><svg aria-hidden="true">...</svg><span class="cap-sr-only">Move Low water</span></button>
<div class="cap-sortable-body"><span class="cap-sortable-label">Low water</span><span class="cap-sortable-detail">Ines, 2,140 words</span></div>
<span class="cap-sortable-steps">
<button type="submit" name="up" value="low-water" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="up" disabled>...<span class="cap-sr-only">Move Low water up</span></button>
<button type="submit" name="down" value="low-water" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="down">...<span class="cap-sr-only">Move Low water down</span></button>
</span>
<input type="hidden" name="order" value="low-water" />
</li>
</ol>
<p class="cap-sr-only" id="sort-help">To move an item with the keyboard, press Space or Enter on its handle, ...</p>import { enhance, moveId } from "capsomer/behavior/sortable-list";
enhance(); // every [data-cap="sortable-list"]
el.addEventListener("cap:sortable-change", (e) => save(e.detail.order)); // { order, id, from, to, by }; preventDefault puts it backExamples
Cards: a corkboard, rendered by the React wrapper
<p>One card per scene with its summary. In cards every arrow key means previous or next in reading order.</p>
<div class="sortable-sample" data-wide>
<div data-mount="cards"></div>
</div>
An item that is up, and one under the pointer
<p>Set from the page: a raised item with an accent edge, its grip pressed.</p>
<div class="sortable-sample">
<ol class="cap-sortable" aria-label="Lifted and dragged">
<li class="cap-sortable-item" data-lifted>
<button type="button" class="cap-sortable-handle" aria-pressed="true" id="lifted-handle"><svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" aria-hidden="true" focusable="false"><circle cx="6" cy="3.5" r="1.25"/><circle cx="10" cy="3.5" r="1.25"/><circle cx="6" cy="8" r="1.25"/><circle cx="10" cy="8" r="1.25"/><circle cx="6" cy="12.5" r="1.25"/><circle cx="10" cy="12.5" r="1.25"/></svg><span class="cap-sr-only">Move Rain at Glen Rose</span></button>
<div class="cap-sortable-body"><span class="cap-sortable-label" id="lifted-label">Rain at Glen Rose</span><span class="cap-sortable-detail" id="lifted-detail">Up by keyboard</span></div>
</li>
<li class="cap-sortable-item" data-dragging>
<button type="button" class="cap-sortable-handle" aria-pressed="false"><svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" aria-hidden="true" focusable="false"><circle cx="6" cy="3.5" r="1.25"/><circle cx="10" cy="3.5" r="1.25"/><circle cx="6" cy="8" r="1.25"/><circle cx="10" cy="8" r="1.25"/><circle cx="6" cy="12.5" r="1.25"/><circle cx="10" cy="12.5" r="1.25"/></svg><span class="cap-sr-only">Move The second set</span></button>
<div class="cap-sortable-body"><span class="cap-sortable-label"><span>The second set</span></span><span class="cap-sortable-detail">Under the pointer</span></div>
</li>
<li class="cap-sortable-item">
<button type="button" class="cap-sortable-handle" aria-pressed="false" id="hover-handle"><svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" aria-hidden="true" focusable="false"><circle cx="6" cy="3.5" r="1.25"/><circle cx="10" cy="3.5" r="1.25"/><circle cx="6" cy="8" r="1.25"/><circle cx="10" cy="8" r="1.25"/><circle cx="6" cy="12.5" r="1.25"/><circle cx="10" cy="12.5" r="1.25"/></svg><span class="cap-sr-only">Move The flood line</span></button>
<div class="cap-sortable-body"><span class="cap-sortable-label"><span>The flood line</span></span><span class="cap-sortable-detail">Grip under the pointer</span></div>
</li>
</ol>
</div>
Lists that share a group: items move between them
<p>Two lists with the same <code>data-group</code>. Drag a grip into the other list, press Space on a grip and an arrow past the end of its list, or choose the list in the item's select. Remove asks the page first (<code>cap:sortable-remove</code>); with <code>data-alt-keys</code>, Alt and an arrow anywhere in an item moves it too.</p>
<div class="sortable-sample">
<h3 class="sortable-sample-lane">Talks</h3>
<ol class="cap-sortable" data-cap="sortable-list" data-group="program" data-alt-keys data-list="talks" aria-label="Talks" id="talks">
<li class="cap-sortable-item" data-value="t1">
<button type="button" class="cap-sortable-handle" aria-describedby="group-help"><svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" aria-hidden="true" focusable="false"><circle cx="6" cy="3.5" r="1.25"/><circle cx="10" cy="3.5" r="1.25"/><circle cx="6" cy="8" r="1.25"/><circle cx="10" cy="8" r="1.25"/><circle cx="6" cy="12.5" r="1.25"/><circle cx="10" cy="12.5" r="1.25"/></svg><span class="cap-sr-only">Move Getting started</span></button>
<div class="cap-sortable-body"><span class="cap-sortable-label"><span>Getting started</span></span></div>
<span class="cap-sortable-steps"><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="up"><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 13V3M3.5 7.5 8 3l4.5 4.5"/></svg><span class="cap-sr-only">Move Getting started up</span></button><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="down"><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 3v10M3.5 8.5 8 13l4.5-4.5"/></svg><span class="cap-sr-only">Move Getting started down</span></button><label class="cap-sr-only" for="to-t1">Move Getting started to</label><select id="to-t1" class="cap-select" data-size="sm" data-cap-part="move-to"><option value="talks" selected>Talks</option><option value="posters">Posters</option></select><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-cap-part="remove">Remove<span class="cap-sr-only"> Getting started</span></button></span>
</li>
<li class="cap-sortable-item" data-value="t2">
<button type="button" class="cap-sortable-handle" aria-describedby="group-help"><svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" aria-hidden="true" focusable="false"><circle cx="6" cy="3.5" r="1.25"/><circle cx="10" cy="3.5" r="1.25"/><circle cx="6" cy="8" r="1.25"/><circle cx="10" cy="8" r="1.25"/><circle cx="6" cy="12.5" r="1.25"/><circle cx="10" cy="12.5" r="1.25"/></svg><span class="cap-sr-only">Move Release notes</span></button>
<div class="cap-sortable-body"><span class="cap-sortable-label"><span>Release notes</span></span></div>
<span class="cap-sortable-steps"><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="up"><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 13V3M3.5 7.5 8 3l4.5 4.5"/></svg><span class="cap-sr-only">Move Release notes up</span></button><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="down"><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 3v10M3.5 8.5 8 13l4.5-4.5"/></svg><span class="cap-sr-only">Move Release notes down</span></button><label class="cap-sr-only" for="to-t2">Move Release notes to</label><select id="to-t2" class="cap-select" data-size="sm" data-cap-part="move-to"><option value="talks" selected>Talks</option><option value="posters">Posters</option></select><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-cap-part="remove">Remove<span class="cap-sr-only"> Release notes</span></button></span>
</li>
<li class="cap-sortable-empty">Empty. Drag an abstract here.</li>
</ol>
<h3 class="sortable-sample-lane">Posters</h3>
<ol class="cap-sortable" data-cap="sortable-list" data-group="program" data-alt-keys data-list="posters" aria-label="Posters" id="posters">
<li class="cap-sortable-item" data-value="p1">
<button type="button" class="cap-sortable-handle" aria-describedby="group-help"><svg viewBox="0 0 16 16" width="16" height="16" fill="currentColor" aria-hidden="true" focusable="false"><circle cx="6" cy="3.5" r="1.25"/><circle cx="10" cy="3.5" r="1.25"/><circle cx="6" cy="8" r="1.25"/><circle cx="10" cy="8" r="1.25"/><circle cx="6" cy="12.5" r="1.25"/><circle cx="10" cy="12.5" r="1.25"/></svg><span class="cap-sr-only">Move Field notes</span></button>
<div class="cap-sortable-body"><span class="cap-sortable-label"><span>Field notes</span></span></div>
<span class="cap-sortable-steps"><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="up"><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 13V3M3.5 7.5 8 3l4.5 4.5"/></svg><span class="cap-sr-only">Move Field notes up</span></button><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="down"><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 3v10M3.5 8.5 8 13l4.5-4.5"/></svg><span class="cap-sr-only">Move Field notes down</span></button><label class="cap-sr-only" for="to-p1">Move Field notes to</label><select id="to-p1" class="cap-select" data-size="sm" data-cap-part="move-to"><option value="talks">Talks</option><option value="posters" selected>Posters</option></select><button type="button" class="cap-btn" data-variant="quiet" data-size="sm" data-cap-part="remove">Remove<span class="cap-sr-only"> Field notes</span></button></span>
</li>
<li class="cap-sortable-empty">Empty. Drag an abstract here.</li>
</ol>
<p class="cap-sr-only" id="group-help">To move an item with the keyboard, press Space or Enter on its handle, move it with the arrow keys, and press Space or Enter to drop it. Escape puts it back.</p>
<output class="sortable-sample-out" id="group-out">No move yet.</output>
</div>
Repeatable rows in React: add, remove, put in order
<p>Rows with fields of their own, kept by the page as a plain array; <code>useRows</code> gives each row an id that follows it, so what is typed in a row moves with it. Add puts focus in the new row's first field; Remove puts it on the next row; at three rows Add is off; at none the list says so.</p>
<div class="sortable-sample">
<div data-mount="hosts"></div>
</div>
A site's own rows: no grip, Up and Down in words, no box, a red Remove, an excluded row, the site's own checkbox
<p>Props (<code>grip={false}</code>, <code>steps="labeled"</code>, <code>itemClassName</code>, <code>renderControls</code>) and tokens (<code>--sortable-item-border</code>, <code>--sortable-item-bg</code>, <code>--sortable-item-pad</code>, <code>--sortable-remove-ink</code>) only.</p>
<div class="sortable-sample">
<div data-mount="own"></div>
</div>
Steps as cards: a head line, Alt and an arrow, the list's own words
<p>The stack layout puts the grip, the head and the buttons over the content. Alt and Up or Down anywhere in a step moves it, and the list says "Moved to step 2 of 3." in its host's words.</p>
<div class="sortable-sample">
<div data-mount="steps"></div>
</div>
Sections in React: items between lists, and locked
<p>A board of three lists. Locking it (a published book) leaves the order with no grip and no buttons.</p>
<div class="sortable-sample" data-wide>
<div data-mount="sections"></div>
</div>
As delivered with no script: a form the server reorders
<p>Move up and Move down are submit buttons (<code>up=<id></code>, <code>down=<id></code>), and every item posts its id as <code>order</code>, so Save order sends the whole list. The ends' buttons are disabled.</p>
<form class="sortable-sample sortable-sample-form" method="post" action="#reorder" id="reorder-form">
<ol class="cap-sortable" aria-label="Posts in Field notes from the Paluxy">
<li class="cap-sortable-item" data-value="fn-1">
<div class="cap-sortable-body"><span class="cap-sortable-label"><span>Reading a trackway</span></span></div>
<span class="cap-sortable-steps"><button type="submit" name="up" value="fn-1" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="up" disabled><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 13V3M3.5 7.5 8 3l4.5 4.5"/></svg><span class="cap-sr-only">Move Reading a trackway up</span></button><button type="submit" name="down" value="fn-1" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="down"><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 3v10M3.5 8.5 8 13l4.5-4.5"/></svg><span class="cap-sr-only">Move Reading a trackway down</span></button></span>
<input type="hidden" name="order" value="fn-1" />
</li>
<li class="cap-sortable-item" data-value="fn-2">
<div class="cap-sortable-body"><span class="cap-sortable-label"><span>What the river keeps</span></span></div>
<span class="cap-sortable-steps"><button type="submit" name="up" value="fn-2" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="up"><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 13V3M3.5 7.5 8 3l4.5 4.5"/></svg><span class="cap-sr-only">Move What the river keeps up</span></button><button type="submit" name="down" value="fn-2" class="cap-btn" data-variant="quiet" data-size="sm" data-icon-only data-cap-part="down" disabled><svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M8 3v10M3.5 8.5 8 13l4.5-4.5"/></svg><span class="cap-sr-only">Move What the river keeps down</span></button></span>
<input type="hidden" name="order" value="fn-2" />
</li>
</ol>
<button type="submit" class="cap-btn" name="intent" value="save-order">Save order</button>
</form>
Rows in React, inside a form
<p>The React wrapper with <code>name="order"</code>: hidden fields and submit buttons, as a server renders it; with script the moves happen in place and the page saves the order.</p>
<div class="sortable-sample">
<div data-mount="rows"></div>
</div>
API reference
SortableList
| Prop | Type | Required | Does |
|---|---|---|---|
items | readonly T[] | Yes | |
onReorder | (order: string[], move: SortMove) => void | Yes | |
onAdd | () => void | Add: a button under the list that calls onAdd (the host appends the item), then says so and puts focus in the new item's first field. Off at max items. | |
addLabel | string | ||
max | number | ||
aria-label | string | ||
aria-labelledby | string | ||
getId | (item: T) => string | Yes | |
getLabel | (item: T) => string | Yes | The words a person knows the item by: "Move {label}", "Picked up {label}". |
renderItem | (item: T, state: SortState) => ReactNode | Yes | The item's own content, beside the handle and the buttons. No drag handle of its own. |
renderHead | (item: T, state: SortState) => ReactNode | A line between the handle and the buttons, in the item's head: "Step 3", an item's title. In the "cards" and "stack" layouts the head sits over the content. | |
layout | Layout | "rows" (the default), "cards" (a wrapping grid) or "stack" (a card per line, the head over the content, for an item whose body is fields). | |
messages | Partial<SortMessages> | Says what the list says in the host's own words: any of the sentences in sortText. | |
altKeys | boolean | Alt and Up or Down anywhere in an item moves it one place, as the buttons do (not from a select, where Alt+Down opens it). The buttons name the shortcut with aria-keyshortcuts. | |
readOnly | boolean | Shows the order with no handle and no buttons: a published book, a locked list. | |
busy | boolean | A move or save is under way: every control is disabled. | |
onRemove | (id: string, at: { index: number; list: string }) => void | Remove: a button after Move down. onRemove hears it; the list says so and puts focus on the next item. Not offered at min items or fewer. | |
min | number | ||
empty | ReactNode | Said in place of an empty list: "No hosts yet." | |
start | number | The first number of the ordered list (start of the ol). | |
name | string | The form field name for the order; turns the buttons into submit buttons. | |
className | string | ||
steps | "quiet" | "bordered" | "labeled" | How Move up and Move down are drawn: "quiet" icon buttons (the default), "bordered" icon buttons, or "labeled" bordered buttons with the words Up and Down. | |
grip | boolean | The grip; on by default. Off, the item has no drag handle and moves by its buttons (and Alt and an arrow, with altKeys). | |
itemClassName | (item: T, state: SortState) => string | undefined | A class of the site's own on an item, for a state it draws (an excluded entry). | |
renderControls | (item: T, state: SortState) => ReactNode | The site's own controls in the item's buttons, after the steps and the move-to select and before Remove (a checkbox, say). | |
renderFoot | (item: T, state: SortState) => ReactNode | A part after the buttons, the item's full width: an "Edit item" disclosure that belongs under the item's title and its buttons rather than beside them. | |
removeStyle | "quiet" | "bordered" | How Remove is drawn: "quiet" (the default, bare words) or "bordered" (a boxed button). |
SortableBoard
| Prop | Type | Required | Does |
|---|---|---|---|
lanes | readonly SortLane<T>[] | Yes | |
onMove | (lists: Lists, move: BoardMove) => void | Yes | Every list's new order, and what moved. The host saves it. |
renderLaneHead | (lane: SortLane<T>) => ReactNode | The heading or heading and note above a list's items. Wrapped in the list's section. | |
moveTo | boolean | A select in each item to move it to another list: the one-pointer way across lists (WCAG 2.5.7). On by default. | |
laneClassName | string | ((lane: SortLane<T>) => string | undefined) | A class of the site's own on a list's section (.cap-sortable-lane), for its look. | |
aria-label | string | ||
getId | (item: T) => string | Yes | |
getLabel | (item: T) => string | Yes | The words a person knows the item by: "Move {label}", "Picked up {label}". |
renderItem | (item: T, state: SortState) => ReactNode | Yes | The item's own content, beside the handle and the buttons. No drag handle of its own. |
renderHead | (item: T, state: SortState) => ReactNode | A line between the handle and the buttons, in the item's head: "Step 3", an item's title. In the "cards" and "stack" layouts the head sits over the content. | |
layout | Layout | "rows" (the default), "cards" (a wrapping grid) or "stack" (a card per line, the head over the content, for an item whose body is fields). | |
messages | Partial<SortMessages> | Says what the list says in the host's own words: any of the sentences in sortText. | |
altKeys | boolean | Alt and Up or Down anywhere in an item moves it one place, as the buttons do (not from a select, where Alt+Down opens it). The buttons name the shortcut with aria-keyshortcuts. | |
readOnly | boolean | Shows the order with no handle and no buttons: a published book, a locked list. | |
busy | boolean | A move or save is under way: every control is disabled. | |
onRemove | (id: string, at: { index: number; list: string }) => void | Remove: a button after Move down. onRemove hears it; the list says so and puts focus on the next item. Not offered at min items or fewer. | |
min | number | ||
empty | ReactNode | Said in place of an empty list: "No hosts yet." | |
start | number | The first number of the ordered list (start of the ol). | |
name | string | The form field name for the order; turns the buttons into submit buttons. | |
className | string | ||
steps | "quiet" | "bordered" | "labeled" | How Move up and Move down are drawn: "quiet" icon buttons (the default), "bordered" icon buttons, or "labeled" bordered buttons with the words Up and Down. | |
grip | boolean | The grip; on by default. Off, the item has no drag handle and moves by its buttons (and Alt and an arrow, with altKeys). | |
itemClassName | (item: T, state: SortState) => string | undefined | A class of the site's own on an item, for a state it draws (an excluded entry). | |
renderControls | (item: T, state: SortState) => ReactNode | The site's own controls in the item's buttons, after the steps and the move-to select and before Remove (a checkbox, say). | |
renderFoot | (item: T, state: SortState) => ReactNode | A part after the buttons, the item's full width: an "Edit item" disclosure that belongs under the item's title and its buttons rather than beside them. | |
removeStyle | "quiet" | "bordered" | How Remove is drawn: "quiet" (the default, bare words) or "bordered" (a boxed button). |
Functions
| Function | Signature | Does |
|---|---|---|
useRows | <V>(value: readonly V[], onChange: (next: V[]) => void): { items: Row<V>[]; getId: (r: Row<V>) => string; onReorder: (order: string[]) => void; onRemove: (id: string) => void; } | Stable ids for rows a host keeps as a plain array (a form's repeatable rows, with no id of their own). The ids follow each row as the list moves and removes them, so a row keeps its fields and its focus; a row the host adds gets a new one. Give rows.items to the list with rows.getId, rows.onReorder and rows.onRemove; onChange receives the new array. |
moveId | (order: readonly string[], id: string, to: number): string[] | The order with id moved to position to (clamped to the list). |
indexAtPoint | (others: readonly Box[], x: number, y: number, layout?: Layout): number | Where an item dragged to (x, y) belongs, from the boxes of the other items in their current order. Rows: how many other rows have their middle above the pointer. Cards (a wrapping grid): how many other cards come before the pointer in reading order, that is above its line, or on its line and left of it. Counting the others, never the dragged item, keeps the answer steady as the list rearranges under the pointer. |
locate | (lists: Lists, id: string): { list: string; index: number; } | null | Where an id is: its list and its zero-based place in it, or null. |
moveBetween | (lists: Lists, id: string, toList: string, to: number): Lists | The lists with id taken out of wherever it is and put in toList at to (clamped). Neither the input nor an unknown id's lists are changed. |
keyMove | (key: string, at: { list: number; index: number; }, sizes: readonly number[]): { list: number; index: number; } | null | The place a key moves an item that is up to, across lists: the position in its own list as keyTarget gives it, and at either end of the list the same arrow goes on into the end of the list before it or the start of the one after. sizes are the lengths of the lists in order, list the position of the item's list among them. Null for a key that does not move it. |
keyTarget | (key: string, index: number, count: number): number | null | The position a key moves a lifted item to, or null for a key that does not move it. In cards every arrow is "previous" or "next" in reading order. |
moveNode | (parent: Element, node: Element, ref: Node | null): void | Puts node into parent before ref (null: at the end). Where the browser has moveBefore (Chrome 133, Firefox 144; not Safari) the node keeps its state while it moves: focus, a running transition, an open popover. Elsewhere it is the usual remove and insert, after which the caller puts focus back (Modern Web Guidance, move-dom-element-without-losing-state). |
startPointerDrag | (down: PointerEvent, h: DragHandlers, threshold?: number): void | |
announcer | (el: HTMLElement): { region: HTMLElement; made: boolean; } | The polite live region for a list: [data-cap-part="announce"] beside it, made when missing. |
groupOf | (el: HTMLElement): HTMLElement[] | The lists an item may move between: the ones that share this list's data-group, in document order; the list alone with none. |
placeItem | (item: HTMLElement, to: number): void | Puts item at position to of its own list by moving its neighbors around it, never the item itself, so the handle or button that has focus keeps it. |
placeIn | (item: HTMLElement, list: HTMLElement, to: number): void | Puts item at position to of list, which may be another list of its group. Across lists the item itself moves (moveNode keeps its focus where the browser has moveBefore, and the caller puts focus back elsewhere); within one the neighbors move around it. |
createSortableList | (el: HTMLElement): SortableList | |
enhance | (root?: ParentNode): () => void | Attaches to every [data-cap="sortable-list"] under root not yet marked data-cap-ready. Returns a function that detaches them all. |
CSS variables
| Variable | Default |
|---|---|
--cap-btn-fs | set by the page |
--sortable-add-gap | var(--space-3) |
--sortable-body-basis | auto |
--sortable-body-pad-inline | calc(var(--pad-card) - var(--space-2)) |
--sortable-card-pad | var(--space-2) var(--space-2) var(--pad-card) |
--sortable-card-radius | var(--radius-l) |
--sortable-empty-border | var(--line-w) dashed var(--line-strong) |
--sortable-empty-pad | var(--space-4) |
--sortable-foot-gap | var(--sortable-item-gap, var(--space-2)) |
--sortable-gap | var(--space-2) |
--sortable-item-align | center |
--sortable-item-bg | var(--surface) |
--sortable-item-border | var(--line-w) solid var(--line) |
--sortable-item-gap | var(--space-2) |
--sortable-item-pad | var(--space-1) |
--sortable-item-radius | var(--radius-m) |
--sortable-item-wrap | nowrap |
--sortable-lane-bg | none |
--sortable-lane-border | 0 |
--sortable-lane-pad | 0 |
--sortable-lane-radius | 0 |
--sortable-remove-fs | var(--cap-btn-fs) |
--sortable-remove-hover-ink | var(--text) |
--sortable-remove-ink | var(--sortable-step-ink, var(--muted)) |
--sortable-remove-pad-inline | calc(var(--pad-x) - 1px) |
--sortable-remove-weight | var(--weight-medium) |
--sortable-step-ink | var(--muted) |
--sortable-steps-gap | var(--space-1) |
Parts and data attributes
| Class | Is |
|---|---|
.cap-sortable | the root |
.cap-sortable-board | a part |
.cap-sortable-body | a part |
.cap-sortable-detail | a part |
.cap-sortable-empty | a part |
.cap-sortable-foot | a part |
.cap-sortable-handle | a part |
.cap-sortable-head | a part |
.cap-sortable-item | a part |
.cap-sortable-label | a part |
.cap-sortable-lane | a part |
.cap-sortable-steps | a part |
| Attribute | Values |
|---|---|
data-cap-part | add remove |
data-dragging | present or absent |
data-has-head | present or absent |
data-layout | cards stack |
data-lifted | present or absent |
data-readonly | present or absent |
data-sorting | present or absent |
| State | Read from |
|---|---|
:disabled | the platform |
:focus-visible | the platform |
:hover | the platform |
[aria-pressed="true"] | an attribute |
Accessibility
| Key | Does |
|---|---|
| Space, Enter on a grip | Picks the item up; again, drops it where it is |
| Up arrow, Left arrow | While up: one place earlier |
| Down arrow, Right arrow | While up: one place later |
| Home, End | While up: to the start, to the end |
| Escape | While up: puts it back where it was |
| Alt+Up, Alt+Down | With data-alt-keys, anywhere in an item: moves it one place, keeping focus (ignored in a select) |
| Down past the last item | While up in a group: into the next list, at its start |
| Tab | Grip, then Move up, then Move down, then the next item |
- An ordered list (
ol) named byaria-labeloraria-labelledby, so its length and each item's place are read. - The grip is a button named "Move {label}", described by the one help line, with
aria-pressedwhile the item is up. Move up and Move down are buttons named "Move {label} up" and "Move {label} down", disabled at the ends. - The move-to select is named "Move {label} to"; Remove is "Remove {label}", Add is "Add {noun}". Each list has its own live region, which says "Added ...", "Removed ... N left." and moves between lists as "Moved {label} to {list}: position n of m."
- Moves are said in a
role="status"region that exists before it changes. - The grip takes touch for dragging (
touch-action: none) only on itself, so the page still scrolls under a finger anywhere else.