With Drag Drop

Drag and Drop — Implementation Guidance

Custom pointer-driven dragging, built directly (not native HTML5 draggable/dataTransfer — that's a separate, OS-integrated mechanism this skill does not cover, and no third-party dependency is required for anything below). One core engine, extended per scenario — not several competing approaches to pick between. Apply Core Rules to everything you build; The Core Engine describes the shared shape; Extending the Engine covers each scenario.

The Core Engine

Every scenario below is the same three-part shape, just configured differently:

1. Activators — whatever starts/moves/ends the gesture. A pointer activator (pointerdown/move/up, gated by a distance or delay threshold) is the default; a keyboard activator (Space/Enter to pick up, arrow keys to move, Escape to cancel) drives the same start/move/end lifecycle so keyboard operability is architected in, not bolted on afterward.
2. Modifiers — an ordered pipeline of pure functions the raw delta passes through before it's applied: restrict-to-bounds, snap-to-grid, aspect-ratio lock, min/max size. Order matters — each modifier sees the previous modifier's already-adjusted values, not the raw pointer position.
3. Position model — a base (the resting value, changed only at gesture start/end) and an offset (the live delta, changed continuously during the gesture, folded back to zero the instant it ends). See Core Rules for why these stay separate.

A free-drag element is this engine with no modifiers. A resize handle is this engine tracking width/height instead of x/y. A sortable list is this engine plus a swap/shift strategy function. A drop zone is this engine plus a collision-detection function against registered targets. Build the engine once; each scenario in Extending the Engine is a small addition to it, not a separate system.

Core Rules

These apply everywhere in the engine — a naive implementation of any one of these has broken working code in production, including this exact project's own feedback-widget FAB earlier the same day.

• NEVER animate top/left/width/height on every frame of a live drag Instead: Track the drag delta in a transform: translate3d(x, y, 0) on top of a stable base position. A single one-shot CSS transition on left/top after the drag ends (e.g. snapping to an edge) is fine — that's one style recalculation, not one per pointermove. Why: transform is compositor-only (GPU, no layout/paint); animating box-model properties on every pointer-move event forces layout every frame and janks under load.

• NEVER set both top+bottom (or left+right) while height/width is auto Instead: When switching a live-tracked element to an absolute resting position (e.g. after a drag snaps to an edge), explicitly cancel the unused pair (bottom: auto; right: auto;). Why: CSS resolves this as over-constrained by solving for the missing dimension — the box stretches to fill the gap between the two anchors instead of sizing to content. A leftover bottom class combined with a newly-set top will silently stretch the element to fill the viewport.

• NEVER represent "resting position" and "live drag delta" with the same property Instead: Keep them as two separate values — a base position (left/top, updated only at drag start/end) and a transform delta (updated continuously during the drag, reset to zero when folded into the base). Change only one of the two in any given reactive update. Why: Updating both in the same tick to represent one animated transition (e.g. "jump the base and compensate with an equal-and-opposite transform offset, then animate the offset back to zero") is fragile — if the two values ever commit to the DOM in separate paints, the element visibly flashes to the un-compensated position for a frame.

• NEVER use event.offsetX/event.offsetY as the drag reference point Instead: Compute deltas from event.clientX/clientY relative to the pointer's own position at drag start, or relative to a fixed container's getBoundingClientRect(). Why: offsetX/offsetY are relative to whichever element is currently under the cursor — as the pointer crosses child elements mid-drag, the reference frame silently changes underneath you, corrupting the computed delta.

• NEVER treat any pointer movement as the start of a drag Instead: Require a distance threshold (typically 1–10px of movement, or a short delay for long-press activation) before calling it a drag. Below threshold, let the native click fire normally. Why: Without a threshold, the sub-pixel movement inherent in any real click misfires as a drag, and legitimate click handlers on the same element never fire.

• NEVER rely only on mouseleave or a same-element mouseup to end a drag Instead: Use the Pointer Events API and call element.setPointerCapture(event.pointerId) on drag start; handle pointercancel identically to pointerup. Also end the drag on the window's blur event (alt-tab, a native file picker or dialog stealing focus mid-drag) — capture doesn't help here since the pointer never actually released. Why: Without capture, releasing the pointer outside the original element never fires that element's mouseup/pointerup — the drag gets stuck "on" until the cursor re-enters, then resumes unexpectedly. mouseleave-as-cancel is a symptom fix; pointer capture removes the underlying problem, but neither one fires on a focus-stealing interrupt — that needs its own blur handler.

• NEVER wire mouse events only Instead: Use Pointer Events (pointerdown/pointermove/pointerup/pointercancel) — one API unifies mouse, touch, and pen. If Pointer Events aren't available, wire mouse and touch event pairs explicitly, and filter the synthetic mouse events browsers fire ~300–500ms after a touch (check event.timeStamp deltas) so touch drags don't double-fire. Set touch-action: none on the draggable element so the browser's own scroll/pinch/long-press gestures don't fight the drag. Why: Mouse-only handlers are silently broken on every touchscreen — no error, the element just doesn't drag.

• NEVER leave listeners or timers attached past the component's lifetime Instead: Track every addEventListener (especially window/document-level ones added during drag start) and remove them on drag end and on unmount; clear any setTimeout/requestAnimationFrame handles the same way. Why: Leaked document-level listeners keep firing after the component is gone, causing phantom state updates or drags on unrelated later interactions.

• NEVER ship a pointer-only activator for content reordering Instead: Give the engine a second activator — keyboard (Space/Enter to pick up, arrow keys to move, Space/Enter to drop, Escape to cancel) — sharing the exact same start/move/end lifecycle as the pointer activator, plus an aria-live region announcing state changes. Why: Pointer-only dragging is unusable for keyboard and screen-reader users. This is the gap that's easiest to skip because the pointer path alone looks "done."

Extending the Engine

MANDATORY READ before implementing any of these — references/patterns.md has the full worked engine plus every extension below.