Design a Drag and Drop System

Building drag and drop interactions that work across input devices, handle complex reordering scenarios, and maintain accessibility—the browser APIs, architectural patterns, and trade-offs that power production implementations in Trello, Notion, and Figma.

Drag and drop appears simple: grab an element, move it, release it. In practice, it requires handling three incompatible input APIs (mouse, touch, pointer), working around significant browser inconsistencies in the HTML5 Drag and Drop API, providing keyboard alternatives for accessibility, and managing visual feedback during the operation. This article covers the underlying browser APIs, the design decisions that differentiate library approaches, and how production applications solve these problems at scale.

Abstract

Drag and drop systems must unify three input models while providing an accessible non-drag alternative. The core mental model:

• Native HTML5 DnD has critical limitations: The WHATWG Drag and Drop API works for mouse and pen input but does not fire drag events for touch on Chrome, Firefox, or Safari¹. The DataTransfer object is governed by a strict three-mode lifecycle (read/write during dragstart, protected during intermediate events, read-only during drop)², and historic browser drift around drag-image handling and event ordering makes raw API usage impractical for production.

• Pointer Events unify input devices: The W3C Pointer Events Level 2 Recommendation (with Level 3 Candidate Recommendation in flight) gives a single hardware-agnostic event stream for mouse, touch, and pen. Pointer-Events-based libraries (dnd-kit, React Aria) sidestep HTML5 DnD entirely; the trade-off is losing OS-level features like cross-window drag.

• The two camps split on the API question, not the framework: HTML5 DnD wrappers (react-dnd, Sortable.js, Pragmatic Drag and Drop) inherit native cross-window drag and file drops but inherit native quirks too. Pointer Events implementations (dnd-kit, React Aria) get touch and keyboard for free but cannot accept files dragged from the OS without a separate native code path.

• Accessibility means a single-pointer alternative, not just keyboard: WCAG 2.5.7 Dragging Movements (Level AA, added in WCAG 2.2) specifically requires a non-drag mechanism operable by a single pointer. Keyboard support is required by WCAG 2.1.1 but does not satisfy 2.5.7 on its own — you must also expose a click/tap path (move buttons, context menu, etc.).

The Challenge

Browser API Fragmentation

The web has three overlapping APIs for pointer input, each with different capabilities and browser support.

HTML5 Drag and Drop API (WHATWG spec): Designed for mouse-based desktop interaction. Events: dragstart, drag, dragenter, dragover, dragleave, drop, dragend. The DataTransfer object carries data between drag source and drop target.

Touch Events API (W3C spec, now considered legacy): Designed for touchscreens. Events: touchstart, touchmove, touchend, touchcancel. Provides multi-touch support via TouchList collections.

Pointer Events API (W3C spec): Unified model for all pointing devices. Events mirror mouse events with pointer prefix. The pointerType property indicates device: "mouse", "touch", or "pen".

The fundamental problem: HTML5 Drag and Drop events do not fire for touch input on Chrome, Firefox, or Safari¹. Native drag is mouse- and pen-only; touch users get nothing without an explicit second code path or a polyfill such as drag-drop-touch-js/dragdroptouch.

HTML5 DnD API Quirks

The native API has behavior differences that break naive cross-browser implementations.

DataTransfer is governed by a three-mode lifecycle. The WHATWG drag data store mode is, in order:

Practically, this means: set everything you need in dragstart, gate drop targets in dragover by inspecting dataTransfer.types, and read payloads in drop. The protected mode exists to stop a malicious page from spying on data the user is dragging in from another origin or another application².

The spec pins drop before dragend, but engines historically drifted. Step 2 of the WHATWG drag-and-drop processing model fires drop at the target; step 3 fires dragend at the source. Older Chrome/Safari builds fired dragend before drop³, and the order can still surface bugs across long-tail user-agents. Treat them as a commit/cleanup pair, not a sequence — write idempotent handlers, and never gate drop’s persistence on state mutated in dragend (or vice versa).

Drag image requirements differ by engine:

• Firefox accepts any DOM element for setDragImage().
• Chromium requires the element to be in the DOM and have layout when setDragImage is called⁴.
• Safari has historically required the source to be visible enough to snapshot.

Show 3 hidden lines4  data: Record<string, string>5  dragImage?: HTMLElement6}78function setupNativeDrag({ element, data, dragImage }: DragSourceOptions): void {9  element.draggable = true1011  element.addEventListener("dragstart", (e) => {12    // Must set data in dragstart - only chance13    Object.entries(data).forEach(([type, value]) => {14      e.dataTransfer?.setData(type, value)15    })1617    // Chrome requires element in DOM for custom drag image18    if (dragImage) {19      document.body.appendChild(dragImage)Show 6 hidden lines26  })27}

Drop target acceptance: Drop targets must call preventDefault() in both dragenter and dragover to signal they accept drops. Missing either causes the browser to reject the drop.

Touch Challenges

Touch interaction differs fundamentally from mouse:

No hover state: Touch has no equivalent to mouseover. Drag preview must follow the finger, not appear on hover.

Scroll conflicts: Touch movement is overloaded—it scrolls by default. Drag operations must prevent scrolling while allowing intentional scrolls.

Gesture disambiguation: Is this touch a tap, a scroll, or a drag? Activation delays or distance thresholds help distinguish intent.

Multi-touch complexity: What happens when a second finger touches during a drag? Most implementations ignore additional touches; some support multi-select.

Accessibility Requirements

WCAG 2.5.7 Dragging Movements (Level AA, added in WCAG 2.2) is the normative bar:

“All functionality that uses a dragging movement for operation can be achieved by a single pointer without dragging, unless dragging is essential, or the functionality is determined by the user agent and not modified by the author.”

Why dragging is problematic:

• Users with motor impairments may not be able to hold and move simultaneously.
• Head pointers, eye-gaze systems, and trackballs make sustained drags difficult or impossible.
• Screen reader users cannot perceive spatial relationships through visual feedback.

Acceptable single-pointer (2.5.7) alternatives:

• Click-based “move”: click item, then click destination slot.
• Move menu invoked by right-click or long-press, with a list of valid destinations.
• Up/down arrow buttons next to each item for list reordering.
• Numeric position field where users type the new position.

Keyboard (2.1.1) alternative — required in addition to the above:

• Tab to focus the item, Enter or Space to grab, Arrow keys to move, Enter or Space to drop, Escape to cancel.

Scale Factors

The right drag-drop approach depends on use case complexity:

Browser APIs Deep Dive

HTML5 Drag and Drop

The native API provides drag operations with OS-level integration—dragging files from desktop, cross-tab dragging, and native drag previews.

Event sequence for a successful drop (per the WHATWG drag-and-drop processing model):

1dragstart (source) → drag (source, repeating) →2dragenter (target) → dragover (target, repeating) →3drop (target) → dragend (source)

The spec pins drop (step 2) before dragend (step 3) inside the processing model, but historic browser drift around the pair is real (see HTML5 DnD API Quirks). Treat them as a commit/cleanup pair and write idempotent handlers.

DataTransfer security model: The protected mode described above exists so that a malicious page cannot read data the user is dragging from another origin or another application during dragover. Scripts can still enumerate the available formats (dataTransfer.types), which is exactly what drop targets need to decide whether to accept the drop.

Show 5 hidden lines6    e.dataTransfer!.effectAllowed = "move"7    e.dataTransfer!.setData("application/x-item-id", itemId)8    e.dataTransfer!.setData("text/plain", itemId) // Fallback for external drops910    element.classList.add("dragging")11  })1213  element.addEventListener("dragend", () => {14    element.classList.remove("dragging")15  })16}1718function createDropTarget(element: HTMLElement, onDrop: (itemId: string, position: "before" | "after") => void): void {19  element.addEventListener("dragenter", (e) => {20    e.preventDefault() // Required to allow drop21    element.classList.add("drop-target")22  })2324  element.addEventListener("dragover", (e) => {25    e.preventDefault() // Required for every dragover26    e.dataTransfer!.dropEffect = "move"27  })2829  element.addEventListener("dragleave", () => {30    element.classList.remove("drop-target")31  })3233  element.addEventListener("drop", (e) => {34    e.preventDefault()Show 7 hidden lines

Effect feedback: effectAllowed (source) and dropEffect (target) communicate what operations are valid:

Pointer Events

Pointer Events Level 2 is a W3C Recommendation; Level 3 is currently a Candidate Recommendation. The spec defines a pointer as “a hardware-agnostic representation of input devices that can target a specific coordinate (or set of coordinates) on a screen”. One unified API covers mouse, touch, and pen, with multi-pointer tracking via pointerId.

Key properties beyond mouse events:

Pointer capture: Redirect all pointer events to a specific element, even when pointer moves outside. Critical for drag operations.

Show 5 hidden lines6  currentX: number7  currentY: number8  element: HTMLElement9}1011let dragState: PointerDragState | null = null1213function setupPointerDrag(element: HTMLElement): void {14  element.addEventListener("pointerdown", (e) => {15    // Only handle primary pointer16    if (!e.isPrimary) return1718    // Capture pointer to receive events even outside element19    element.setPointerCapture(e.pointerId)2021    dragState = {22      pointerId: e.pointerId,23      startX: e.clientX,24      startY: e.clientY,25      currentX: e.clientX,26      currentY: e.clientY,27      element,28    }2930    element.classList.add("dragging")31  })3233  element.addEventListener("pointermove", (e) => {34    if (!dragState || e.pointerId !== dragState.pointerId) return3536    dragState.currentX = e.clientX37    dragState.currentY = e.clientY3839    // Update visual positionShow 11 hidden lines5152    // Determine drop target at final position53    const dropTarget = document.elementFromPoint(e.clientX, e.clientY)54    // Handle drop logic...5556    dragState = null57  })5859  // Cancel on pointer lost (e.g., touch cancelled by palm rejection)60  element.addEventListener("pointercancel", (e) => {61    if (!dragState || e.pointerId !== dragState.pointerId) return6263    element.releasePointerCapture(e.pointerId)64    element.classList.remove("dragging")65    element.style.transform = ""66    dragState = null67  })68}

Touch-action CSS: Control which touch gestures the browser handles vs. your code.

1.draggable {2  /* Disable browser touch handling - we'll manage it */3  touch-action: none;4}56.scrollable-container {7  /* Allow vertical scroll, we handle horizontal drag */8  touch-action: pan-y;9}

Touch Events (Legacy)

Touch Events Level 2 was published as a W3C Community Group Final Report in 2024 and is explicitly designated a legacy API by the W3C Touch Events Community Group, which “strongly encourages adoption of Pointer Events”. They remain relevant only for multi-touch scenarios that genuinely need direct touch list semantics, or for code that still has to support older non-Pointer-Events browsers.

TouchList collections:

• touches: All current touch points on screen
• targetTouches: Touch points on the event target element
• changedTouches: Touch points that changed in this event

Show 3 hidden lines45  element.addEventListener(6    "touchstart",7    (e) => {8      // Use first touch only9      if (e.touches.length !== 1) return10      startTouch = e.touches[0]1112      element.classList.add("dragging")13    },14    { passive: false },15  )1617  element.addEventListener(18    "touchmove",19    (e) => {20      if (!startTouch) return2122      // Prevent scrolling during drag23      e.preventDefault()2425      const touch = e.touches[0]26      const deltaX = touch.clientX - startTouch.clientX27      const deltaY = touch.clientY - startTouch.clientY2829      element.style.transform = `translate(${deltaX}px, ${deltaY}px)`Show 11 hidden lines41    // Find drop target42    const dropTarget = document.elementFromPoint(touch.clientX, touch.clientY)43    // Handle drop...4445    startTouch = null46  })4748  element.addEventListener("touchcancel", () => {49    element.classList.remove("dragging")50    element.style.transform = ""51    startTouch = null52  })53}

Passive event listener caveat: Touch event listeners are passive by default in modern browsers for scroll performance. To preventDefault() (required to prevent scrolling during drag), explicitly set { passive: false }.

Design Paths

Path 1: Native HTML5 DnD with Touch Backend

Architecture: Use HTML5 Drag and Drop API for desktop, add separate touch event handling for mobile.

1Desktop: element → dragstart/dragover/drop → DataTransfer → drop handler2Mobile:  element → touchstart/touchmove/touchend → custom state → drop handler

How it works:

1. Set draggable="true" on elements
2. Handle native drag events for mouse interaction
3. Detect touch devices and add touch event listeners
4. Maintain unified drop target registry for both paths

Best for:

• Cross-tab or cross-window dragging (only native DnD supports this)
• File drops from desktop
• Simple list reordering with existing touch library

Implementation complexity:

Device/network profile:

• Works well on: Desktop browsers, modern mobile with touch backend
• Struggles on: Complex nested drag targets, virtualized lists

Trade-offs:

• Pro: Native OS integration (cross-window drag, file drops)
• Pro: Browser-managed drag preview
• Con: Two code paths to maintain
• Con: DataTransfer quirks across browsers
• Con: No touch support without additional library

Real-world example: Sortable.js uses this approach — native DnD on desktop with a touch adapter. ~14.7 kB gzipped (v1.15.6, per Bundlephobia), no framework dependency.

Path 2: Custom Pointer Events Implementation

Architecture: Bypass native DnD entirely. Build drag system on Pointer Events for consistent cross-device behavior.

1pointerdown → capture → pointermove (throttled) → hit test drop targets → pointerup → commit

How it works:

1. Listen for pointerdown on draggable elements
2. Capture pointer to receive events outside element bounds
3. Track position via pointermove, update preview position
4. Hit-test drop targets using document.elementFromPoint()
5. Commit changes on pointerup

Best for:

• Consistent behavior across all input types
• Complex drag interactions (nested lists, kanban boards)
• Applications requiring fine-grained control

Implementation complexity:

Trade-offs:

• Pro: Single code path for all devices
• Pro: Full control over drag preview and feedback
• Pro: No DataTransfer timing issues
• Con: No cross-window drag support
• Con: Must implement file drop separately
• Con: More code to write/maintain

Real-world example: dnd-kit uses this architecture. Its sensor system abstracts input types — PointerSensor, MouseSensor, TouchSensor, KeyboardSensor — and the PointerSensor explicitly avoids the HTML5 Drag and Drop API in favor of native PointerEvents. Built-in accessibility with keyboard navigation and screen reader announcements. @dnd-kit/core is ~14.2 kB gzipped per Bundlephobia; a sortable setup with @dnd-kit/sortable and @dnd-kit/modifiers runs closer to ~25 kB.

Path 3: Hybrid with Library Abstraction

Architecture: Use library that abstracts backend differences. Declarative API, implementation details hidden.

1<Draggable> → Library internals → Backend (HTML5/Touch/Keyboard) → <Droppable>

How it works:

1. Wrap draggable elements with library component/hook
2. Register drop targets with acceptance criteria
3. Library handles input detection and routes to appropriate backend
4. Render functions receive drag state for visual feedback

Best for:

• Teams wanting production-ready solution quickly
• Applications needing all features (keyboard, touch, mouse)
• Complex interactions without low-level concerns

Implementation complexity:

Trade-offs:

• Pro: Fastest time to production
• Pro: Maintained by community/company
• Pro: Accessibility often built-in
• Con: Bundle size overhead
• Con: Less control over edge cases
• Con: Learning library-specific patterns

Library comparison (sizes are gzipped, sourced from Bundlephobia and library docs as of 2026-Q1; treat them as orders of magnitude — your effective size depends on which sub-packages you import):

Decision Framework

Implementing Core Patterns

List Reordering

The most common drag-drop pattern: reorder items within a single list.

State management: Track source index, current hover index, and compute final order on drop.

Show 8 hidden lines9): {10  items: T[]11  dragHandlers: (index: number) => DragHandlers12  dropHandlers: (index: number) => DropHandlers13} {14  const [state, setState] = useState<SortableListState<T>>({15    items: initialItems,16    dragIndex: null,17    hoverIndex: null,18  })1920  const dragHandlers = (index: number) => ({21    onDragStart: () => {22      setState((s) => ({ ...s, dragIndex: index }))23    },24    onDragEnd: () => {25      setState((s) => {26        if (s.dragIndex === null || s.hoverIndex === null) {27          return { ...s, dragIndex: null, hoverIndex: null }28        }2930        // Reorder items31        const newItems = [...s.items]32        const [removed] = newItems.splice(s.dragIndex, 1)33        newItems.splice(s.hoverIndex, 0, removed)3435        return { items: newItems, dragIndex: null, hoverIndex: null }36      })37    },38  })3940  const dropHandlers = (index: number) => ({41    onDragEnter: () => {42      setState((s) => ({ ...s, hoverIndex: index }))43    },44  })Show 3 hidden lines

Visual indicator placement: Show drop indicator between items, not on items.

1function getDropIndicatorPosition(e: PointerEvent, element: HTMLElement): "before" | "after" {2  const rect = element.getBoundingClientRect()3  const midpoint = rect.top + rect.height / 24  return e.clientY < midpoint ? "before" : "after"5}

Drop-Target Hit Testing

Once you leave HTML5 DnD (where the browser does its own hit-testing for you), the library has to decide which droppable the active drag is “over”. There are three workable strategies, with very different cost/precision profiles.

Cross-Container Dragging

Moving items between multiple lists (Kanban boards, multi-column layouts).

Key challenge: Tracking which container an item is over, handling container-level acceptance rules.

Show 15 hidden lines16  overIndex: number | null17}1819function handleCrossContainerDrop(20  state: CrossContainerState,21  sourceItems: Map<string, unknown[]>,22  setItems: (containerId: string, items: unknown[]) => void,23): void {24  const { activeItem, overContainerId, overIndex } = state25  if (!activeItem || !overContainerId || overIndex === null) return2627  const targetContainer = state.containers.get(overContainerId)28  if (!targetContainer?.accepts(activeItem)) return2930  // Remove from source31  const sourceList = [...(sourceItems.get(activeItem.sourceContainerId) ?? [])]32  const sourceIndex = sourceList.findIndex((item: any) => item.id === activeItem.id)33  const [removed] = sourceList.splice(sourceIndex, 1)34  setItems(activeItem.sourceContainerId, sourceList)3536  // Add to target37  const targetList = [...(sourceItems.get(overContainerId) ?? [])]38  targetList.splice(overIndex, 0, removed)39  setItems(overContainerId, targetList)40}

Acceptance rules: Containers can restrict what items they accept.

1const containers: Container[] = [2  {3    id: "todo",4    accepts: (item) => item.type === "task",5  },6  {7    id: "done",8    accepts: (item) => item.type === "task" && item.status !== "blocked",9  },10  {11    id: "archive",12    accepts: () => true, // Accepts anything13  },14]

Tree Reordering

Hierarchical structures with nesting (file trees, nested lists).

Complexity factors:

• Drop zones: before sibling, after sibling, as child
• Depth detection from pointer position
• Preventing invalid drops (item into its own descendants)

Show 10 hidden lines1112function getTreeDropPosition(e: PointerEvent, element: HTMLElement, depthIndicatorWidth: number): TreeDropPosition {13  const rect = element.getBoundingClientRect()14  const relativeY = e.clientY - rect.top15  const relativeX = e.clientX - rect.left1617  const nodeId = element.dataset.nodeId!18  const currentDepth = parseInt(element.dataset.depth ?? "0")1920  // Top quarter: drop before21  if (relativeY < rect.height * 0.25) {22    return { type: "before", targetId: nodeId }23  }2425  // Bottom quarter: drop after26  if (relativeY > rect.height * 0.75) {27    return { type: "after", targetId: nodeId }28  }2930  // Middle: check horizontal position for nesting31  const hoverDepth = Math.floor(relativeX / depthIndicatorWidth)32  if (hoverDepth > currentDepth) {33    return { type: "child", parentId: nodeId }34  }3536  return { type: "after", targetId: nodeId }37}3839function isDescendant(tree: TreeNode[], nodeId: string, potentialAncestorId: string): boolean {40  const findNode = (nodes: TreeNode[], id: string): TreeNode | null => {41    for (const node of nodes) {42      if (node.id === id) return node43      const found = findNode(node.children, id)44      if (found) return found45    }46    return null47  }4849  const ancestor = findNode(tree, potentialAncestorId)50  if (!ancestor) return false5152  return findNode(ancestor.children, nodeId) !== null53}

Virtualized List Dragging

Large lists with windowing present unique challenges: elements outside viewport don’t exist in DOM.

Problem: Standard hit-testing fails when potential drop targets aren’t rendered.

Solutions:

1. Overscan: Render extra items beyond viewport. Simple but memory overhead.
2. Position-based hit testing: Calculate target from scroll position, not DOM.
3. Scroll-on-drag: Auto-scroll when dragging near edges.

Show 10 hidden lines11  const container = scrollContainerRef.current12  if (!container) return 01314  const containerRect = container.getBoundingClientRect()15  const relativeY = clientY - containerRect.top + scrollTop16  const index = Math.floor(relativeY / itemHeight)1718  return Math.max(0, Math.min(totalItems - 1, index))19}2021function handleAutoScroll(clientY: number, config: VirtualListDragConfig): void {22  const container = config.scrollContainerRef.current23  if (!container) return2425  const rect = container.getBoundingClientRect()26  const edgeThreshold = 50 // pixels27  const scrollSpeed = 102829  if (clientY < rect.top + edgeThreshold) {30    // Near top edge - scroll up31    container.scrollTop -= scrollSpeed32  } else if (clientY > rect.bottom - edgeThreshold) {33    // Near bottom edge - scroll down34    container.scrollTop += scrollSpeed35  }36}

Drag Preview and Visual Feedback

Native vs Custom Drag Images

Native drag image (HTML5 DnD): Browser captures element snapshot at dragstart. Limited customization.

1// Basic custom drag image2element.addEventListener("dragstart", (e) => {3  const preview = createCustomPreview()4  document.body.appendChild(preview)5  preview.style.position = "absolute"6  preview.style.left = "-9999px"78  // Offset positions the cursor relative to the image9  e.dataTransfer?.setDragImage(preview, 20, 20)1011  requestAnimationFrame(() => preview.remove())12})

Custom drag layer (Pointer Events approach): Render preview element that follows pointer.

Show 8 hidden lines9  if (!state.isDragging) return null;1011  return (12    <div13      style={{14        position: 'fixed',15        left: state.x,16        top: state.y,17        pointerEvents: 'none', // Don't block hit testing18        transform: 'translate(-50%, -50%) rotate(3deg)', // Slight rotation19        opacity: 0.9,20        zIndex: 999921      }}22    >23      <ItemCard item={state.item} />24    </div>25  );26}

Performance consideration: Moving a DOM element every pointermove (60+ times/second) can cause jank. Use transform instead of left/top—it’s GPU-accelerated and doesn’t trigger layout.

Drop Indicators

Visual feedback showing where the item will land.

Line indicator: Horizontal line between items.

1.drop-indicator {2  position: absolute;3  left: 0;4  right: 0;5  height: 2px;6  background: var(--color-accent);7  pointer-events: none;8}910.drop-indicator--before {11  top: -1px;12}1314.drop-indicator--after {15  bottom: -1px;16}

Placeholder gap: Reserve space where item will drop.

1function renderItems(items: Item[], dragIndex: number | null, hoverIndex: number | null) {2  return items.map((item, index) => {3    const isDragging = index === dragIndex;4    const showGapBefore = hoverIndex === index && dragIndex !== null && dragIndex > index;5    const showGapAfter = hoverIndex === index && dragIndex !== null && dragIndex < index;67    return (8      <>9        {showGapBefore && <div className="drop-gap" />}10        <ItemCard11          key={item.id}12          item={item}13          style={{ opacity: isDragging ? 0.5 : 1 }}14        />15        {showGapAfter && <div className="drop-gap" />}16      </>17    );18  });19}

Animation Patterns

Layout shift animation: Animate other items moving out of the way.

1.sortable-item {2  transition: transform 200ms ease;3}45.sortable-item--shifted-down {6  transform: translateY(var(--item-height));7}89.sortable-item--shifted-up {10  transform: translateY(calc(-1 * var(--item-height)));11}

Drop animation: Animate item settling into final position.

1async function animateDrop(2  element: HTMLElement,3  from: { x: number; y: number },4  to: { x: number; y: number },5): Promise<void> {6  const deltaX = to.x - from.x7  const deltaY = to.y - from.y89  // Start at drag position10  element.style.transform = `translate(${-deltaX}px, ${-deltaY}px)`11  element.style.transition = "none"1213  // Force reflow14  element.offsetHeight1516  // Animate to final position17  element.style.transition = "transform 200ms ease-out"18  element.style.transform = ""1920  return new Promise((resolve) => {21    element.addEventListener("transitionend", () => resolve(), { once: true })22  })23}

Accessibility Implementation

Keyboard Navigation

WCAG-compliant drag-drop requires full keyboard support.

Interaction pattern:

1. Focus item with Tab
2. Press Enter/Space to “pick up” item
3. Arrow keys or Tab to move between positions
4. Enter/Space to “drop” or Escape to cancel

Show 15 hidden lines16      // Not dragging - Enter starts drag17      if (e.key === "Enter" || e.key === " ") {18        e.preventDefault()19        setState({20          isActive: true,21          activeItemId: itemId,22          targetIndex: currentIndex,23        })24        announceToScreenReader(`Grabbed ${items[currentIndex].name}. Use arrow keys to move.`)25      }26      return27    }2829    // Currently dragging30    switch (e.key) {31      case "ArrowUp":32      case "ArrowLeft":33        e.preventDefault()34        if (state.targetIndex! > 0) {35          const newIndex = state.targetIndex! - 136          setState((s) => ({ ...s, targetIndex: newIndex }))37          announceToScreenReader(`Position ${newIndex + 1} of ${items.length}`)38        }39        break4041      case "ArrowDown":42      case "ArrowRight":43        e.preventDefault()44        if (state.targetIndex! < items.length - 1) {45          const newIndex = state.targetIndex! + 146          setState((s) => ({ ...s, targetIndex: newIndex }))47          announceToScreenReader(`Position ${newIndex + 1} of ${items.length}`)48        }49        break5051      case "Enter":52      case " ":53        e.preventDefault()54        const fromIndex = items.findIndex((i) => i.id === state.activeItemId)55        onReorder(fromIndex, state.targetIndex!)56        setState({ isActive: false, activeItemId: null, targetIndex: null })57        announceToScreenReader(`Dropped at position ${state.targetIndex! + 1}`)58        break59Show 10 hidden lines

Screen Reader Announcements

Use ARIA live regions to announce drag state changes.

1function announceToScreenReader(message: string): void {2  let announcer = document.getElementById("drag-announcer")34  if (!announcer) {5    announcer = document.createElement("div")6    announcer.id = "drag-announcer"7    announcer.setAttribute("aria-live", "assertive")8    announcer.setAttribute("aria-atomic", "true")9    announcer.style.cssText = `10      position: absolute;11      width: 1px;12      height: 1px;13      padding: 0;14      margin: -1px;15      overflow: hidden;16      clip: rect(0, 0, 0, 0);17      white-space: nowrap;18      border: 0;19    `20    document.body.appendChild(announcer)21  }2223  // Clear and set to ensure announcement24  announcer.textContent = ""25  requestAnimationFrame(() => {26    announcer!.textContent = message27  })28}

Announcement timing:

ARIA Attributes

1<!-- Draggable item -->2<div role="listitem" tabindex="0" aria-grabbed="false" aria-describedby="drag-instructions">Item content</div>34<!-- When being dragged -->5<div role="listitem" tabindex="0" aria-grabbed="true" aria-describedby="drag-instructions">Item content</div>67<!-- Drop target -->8<div role="list" aria-dropeffect="move">9  <!-- items -->10</div>1112<!-- Instructions (hidden visually) -->13<div id="drag-instructions" class="sr-only">14  Press Enter to grab. Use arrow keys to move. Press Enter to drop or Escape to cancel.15</div>

Real-World Implementations

Trello: Kanban Board

Challenge: Drag cards between multiple lists with smooth animations and real-time sync.

Approach (observable behavior; Trello has rotated through several internal libraries over the years):

• Drop zones on each card and at list bottom.
• Visual feedback: card tilts slightly during drag (the well-known “jaunty angle”).
• Optimistic updates with server reconciliation; failures roll the card back.

Technical details:

• Each card has a pos attribute exposed by the public Trello API, stored as a 64-bit floating-point number (HN discussion of the format).
• Inserting between two cards averages the neighbors’ pos values, so reorders are an O(1) API call instead of an O(n) re-index.
• When pos gaps shrink below the float-precision threshold, a background job rebalances the affected list (Hacker News thread).
• Updates broadcast to other clients via WebSocket so collaborators see moves in real time.

Key insight: Floating-point pos with rebalancing trades per-write cost for occasional bulk maintenance — a classic “fractional indexing” pattern that decouples drag UX from server load.

Notion: Block Reordering

Challenge: Every piece of content is a draggable, nestable block. Blocks can be text, images, databases, or embedded content.

Observable behavior:

• Drag handle (six dots) appears on hover.
• Multi-block selection with Shift+click; Alt/Option+drag creates a duplicate.
• Horizontal drag position determines nesting depth in toggles and lists.
• Drag preview shows a block outline, not the full content; drop indicator style changes by nesting level.

Architecture (from Notion’s “data model behind Notion” post):

• Every piece of content is a block with a UUID, a parent pointer, and an ordered list of content (child block IDs). Blocks form a render tree.
• User actions are encoded as discrete operations against that tree, batched into transactions, persisted in an append-only log on the server, and pushed to other clients over WebSockets.
• Concurrent edits are merged with a hybrid strategy: tree-structure operations lean on operation-based sync with the server as serialization point, while character-level text edits use CRDT-style merging for offline tolerance⁶.

Key insight: Notion’s drag operates on block identity, not DOM nodes. Reparenting is just a server operation that updates parent and rewrites the source and destination content arrays, which is why drags survive page reloads and collaborator edits without bespoke client code.

Figma: Canvas Objects

Challenge: Drag objects on infinite canvas with zoom, precision positioning, and multi-select.

Architecture (from Figma’s engineering blog and the Pragmatic Engineer interview with the Figma Slides team):

• Core editor is a C++ engine compiled to WebAssembly that draws to an HTML <canvas> via WebGL — and now WebGPU where supported.
• Surrounding UI (layer list, properties panel, modals) is React + TypeScript talking to the engine through a bindings layer.
• Custom hit-testing against the scene graph rather than elementFromPoint; the canvas knows nothing about DOM.

Implementation details:

• Drag threshold (a few pixels) prevents accidental moves on click.
• Snap-to-grid and smart guides are computed every frame against neighbors.
• Undo stack captures a drag as a single operation.

Key insight: For canvas-style apps, no off-the-shelf drag library covers the load-bearing path. The renderer owns coordinates, the engine owns hit-testing, and you reach for a library only on the chrome.

VS Code: File Tree and Tabs

Challenge: Drag files between explorer, editors, and terminals; also accept files dragged in from the OS.

Approach (visible in src/vs/workbench/browser/dnd.ts):

• Custom implementation built on a LocalSelectionTransfer singleton for same-window drags.
• Native HTML5 DnD for external file drops, which is the only way to receive OS file drops.
• Typed drag identifiers — DraggedEditorIdentifier for a single editor, DraggedEditorGroupIdentifier for a tab group.

Technical details:

• LocalSelectionTransfer is a singleton keyed by drag-payload type; it lets the source set typed payload data and the target read it back without going through DataTransfer (which is locked down outside dragstart/drop).
• EditorDropTarget components register as drop zones.
• The file tree supports dragging into and out of folders; tabs support reordering across editor groups.
• For extensions, the public surface area is the TreeDragAndDropController and DocumentDropEditProvider APIs, which wrap a smaller vscode.DataTransfer abstraction.

Key insight: VS Code uses two drag mechanisms in parallel — a process-local typed channel for in-app drags (avoids DataTransfer quirks) and native DataTransfer for OS interop (the only way to accept files). This is the same pattern most desktop-class web apps converge on.

Browser Constraints

Main Thread Budget

Drag operations run on main thread. Heavy operations cause jank.

Budget: 16ms per frame for 60fps. Drag handlers should complete in <8ms to leave room for rendering.

Optimization strategies:

1. Throttle pointermove: Don’t process every event
2. Debounce drop target calculations: Especially for complex hit-testing
3. RAF for visual updates: Batch position updates to animation frame
4. Avoid layout thrashing: Read dimensions before starting drag, cache them

1// Throttled drag handler2let lastMoveTime = 03const THROTTLE_MS = 16 // One frame45function handlePointerMove(e: PointerEvent): void {6  const now = performance.now()7  if (now - lastMoveTime < THROTTLE_MS) return8  lastMoveTime = now910  // Actual move handling11  updateDragPosition(e.clientX, e.clientY)12}

Touch Delay and Gesture Conflicts

The classic 300ms tap delay is essentially gone on modern mobile browsers as long as you ship a proper viewport meta tag (<meta name="viewport" content="width=device-width">) or apply touch-action: manipulation to interactive elements. Chrome documented the change in “300ms tap delay, gone away”; legacy polyfills like FastClick are no longer needed and may even hurt. Touch gestures (pan, pinch, double-tap-to-zoom) still conflict with drag, so you still need touch-action and activation constraints.

Activation constraints prevent accidental drags:

1interface ActivationConstraint {2  delay?: number // ms to hold before drag starts3  distance?: number // px to move before drag starts4  tolerance?: number // px of movement allowed during delay5}67// dnd-kit sensor configuration8const pointerSensor = useSensor(PointerSensor, {9  activationConstraint: {10    delay: 250, // Hold 250ms before drag activates11    tolerance: 5, // Allow 5px movement during delay12  },13})

Memory Considerations

Long drag operations with many drop targets can accumulate state.

Cleanup patterns:

• Clear highlight states on pointercancel
• Remove event listeners when drag ends
• Reset animations to avoid stale transforms
• Clear cached dimensions if window resizes during drag

1function cleanupDragState(): void {2  // Reset all visual states3  document.querySelectorAll(".drop-target-active").forEach((el) => {4    el.classList.remove("drop-target-active")5  })67  // Clear cached data8  dropTargetRects.clear()910  // Remove global listeners11  document.removeEventListener("pointermove", handleGlobalMove)12  document.removeEventListener("pointerup", handleGlobalUp)13}

Common Pitfalls

1. Missing preventDefault in dragover

The mistake: Only calling preventDefault() in drop handler.

1// Broken - drop never fires2element.addEventListener("drop", (e) => {3  e.preventDefault()4  handleDrop(e)5})

Why it fails: Browser requires preventDefault() in dragenter AND dragover to mark element as valid drop target. Without it, drop event never fires.

The fix:

1element.addEventListener("dragenter", (e) => e.preventDefault())2element.addEventListener("dragover", (e) => e.preventDefault())3element.addEventListener("drop", (e) => {4  e.preventDefault()5  handleDrop(e)6})

2. Drag Image Not Visible

The mistake: Creating drag image dynamically without adding to DOM.

1// Broken in Chrome2element.addEventListener("dragstart", (e) => {3  const img = document.createElement("div")4  img.textContent = "Dragging"5  e.dataTransfer?.setDragImage(img, 0, 0) // Invisible6})

Why it fails: Chrome requires the drag image element to be in the DOM and have layout. Firefox doesn’t.

The fix:

1element.addEventListener("dragstart", (e) => {2  const img = document.createElement("div")3  img.textContent = "Dragging"4  img.style.position = "absolute"5  img.style.left = "-9999px"6  document.body.appendChild(img)78  e.dataTransfer?.setDragImage(img, 0, 0)910  requestAnimationFrame(() => img.remove())11})

3. Touch Events Not Firing

The mistake: Assuming HTML5 DnD works on touch devices.

1// Only works with mouse2element.draggable = true3element.addEventListener("dragstart", handleDragStart)4// Touch users see nothing

Why it fails: HTML5 Drag and Drop API is mouse-only. Touch events don’t trigger drag events.

The fix: Use Pointer Events or add explicit touch handling:

1element.addEventListener("pointerdown", handlePointerDown)2// OR3element.addEventListener("touchstart", handleTouchStart, { passive: false })

4. Passive Event Listener Blocking preventDefault

The mistake: Touch events added without { passive: false }.

1// preventDefault has no effect2element.addEventListener("touchmove", (e) => {3  e.preventDefault() // Ignored! Scrolls anyway4  handleDrag(e)5})

Why it fails: Modern browsers make touch listeners passive by default for scroll performance. Passive listeners cannot preventDefault().

The fix:

1element.addEventListener(2  "touchmove",3  (e) => {4    e.preventDefault()5    handleDrag(e)6  },7  { passive: false },8)

5. State Desync with Optimistic Updates

The mistake: Updating UI before server confirms, then not handling failures.

1// Optimistic update without rollback2function handleDrop(fromIndex: number, toIndex: number): void {3  setItems(reorder(items, fromIndex, toIndex))4  api.updateOrder(items.map((i) => i.id)) // Fire and forget5}

Why it fails: Server rejection leaves UI in wrong state. Network failure loses the change.

The fix:

1function handleDrop(fromIndex: number, toIndex: number): void {2  const previousItems = items3  const newItems = reorder(items, fromIndex, toIndex)45  setItems(newItems) // Optimistic67  api8    .updateOrder(newItems.map((i) => i.id))9    .then((serverOrder) => setItems(serverOrder)) // Reconcile against canonical state10    .catch(() => {11      setItems(previousItems) // Rollback12      showError("Failed to save order")13    })14}

Conclusion

Drag and drop systems require unifying disparate browser APIs while maintaining accessibility. The fundamental tension: native HTML5 DnD provides OS-level integration (cross-window drag, file drops) but lacks touch support and carries real cross-browser quirks. Pointer-Events implementations provide consistent behavior across input devices but cannot accept files dragged from the OS without falling back to native DnD anyway.

Architectural decisions:

API layer: Native HTML5 DnD when you need file drops or cross-window/cross-tab drag. Pointer Events when you need consistent multi-device behavior and don’t need OS integration. Many applications want both, isolated behind a small adapter.

Library vs custom: Libraries (dnd-kit, Pragmatic Drag and Drop, react-dnd, Sortable.js, React Aria) all encode hard-won workarounds for the underlying APIs and are the right default. Custom implementation only when you have unusual requirements — canvas-based rendering, multi-pointer gestures, or extreme bundle-size constraints.

Accessibility: Not optional. WCAG 2.5.7 requires a single-pointer alternative; WCAG 2.1.1 requires a keyboard path. Build both in from the start — retrofitting is harder, and at least one (the single-pointer one) is easy to forget.

Visual feedback: Users need constant feedback during drag — drag preview follows the cursor, drop indicators show destination, animations smooth transitions. Without feedback, drag operations feel broken even when they’re working correctly.

The current production split is roughly: dnd-kit and React Aria for Pointer-Events-first React stacks; Pragmatic Drag and Drop for framework-agnostic native-DnD work; Sortable.js for tiny vanilla apps; react-dnd in legacy code that nobody is rewriting. Pick by which API you need underneath, not by feature checklist alone — that decision flows backwards into everything else, including how much accessibility code you’ll have to write yourself.

Appendix

Prerequisites

• DOM events: Event propagation, delegation, preventDefault
• CSS transforms: translate, transform-origin, GPU acceleration
• Browser input APIs: Basic familiarity with mouse, touch, or pointer events
• React hooks (if using React-based libraries)

Terminology

• DataTransfer: HTML5 DnD object carrying data between drag source and drop target
• Drag handle: UI element that initiates drag (often a grip icon)
• Drop indicator: Visual marker showing where dragged item will land
• Hit testing: Determining which element is under the pointer
• Pointer capture: API to receive all pointer events for a specific pointer ID
• Sensor: dnd-kit abstraction for input type (pointer, touch, keyboard)

Summary

• HTML5 DnD limitations: Mouse and pen only, three-mode DataTransfer lifecycle, no touch support without separate implementation, OS-level features (cross-window, file drop) only available here.
• Pointer Events advantage: Single API for mouse, touch, and pen; pointer capture for reliable drag tracking when the cursor leaves the element.
• Accessibility requirement: WCAG 2.5.7 mandates a single-pointer (click/tap) alternative; WCAG 2.1.1 requires a keyboard path. Both are required.
• Library API split: HTML5 DnD wrappers (react-dnd, Sortable.js, Pragmatic Drag and Drop) vs Pointer-Events implementations (dnd-kit, React Aria-managed pointer/touch is HTML5 underneath).
• Visual feedback: Drag preview, drop indicators, and layout-shift animations are essential for usable drag-drop.
• Real-world patterns: Trello uses fractional pos indexing with rebalancing, Notion operates on block IDs with hybrid OT/CRDT sync, Figma renders the canvas in a custom WebAssembly engine and only uses libraries on the chrome.

References

• WHATWG HTML Standard — Drag and Drop — normative HTML5 DnD spec, including the three-mode DataTransfer lifecycle.
• W3C Pointer Events Level 2 and Pointer Events Level 3 (CR) — unified pointer input specs.
• W3C Touch Events Level 2 — Community Group Final Report — Touch Events, now legacy.
• WCAG 2.5.7 Dragging Movements (WCAG 2.2, AA) and WCAG 2.1.1 Keyboard (A).
• MDN — HTML Drag and Drop API and MDN — Pointer Events.
• dnd-kit documentation and the pointer sensor reference.
• react-dnd documentation.
• Pragmatic Drag and Drop — Atlassian Design System and Atlassian’s “Designed for delight, built for performance” write-up.
• React Aria — Drag and Drop and “Taming the dragon” architecture post.
• Notion — The data model behind Notion’s flexibility.
• Figma — Rendering powered by WebGPU and Pragmatic Engineer interview on the Figma renderer.