FragiolaDnD
Documentation
API (@fragiola/dnd-react)

Draggable

The wrapper that makes its single child draggable by pointer and keyboard, with no provider. Every prop, its state, attributes and events.

Draggable makes the one element it wraps draggable, by mouse, touch, pen and the keyboard. It renders no element of its own, registers its element in its document's drag space, and adds data-dnd-* attributes, ARIA and, during a drag, a translate.

card.tsx
import { Draggable } from "@fragiola/dnd-react/draggable";

<Draggable id={task.id} type="task" data={task} onDragEnd={(event) => log(event.operation)}>
    <article aria-label={task.title}>{task.title}</article>
</Draggable>;

Props

proptypedefault
idstring | numberrequiredunique within its scope; reported as operation.source.id
typestringwhat a droppable's accepts list matches
dataunknownanything the app wants back in the events (operation.source.data)
scopestringthe default scopeonly droppables of the same scope meet it
spaceDragSpaceits document'san explicit space from createDragSpace
disabledbooleanfalsestarts no drag; cancels the one in progress
activation{ distance?, delay?, tolerance? }3 px; touch 200 ms within 5 pxwhen a press becomes a drag (sensors)
keyboard{ step?, mode?: "step" | "targets" }25 px, "step"how the arrows move it
autoScrollAutoScrollopt-in auto-scroll, from autoScroll()
collisionCollisionStrategypointerWithinhow the target is found (collision)
translatebooleantruewhether the element follows the pointer; false when a DragOverlay shows it
describedBystringthe id of the element describing how to drag it (aria-describedby)
onDragStart(event: DragStartEvent) => voidthe drag started, past the activation; operation.target is the droppable it starts over
onDragMove(event: DragMoveEvent) => voidthe dragged box moved, at most once per frame
onDragEnd(event: DropEvent) => voidit was released, on a target or not (event.operation.target)
onDragCancel(event: DragCancelEvent) => voidit was cancelled: nothing dropped
classNamestring | (state) => string | undefinedadded to the element's own
styleCSSProperties | (state) => CSSProperties | undefinedmerged over the element's own; structural keys win
renderReactElement | (props, state) => ReactElementthe element, when there is no child to wrap
refRef<HTMLElement>merged with the wrapper's and the child's
childrenone elementthe element made draggable; it must forward ref and props

Any other prop is forwarded to the element, so Draggable is itself a valid child of another wrapper.

State

{ dragging: boolean; disabled: boolean }, given to className, style and render.

Attributes

attributewhen
data-dnd-part="draggable"always
data-dnd-idalways: the id, as a string
data-dnd-draggingit is the source of the drag in progress
data-dnd-disabled, aria-disabled="true"disabled
aria-describedbydescribedBy is set
tabindex="0"set on the activator when it is not focusable already

Events

Each callback receives { type, operation, input }, where operation is an immutable snapshot:

field
phase"dragging", "dropping" (during the drop callbacks), or "idle" (a cancel)
scopethe scope the source and its droppables share
source{ id, type?, data? }
target{ id, data? }: the hovered droppable that accepts the source; none for a refused hover
pointerthe pointer now (for the keyboard, the centre of the dragged box)
deltahow far the pointer moved since the start
rects{ source, drag, target? }: the source's box at the start, where it is dragged now, the target's
input"pointer" or "keyboard"

On a release, the droppable's onDrop runs first, then the draggable's onDragEnd, then the page-wide listeners, and only then is the translate cleared: an app that moves the element in its own state never sees it jump.

Deviations to know

  • An onMouseDown on the draggable does not run: the press is claimed on pointerdown. Use onPointerDown. See the press claim.
  • The wrapper adds no role and no name: give the element its accessible name.
Hello DnD
Gallery