State attributes and inline style
Every state a wrapper has is a data-dnd attribute on your element, present or absent, and the only inline style it writes is structural.
A wrapper exposes its state on the element it wraps, as data-dnd-* attributes and ARIA. A
boolean attribute is present (empty) or absent, never "false". The names are namespaced, so
wrapping another primitive never collides with its own attributes (Dockable's data-dragging,
Grid Layout's data-dragging).
Parts and ids
Every element a wrapper touches carries data-dnd-part: draggable, handle, droppable,
overlay, sortable, sortable-group or swappable. A draggable, a droppable, a sortable and a
swappable item also carry data-dnd-id, the id they were given (as a string); a
SortableGroup carries its group there. Stacked wrappers list their parts (data-dnd-part="draggable droppable"; select with
[data-dnd-part~="droppable"]). Tests and tooling select by them, never by class names.
States
| attribute | on | when |
|---|---|---|
data-dnd-dragging | draggable, sortable, swappable, its handle | it is the source of the drag in progress |
data-dnd-disabled | draggable, sortable, swappable, its handle, droppable, sortable group | disabled is set |
data-dnd-handle | handle | always: it is a drag handle |
data-dnd-active | droppable | a drag runs that this droppable would accept (its scope, its accepts) |
data-dnd-over | droppable | an accepted source hovers it, and no drop middleware vetoes it |
data-dnd-refused | droppable | a source hovers it that its accepts, or a drop middleware, refuses |
data-dnd-sorting | sortable, sortable group | its group takes part in a sort in progress: the source's group, or one that accepts it |
data-dnd-swap-target | swappable | it is the item the drag would swap with now; written by the core, never rendered |
aria-disabled="true" | draggable, sortable, swappable, its handle, droppable, sortable group | disabled is set |
aria-describedby | draggable, sortable, swappable, handle | only when the app passes describedBy |
A droppable is never both over and refused. A refused hover never reports onDrop.
data-dnd-sorting is rendered by React at a sort's start and end only; data-dnd-swap-target is
written by the core with the target's shift, so a swap preview commits nothing.
The same state in functions
className and style take a value or a function of the state, and so does render:
<Droppable id="done" className={(state) => (state.refused ? "column column-refused" : "column")}>
<section aria-label="Done" />
</Droppable>| part | state |
|---|---|
Draggable, DragHandle | { dragging, disabled } |
Droppable | { over, active, refused, disabled } |
Sortable | { dragging, sorting, disabled } |
SortableGroup | { sorting, disabled } |
Swappable | { dragging, disabled } |
DragOverlay | { operation }: the drag it shows |
Inline style is structural only
The packages ship no CSS. The only inline style they write:
| style | on | why |
|---|---|---|
translate | the dragged element, during a drag | it follows the pointer; the CSS translate property, never transform, so it composes with a host that owns transform |
translate | a sort's shifted items, a swap's target | the preview: each moved from its box at rest, never a DOM move |
touch-action: none | a drag handle | a touch on the handle drags, never scrolls |
position: fixed, left, top, width, height, box-sizing, pointer-events: none | DragOverlay's box | it sits where the dragged box is, inert to the pointer |
translate is written once per animation frame at most, and cleared after your onDrop and
onDragEnd run, back to the inline value the element had. A draggable with translate={false}
is never moved. Everything else, the look of a dragged item, the placeholder, the cursor, the
z-index and the transitions, is yours.
Capability entries
Each capability is its own import, so an app's bundle carries only what it uses. What each entry holds, and what it costs on a production build.
Sensors and activation
One Pointer Events path for mouse, touch and pen, when a press becomes a drag, what cancels it, which elements never start one, and how presses are claimed.