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

A kanban board with three columnsA kanban board with three columns

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

A reorderable list with one item focusedA reorderable list with one item focused

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

OptionDefaultWhat it does
groupnoneLists with the same group can move items between them
handlethe whole itemA selector for a drag handle inside each item, such as .ph-sortable-handle
disabledfalseTurns dragging off
onMovenoneCalled 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

KeyAction
TabMoves to an item
Space or EnterPicks up the item, or drops it
Up and Down arrowsMove it (Left and Right in horizontal lists)
Left and Right arrowsMove it to the next list, on a board
EscapeCancels 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.