Drag and drop
On this page
phApp.sortable() makes lists people can reorder, and boards where cards move between columns.
It works with a mouse, touch and the keyboard, and announces each move to screen readers. It's
built on SortableJS.
Add ph-app-sortable.js after ph-app.js on pages with drag and drop:
<script defer src="https://app.performancehub.co/assets/app-kit/v1/ph-app-sortable.js"></script>
Board


Figure 1: A board where cards move between columns
<div class="ph-board">
<div class="ph-board-column">
<h3 class="ph-board-column-header" id="col-todo">To do</h3>
<ul class="ph-board-list" aria-labelledby="col-todo" data-status="todo">
<li class="ph-board-card" data-id="t1">Order art supplies</li>
<li class="ph-board-card" data-id="t2">Laminate science posters</li>
</ul>
</div>
<div class="ph-board-column">
<h3 class="ph-board-column-header" id="col-doing">In progress</h3>
<ul class="ph-board-list" aria-labelledby="col-doing" data-status="doing">
<li class="ph-board-card" data-id="t4">Mark Year 6 projects</li>
</ul>
</div>
</div>
phApp.sortable('.ph-board-list', {
group: 'jobs',
onMove: ({ id, to, newIndex }) =>
phApp.fetchJSON(`api/tasks/${id}`, { method: 'PATCH', body: { status: to.dataset.status, position: newIndex } }),
});
Lists with the same group share items.
List


Figure 2: A reorderable list, with the focused item ready to pick up
<ul class="ph-sortable-list" aria-labelledby="order-title">
<li data-id="a">Warm-up</li>
<li data-id="b">Strength circuit</li>
<li data-id="c">Conditioning</li>
<li data-id="d">Stretch</li>
</ul>
const order = phApp.sortable('.ph-sortable-list', {
onMove: () => saveOrder(order.order()), // ['a', 'c', 'b', 'd']
});
Every item needs a data-id. Name each list with aria-labelledby or aria-label; the name is
used in announcements ("position 2 of 4 in In progress").
Options
| Option | Default | What it does |
|---|---|---|
group | none | Lists with the same group can move items between them |
handle | the whole item | A selector for a drag handle inside each item, such as .ph-sortable-handle |
disabled | false | Turns dragging off |
onMove | none | Called after every reorder or move, by mouse, touch or keyboard |
onMove gets { item, id, from, to, oldIndex, newIndex }: the element moved, its data-id, the
lists it came from and went to, and its old and new positions.
phApp.sortable() takes a selector, an element or a list of elements, and returns
{ lists, order(list?), destroy() }. order() gives the data-ids of the first list, or of
list, in their current order.
Keyboard
| Key | Action |
|---|---|
| Tab | Moves to an item |
| Space or Enter | Picks up the item, or drops it |
| Up and Down arrows | Move it (Left and Right in horizontal lists) |
| Left and Right arrows | Move it to the next list, on a board |
| Escape | Cancels and puts it back |
Screen readers hear "Press Space to pick up. Use the arrow keys to move, Space to drop, Escape to cancel." and each move, such as "Mark Year 6 projects moved to position 1 of 2 in Done."
On touch screens, hold an item briefly before dragging, so the page still scrolls.
React
import { SortableList } from 'ph-app-kit-react/sortable';
<SortableList
aria-label="Class running order"
items={steps}
getKey={(step) => step.id}
renderItem={(step) => step.name}
onReorder={setSteps}
/>
In React, onReorder gives the reordered items, and the kit leaves the DOM to React.
Guidelines
- Save after every move, and put the item back with a toast if the save fails.
- Say in the description that items can be dragged.
- For long lists or exact positions, offer a "Move to…" menu too.