FragiolaDnD
Documentation
API (@fragiola/dnd-react)

Swappable

The wrapper that makes its single child an item that swaps places with another, by pointer and keyboard. Every prop, its attributes and the event.

Swappable makes the one element it wraps an item that swaps with the items of its group, and of the groups that accept it. It renders no element of its own. A swappable item is both a drag source and a drop target of its space.

tiles.tsx
import { Swappable, swapItems } from "@fragiola/dnd-react/swappable";

{tiles.map((tile, index) => (
    <Swappable
        key={tile.id}
        id={tile.id}
        index={index}
        group="tiles"
        onSwap={({ source, target }) => target && setTiles((now) => swapItems(now, source.index, target.index))}
    >
        <div aria-label={tile.name} className="tile data-dnd-swap-target:outline" />
    </Swappable>
))}

Props

proptypedefault
idstring | numberrequiredunique within its scope; also its drop target id
indexnumberrequiredits place in its group's list, from 0, reported in the swap event
groupstringrequiredthe items it swaps with, within its scope (its own group's always)
typestringwhat a plain droppable's accepts list matches
dataunknownanything the app wants back in the events
scopestringthe default scopeonly swappables and droppables of the same scope meet it
spaceDragSpaceits document'san explicit space from createDragSpace
disabledbooleanfalseneither drags nor swaps
acceptsstring[] | (source: SwapSource) => booleanits own groupthe other groups whose items it swaps with
activation{ distance?, delay?, tolerance? }3 px; touch 200 ms within 5 pxwhen a press becomes a drag
autoScrollAutoScrollopt-in auto-scroll, from autoScroll()
translatebooleantruewhether it follows the pointer; false when a DragOverlay shows it, and it moves to the target's place instead
describedBystringthe id of the element describing how to swap it (aria-describedby)
onSwap(event: SwapEvent) => voiddropped (on a target or not) or cancelled
className, style, render, ref, childrenas on Draggable, with the swappable's state

Any other prop is forwarded to the element. DragHandle, re-exported from this entry, works inside a Swappable.

The event

swap-event.ts
interface SwapEvent {
    type: "swap";
    source: { id: string | number; group: string; index: number };
    target?: { id: string | number; group: string; index: number };
    canceled: boolean;
    operation: DragOperation;
    input: "pointer" | "keyboard";
}

There is no target when the item was dropped over no other swappable item (an item is never a target of its own drag), when a drop middleware vetoed it, and when it was cancelled. Apply it with swapItems or swapBetween. The core clears the shifts after onSwap.

State

{ dragging: boolean; disabled: boolean }, given to className, style and render. A swappable item re-renders when its drag starts and ends; the preview renders nothing.

Attributes

attributewhenwritten by
data-dnd-part="swappable"alwaysReact
data-dnd-idalways: the id, as a stringReact
data-dnd-draggingit is the item draggedReact
data-dnd-swap-targetit is the item the drag would swap with now, shifted into the source's placethe core, with its translate
data-dnd-disabled, aria-disabled="true"disabledReact
aria-describedbydescribedBy is setReact

data-dnd-swap-target is written by the core, never rendered by React, so a swap preview commits nothing.

Swap between groups
Gallery

useSwappable

useSwappable(options) takes the props above that are options and returns { state, props }: spread props onto one element.

tile.tsx
const { state, props } = useSwappable({ id, index, group: "tiles", onSwap });
return <div {...props} className={state.dragging ? "tile lifted" : "tile"} />;

In the core

registerSwappable(element, options) takes the same options without describedBy, plus handle, and returns a registration (update, unregister, getState, subscribe).