Skip to content

Sortable list

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();

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 back

Examples

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=&lt;id&gt;</code>, <code>down=&lt;id&gt;</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

PropTypeRequiredDoes
itemsreadonly T[]Yes
onReorder(order: string[], move: SortMove) => voidYes
onAdd() => voidAdd: 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.
addLabelstring
maxnumber
aria-labelstring
aria-labelledbystring
getId(item: T) => stringYes
getLabel(item: T) => stringYesThe words a person knows the item by: "Move {label}", "Picked up {label}".
renderItem(item: T, state: SortState) => ReactNodeYesThe item's own content, beside the handle and the buttons. No drag handle of its own.
renderHead(item: T, state: SortState) => ReactNodeA 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.
layoutLayout"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).
messagesPartial<SortMessages>Says what the list says in the host's own words: any of the sentences in sortText.
altKeysbooleanAlt 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.
readOnlybooleanShows the order with no handle and no buttons: a published book, a locked list.
busybooleanA move or save is under way: every control is disabled.
onRemove(id: string, at: { index: number; list: string }) => voidRemove: 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.
minnumber
emptyReactNodeSaid in place of an empty list: "No hosts yet."
startnumberThe first number of the ordered list (start of the ol).
namestringThe form field name for the order; turns the buttons into submit buttons.
classNamestring
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.
gripbooleanThe 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 | undefinedA class of the site's own on an item, for a state it draws (an excluded entry).
renderControls(item: T, state: SortState) => ReactNodeThe 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) => ReactNodeA 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

PropTypeRequiredDoes
lanesreadonly SortLane<T>[]Yes
onMove(lists: Lists, move: BoardMove) => voidYesEvery list's new order, and what moved. The host saves it.
renderLaneHead(lane: SortLane<T>) => ReactNodeThe heading or heading and note above a list's items. Wrapped in the list's section.
moveTobooleanA select in each item to move it to another list: the one-pointer way across lists (WCAG 2.5.7). On by default.
laneClassNamestring | ((lane: SortLane<T>) => string | undefined)A class of the site's own on a list's section (.cap-sortable-lane), for its look.
aria-labelstring
getId(item: T) => stringYes
getLabel(item: T) => stringYesThe words a person knows the item by: "Move {label}", "Picked up {label}".
renderItem(item: T, state: SortState) => ReactNodeYesThe item's own content, beside the handle and the buttons. No drag handle of its own.
renderHead(item: T, state: SortState) => ReactNodeA 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.
layoutLayout"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).
messagesPartial<SortMessages>Says what the list says in the host's own words: any of the sentences in sortText.
altKeysbooleanAlt 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.
readOnlybooleanShows the order with no handle and no buttons: a published book, a locked list.
busybooleanA move or save is under way: every control is disabled.
onRemove(id: string, at: { index: number; list: string }) => voidRemove: 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.
minnumber
emptyReactNodeSaid in place of an empty list: "No hosts yet."
startnumberThe first number of the ordered list (start of the ol).
namestringThe form field name for the order; turns the buttons into submit buttons.
classNamestring
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.
gripbooleanThe 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 | undefinedA class of the site's own on an item, for a state it draws (an excluded entry).
renderControls(item: T, state: SortState) => ReactNodeThe 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) => ReactNodeA 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

FunctionSignatureDoes
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): numberWhere 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; } | nullWhere an id is: its list and its zero-based place in it, or null.
moveBetween(lists: Lists, id: string, toList: string, to: number): ListsThe 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; } | nullThe 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 | nullThe 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): voidPuts 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): voidPuts 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): voidPuts 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): () => voidAttaches to every [data-cap="sortable-list"] under root not yet marked data-cap-ready. Returns a function that detaches them all.

CSS variables

VariableDefault
--cap-btn-fsset by the page
--sortable-add-gapvar(--space-3)
--sortable-body-basisauto
--sortable-body-pad-inlinecalc(var(--pad-card) - var(--space-2))
--sortable-card-padvar(--space-2) var(--space-2) var(--pad-card)
--sortable-card-radiusvar(--radius-l)
--sortable-empty-bordervar(--line-w) dashed var(--line-strong)
--sortable-empty-padvar(--space-4)
--sortable-foot-gapvar(--sortable-item-gap, var(--space-2))
--sortable-gapvar(--space-2)
--sortable-item-aligncenter
--sortable-item-bgvar(--surface)
--sortable-item-bordervar(--line-w) solid var(--line)
--sortable-item-gapvar(--space-2)
--sortable-item-padvar(--space-1)
--sortable-item-radiusvar(--radius-m)
--sortable-item-wrapnowrap
--sortable-lane-bgnone
--sortable-lane-border0
--sortable-lane-pad0
--sortable-lane-radius0
--sortable-remove-fsvar(--cap-btn-fs)
--sortable-remove-hover-inkvar(--text)
--sortable-remove-inkvar(--sortable-step-ink, var(--muted))
--sortable-remove-pad-inlinecalc(var(--pad-x) - 1px)
--sortable-remove-weightvar(--weight-medium)
--sortable-step-inkvar(--muted)
--sortable-steps-gapvar(--space-1)

Parts and data attributes

ClassIs
.cap-sortablethe root
.cap-sortable-boarda part
.cap-sortable-bodya part
.cap-sortable-detaila part
.cap-sortable-emptya part
.cap-sortable-foota part
.cap-sortable-handlea part
.cap-sortable-heada part
.cap-sortable-itema part
.cap-sortable-labela part
.cap-sortable-lanea part
.cap-sortable-stepsa part
AttributeValues
data-cap-partadd remove
data-draggingpresent or absent
data-has-headpresent or absent
data-layoutcards stack
data-liftedpresent or absent
data-readonlypresent or absent
data-sortingpresent or absent
StateRead from
:disabledthe platform
:focus-visiblethe platform
:hoverthe platform
[aria-pressed="true"]an attribute

Accessibility

KeyDoes
Space, Enter on a gripPicks the item up; again, drops it where it is
Up arrow, Left arrowWhile up: one place earlier
Down arrow, Right arrowWhile up: one place later
Home, EndWhile up: to the start, to the end
EscapeWhile up: puts it back where it was
Alt+Up, Alt+DownWith data-alt-keys, anywhere in an item: moves it one place, keeping focus (ignored in a select)
Down past the last itemWhile up in a group: into the next list, at its start
TabGrip, then Move up, then Move down, then the next item
  • An ordered list (ol) named by aria-label or aria-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-pressed while 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.