Swappable

About

Works as Sortable does, with a mouse, a finger or the keyboard, except that an item dropped on another swaps the two rather than shifting the ones between: the right shape for a grid of tiles or a set of slots, where every other item should stay put.

The container's children are the items, or the elements data-swappable-items selects, and data-swappable-handle limits where a drag can start. From the keyboard, Space or Enter picks up the focused item, the arrow keys swap it with the previous or next one, Space or Enter drops it and Escape undoes the swap. Containers with the same data-swappable-group swap with each other. swappable:change fires once a drop has swapped two items.

Usage

Register the component and the framework loads it the first time a page contains [data-swappable].

import { Parallelogram } from '@parallelogram-js/core';

const app = Parallelogram.create();
app.components.add('[data-swappable]', () => import('@parallelogram-js/core/components/Swappable'));
app.run();

The framework is optional. Swappable.enhanceAll() mounts the component on every matching element by itself, for a page that wants one enhancement rather than a framework:

import Swappable from '@parallelogram-js/core/components/Swappable';

Swappable.enhanceAll();

It takes a selector and the component's options, and returns the instance it mounted them with. What it leaves out is what the framework adds: loading a component only on the pages that use it, mounting again after a page swap, and ordering with dependsOn.

Its styles come from the package stylesheet:

@import '@parallelogram-js/core/styles/draggable.css';

Acknowledgements

Swappable is built on Shopify Draggable, used under the MIT licence. Copyright (c) 2018-present Shopify.

The drag engine, its Mirror, Scrollable and Focusable plugins, and the Sortable, Swappable and Droppable behaviour are ported from Draggable 1.2. A single Pointer Events sensor replaces its mouse, touch and force-touch sensors, the keyboard sensor is new, and state is written to data attributes rather than classes. Thank you to Shopify and Draggable's contributors for the work this builds on.