Design a Drag and Drop System

3 collapsed lines
1
// Setting up native drag with workarounds
2
interface DragSourceOptions {
3
  element: HTMLElement
4
  data: Record<string, string>
5
  dragImage?: HTMLElement
6
}
7

8
function setupNativeDrag({ element, data, dragImage }: DragSourceOptions): void {
9
  element.draggable = true
10

11
  element.addEventListener("dragstart", (e) => {
12
    // Must set data in dragstart - only chance
13
    Object.entries(data).forEach(([type, value]) => {
14
      e.dataTransfer?.setData(type, value)
15
    })
16

17
    // Chrome requires element in DOM for custom drag image
18
    if (dragImage) {
19
      document.body.appendChild(dragImage)
6 collapsed lines
20
      dragImage.style.position = "absolute"
21
      dragImage.style.left = "-9999px"
22
      e.dataTransfer?.setDragImage(dragImage, 0, 0)
23
      // Clean up after browser captures image
24
      requestAnimationFrame(() => dragImage.remove())
25
    }
26
  })
27
}

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

5 collapsed lines
1
// Complete native drag implementation
2
function createDragSource(element: HTMLElement, itemId: string): void {
3
  element.draggable = true
4

5
  element.addEventListener("dragstart", (e) => {
6
    e.dataTransfer!.effectAllowed = "move"
7
    e.dataTransfer!.setData("application/x-item-id", itemId)
8
    e.dataTransfer!.setData("text/plain", itemId) // Fallback for external drops
9

10
    element.classList.add("dragging")
11
  })
12

13
  element.addEventListener("dragend", () => {
14
    element.classList.remove("dragging")
15
  })
16
}
17

18
function createDropTarget(element: HTMLElement, onDrop: (itemId: string, position: "before" | "after") => void): void {
19
  element.addEventListener("dragenter", (e) => {
20
    e.preventDefault() // Required to allow drop
21
    element.classList.add("drop-target")
22
  })
23

24
  element.addEventListener("dragover", (e) => {
25
    e.preventDefault() // Required for every dragover
26
    e.dataTransfer!.dropEffect = "move"
27
  })
28

29
  element.addEventListener("dragleave", () => {
30
    element.classList.remove("drop-target")
31
  })
32

33
  element.addEventListener("drop", (e) => {
34
    e.preventDefault()
7 collapsed lines
35
    const itemId = e.dataTransfer!.getData("application/x-item-id")
36
    const rect = element.getBoundingClientRect()
37
    const position = e.clientY < rect.top + rect.height / 2 ? "before" : "after"
38
    onDrop(itemId, position)
39
    element.classList.remove("drop-target")
40
  })
41
}

5 collapsed lines
1
// Pointer Events drag implementation
2
interface PointerDragState {
3
  pointerId: number
4
  startX: number
5
  startY: number
6
  currentX: number
7
  currentY: number
8
  element: HTMLElement
9
}
10

11
let dragState: PointerDragState | null = null
12

13
function setupPointerDrag(element: HTMLElement): void {
14
  element.addEventListener("pointerdown", (e) => {
15
    // Only handle primary pointer
16
    if (!e.isPrimary) return
17

18
    // Capture pointer to receive events even outside element
19
    element.setPointerCapture(e.pointerId)
20

21
    dragState = {
22
      pointerId: e.pointerId,
23
      startX: e.clientX,
24
      startY: e.clientY,
25
      currentX: e.clientX,
26
      currentY: e.clientY,
27
      element,
28
    }
29

30
    element.classList.add("dragging")
31
  })
32

33
  element.addEventListener("pointermove", (e) => {
34
    if (!dragState || e.pointerId !== dragState.pointerId) return
35

36
    dragState.currentX = e.clientX
37
    dragState.currentY = e.clientY
38

39
    // Update visual position
11 collapsed lines
40
    const deltaX = dragState.currentX - dragState.startX
41
    const deltaY = dragState.currentY - dragState.startY
42
    element.style.transform = `translate(${deltaX}px, ${deltaY}px)`
43
  })
44

45
  element.addEventListener("pointerup", (e) => {
46
    if (!dragState || e.pointerId !== dragState.pointerId) return
47

48
    element.releasePointerCapture(e.pointerId)
49
    element.classList.remove("dragging")
50
    element.style.transform = ""
51

52
    // Determine drop target at final position
53
    const dropTarget = document.elementFromPoint(e.clientX, e.clientY)
54
    // Handle drop logic...
55

56
    dragState = null
57
  })
58

59
  // Cancel on pointer lost (e.g., touch cancelled by palm rejection)
60
  element.addEventListener("pointercancel", (e) => {
61
    if (!dragState || e.pointerId !== dragState.pointerId) return
62

63
    element.releasePointerCapture(e.pointerId)
64
    element.classList.remove("dragging")
65
    element.style.transform = ""
66
    dragState = null
67
  })
68
}

1
.draggable {
2
  /* Disable browser touch handling - we'll manage it */
3
  touch-action: none;
4
}
5

6
.scrollable-container {
7
  /* Allow vertical scroll, we handle horizontal drag */
8
  touch-action: pan-y;
9
}

3 collapsed lines
1
// Touch-based drag with scroll prevention
2
function setupTouchDrag(element: HTMLElement): void {
3
  let startTouch: Touch | null = null
4

5
  element.addEventListener(
6
    "touchstart",
7
    (e) => {
8
      // Use first touch only
9
      if (e.touches.length !== 1) return
10
      startTouch = e.touches[0]
11

12
      element.classList.add("dragging")
13
    },
14
    { passive: false },
15
  )
16

17
  element.addEventListener(
18
    "touchmove",
19
    (e) => {
20
      if (!startTouch) return
21

22
      // Prevent scrolling during drag
23
      e.preventDefault()
24

25
      const touch = e.touches[0]
26
      const deltaX = touch.clientX - startTouch.clientX
27
      const deltaY = touch.clientY - startTouch.clientY
28

29
      element.style.transform = `translate(${deltaX}px, ${deltaY}px)`
11 collapsed lines
30
    },
31
    { passive: false },
32
  ) // Must be non-passive to preventDefault
33

34
  element.addEventListener("touchend", (e) => {
35
    if (!startTouch) return
36

37
    const touch = e.changedTouches[0]
38
    element.classList.remove("dragging")
39
    element.style.transform = ""
40

41
    // Find drop target
42
    const dropTarget = document.elementFromPoint(touch.clientX, touch.clientY)
43
    // Handle drop...
44

45
    startTouch = null
46
  })
47

48
  element.addEventListener("touchcancel", () => {
49
    element.classList.remove("dragging")
50
    element.style.transform = ""
51
    startTouch = null
52
  })
53
}

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

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

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

8 collapsed lines
1
interface SortableListState<T> {
2
  items: T[]
3
  dragIndex: number | null
4
  hoverIndex: number | null
5
}
6

7
function useSortableList<T extends { id: string }>(
8
  initialItems: T[],
9
): {
10
  items: T[]
11
  dragHandlers: (index: number) => DragHandlers
12
  dropHandlers: (index: number) => DropHandlers
13
} {
14
  const [state, setState] = useState<SortableListState<T>>({
15
    items: initialItems,
16
    dragIndex: null,
17
    hoverIndex: null,
18
  })
19

20
  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
        }
29

30
        // Reorder items
31
        const newItems = [...s.items]
32
        const [removed] = newItems.splice(s.dragIndex, 1)
33
        newItems.splice(s.hoverIndex, 0, removed)
34

35
        return { items: newItems, dragIndex: null, hoverIndex: null }
36
      })
37
    },
38
  })
39

40
  const dropHandlers = (index: number) => ({
41
    onDragEnter: () => {
42
      setState((s) => ({ ...s, hoverIndex: index }))
43
    },
44
  })
3 collapsed lines
45

46
  return { items: state.items, dragHandlers, dropHandlers }
47
}

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

15 collapsed lines
1
interface Container {
2
  id: string
3
  accepts: (item: DragItem) => boolean
4
}
5

6
interface DragItem {
7
  id: string
8
  type: string
9
  sourceContainerId: string
10
}
11

12
interface CrossContainerState {
13
  containers: Map<string, Container>
14
  activeItem: DragItem | null
15
  overContainerId: string | null
16
  overIndex: number | null
17
}
18

19
function handleCrossContainerDrop(
20
  state: CrossContainerState,
21
  sourceItems: Map<string, unknown[]>,
22
  setItems: (containerId: string, items: unknown[]) => void,
23
): void {
24
  const { activeItem, overContainerId, overIndex } = state
25
  if (!activeItem || !overContainerId || overIndex === null) return
26

27
  const targetContainer = state.containers.get(overContainerId)
28
  if (!targetContainer?.accepts(activeItem)) return
29

30
  // Remove from source
31
  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)
35

36
  // Add to target
37
  const targetList = [...(sourceItems.get(overContainerId) ?? [])]
38
  targetList.splice(overIndex, 0, removed)
39
  setItems(overContainerId, targetList)
40
}

1
const 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 anything
13
  },
14
]

10 collapsed lines
1
interface TreeNode {
2
  id: string
3
  children: TreeNode[]
4
  parentId: string | null
5
}
6

7
type TreeDropPosition =
8
  | { type: "before"; targetId: string }
9
  | { type: "after"; targetId: string }
10
  | { type: "child"; parentId: string }
11

12
function getTreeDropPosition(e: PointerEvent, element: HTMLElement, depthIndicatorWidth: number): TreeDropPosition {
13
  const rect = element.getBoundingClientRect()
14
  const relativeY = e.clientY - rect.top
15
  const relativeX = e.clientX - rect.left
16

17
  const nodeId = element.dataset.nodeId!
18
  const currentDepth = parseInt(element.dataset.depth ?? "0")
19

20
  // Top quarter: drop before
21
  if (relativeY < rect.height * 0.25) {
22
    return { type: "before", targetId: nodeId }
23
  }
24

25
  // Bottom quarter: drop after
26
  if (relativeY > rect.height * 0.75) {
27
    return { type: "after", targetId: nodeId }
28
  }
29

30
  // Middle: check horizontal position for nesting
31
  const hoverDepth = Math.floor(relativeX / depthIndicatorWidth)
32
  if (hoverDepth > currentDepth) {
33
    return { type: "child", parentId: nodeId }
34
  }
35

36
  return { type: "after", targetId: nodeId }
37
}
38

39
function 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 node
43
      const found = findNode(node.children, id)
44
      if (found) return found
45
    }
46
    return null
47
  }
48

49
  const ancestor = findNode(tree, potentialAncestorId)
50
  if (!ancestor) return false
51

52
  return findNode(ancestor.children, nodeId) !== null
53
}

10 collapsed lines
1
interface VirtualListDragConfig {
2
  itemHeight: number
3
  totalItems: number
4
  viewportHeight: number
5
  scrollTop: number
6
  scrollContainerRef: React.RefObject<HTMLElement>
7
}
8

9
function getVirtualDropIndex(clientY: number, config: VirtualListDragConfig): number {
10
  const { itemHeight, totalItems, scrollTop, scrollContainerRef } = config
11
  const container = scrollContainerRef.current
12
  if (!container) return 0
13

14
  const containerRect = container.getBoundingClientRect()
15
  const relativeY = clientY - containerRect.top + scrollTop
16
  const index = Math.floor(relativeY / itemHeight)
17

18
  return Math.max(0, Math.min(totalItems - 1, index))
19
}
20

21
function handleAutoScroll(clientY: number, config: VirtualListDragConfig): void {
22
  const container = config.scrollContainerRef.current
23
  if (!container) return
24

25
  const rect = container.getBoundingClientRect()
26
  const edgeThreshold = 50 // pixels
27
  const scrollSpeed = 10
28

29
  if (clientY < rect.top + edgeThreshold) {
30
    // Near top edge - scroll up
31
    container.scrollTop -= scrollSpeed
32
  } else if (clientY > rect.bottom - edgeThreshold) {
33
    // Near bottom edge - scroll down
34
    container.scrollTop += scrollSpeed
35
  }
36
}

1
// Basic custom drag image
2
element.addEventListener("dragstart", (e) => {
3
  const preview = createCustomPreview()
4
  document.body.appendChild(preview)
5
  preview.style.position = "absolute"
6
  preview.style.left = "-9999px"
7

8
  // Offset positions the cursor relative to the image
9
  e.dataTransfer?.setDragImage(preview, 20, 20)
10

11
  requestAnimationFrame(() => preview.remove())
12
})

8 collapsed lines
1
interface DragPreviewState {
2
  isDragging: boolean;
3
  item: unknown;
4
  x: number;
5
  y: number;
6
}
7

8
function DragPreview({ state }: { state: DragPreviewState }) {
9
  if (!state.isDragging) return null;
10

11
  return (
12
    <div
13
      style={{
14
        position: 'fixed',
15
        left: state.x,
16
        top: state.y,
17
        pointerEvents: 'none', // Don't block hit testing
18
        transform: 'translate(-50%, -50%) rotate(3deg)', // Slight rotation
19
        opacity: 0.9,
20
        zIndex: 9999
21
      }}
22
    >
23
      <ItemCard item={state.item} />
24
    </div>
25
  );
26
}

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
}
9

10
.drop-indicator--before {
11
  top: -1px;
12
}
13

14
.drop-indicator--after {
15
  bottom: -1px;
16
}

1
function 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;
6

7
    return (
8
      <>
9
        {showGapBefore && <div className="drop-gap" />}
10
        <ItemCard
11
          key={item.id}
12
          item={item}
13
          style={{ opacity: isDragging ? 0.5 : 1 }}
14
        />
15
        {showGapAfter && <div className="drop-gap" />}
16
      </>
17
    );
18
  });
19
}

1
.sortable-item {
2
  transition: transform 200ms ease;
3
}
4

5
.sortable-item--shifted-down {
6
  transform: translateY(var(--item-height));
7
}
8

9
.sortable-item--shifted-up {
10
  transform: translateY(calc(-1 * var(--item-height)));
11
}

1
async 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.x
7
  const deltaY = to.y - from.y
8

9
  // Start at drag position
10
  element.style.transform = `translate(${-deltaX}px, ${-deltaY}px)`
11
  element.style.transition = "none"
12

13
  // Force reflow
14
  element.offsetHeight
15

16
  // Animate to final position
17
  element.style.transition = "transform 200ms ease-out"
18
  element.style.transform = ""
19

20
  return new Promise((resolve) => {
21
    element.addEventListener("transitionend", () => resolve(), { once: true })
22
  })
23
}

15 collapsed lines
1
interface KeyboardDragState {
2
  isActive: boolean
3
  activeItemId: string | null
4
  targetIndex: number | null
5
}
6

7
function useKeyboardDrag(items: Item[], onReorder: (fromIndex: number, toIndex: number) => void) {
8
  const [state, setState] = useState<KeyboardDragState>({
9
    isActive: false,
10
    activeItemId: null,
11
    targetIndex: null,
12
  })
13

14
  const handleKeyDown = (e: KeyboardEvent, itemId: string, currentIndex: number) => {
15
    if (!state.isActive) {
16
      // Not dragging - Enter starts drag
17
      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
      return
27
    }
28

29
    // Currently dragging
30
    switch (e.key) {
31
      case "ArrowUp":
32
      case "ArrowLeft":
33
        e.preventDefault()
34
        if (state.targetIndex! > 0) {
35
          const newIndex = state.targetIndex! - 1
36
          setState((s) => ({ ...s, targetIndex: newIndex }))
37
          announceToScreenReader(`Position ${newIndex + 1} of ${items.length}`)
38
        }
39
        break
40

41
      case "ArrowDown":
42
      case "ArrowRight":
43
        e.preventDefault()
44
        if (state.targetIndex! < items.length - 1) {
45
          const newIndex = state.targetIndex! + 1
46
          setState((s) => ({ ...s, targetIndex: newIndex }))
47
          announceToScreenReader(`Position ${newIndex + 1} of ${items.length}`)
48
        }
49
        break
50

51
      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
        break
59

10 collapsed lines
60
      case "Escape":
61
        e.preventDefault()
62
        setState({ isActive: false, activeItemId: null, targetIndex: null })
63
        announceToScreenReader("Drag cancelled")
64
        break
65
    }
66
  }
67

68
  return { state, handleKeyDown }
69
}

1
function announceToScreenReader(message: string): void {
2
  let announcer = document.getElementById("drag-announcer")
3

4
  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
  }
22

23
  // Clear and set to ensure announcement
24
  announcer.textContent = ""
25
  requestAnimationFrame(() => {
26
    announcer!.textContent = message
27
  })
28
}

1
<!-- Draggable item -->
2
<div role="listitem" tabindex="0" aria-grabbed="false" aria-describedby="drag-instructions">Item content</div>
3

4
<!-- When being dragged -->
5
<div role="listitem" tabindex="0" aria-grabbed="true" aria-describedby="drag-instructions">Item content</div>
6

7
<!-- Drop target -->
8
<div role="list" aria-dropeffect="move">
9
  <!-- items -->
10
</div>
11

12
<!-- 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>

1
// Throttled drag handler
2
let lastMoveTime = 0
3
const THROTTLE_MS = 16 // One frame
4

5
function handlePointerMove(e: PointerEvent): void {
6
  const now = performance.now()
7
  if (now - lastMoveTime < THROTTLE_MS) return
8
  lastMoveTime = now
9

10
  // Actual move handling
11
  updateDragPosition(e.clientX, e.clientY)
12
}

1
interface ActivationConstraint {
2
  delay?: number // ms to hold before drag starts
3
  distance?: number // px to move before drag starts
4
  tolerance?: number // px of movement allowed during delay
5
}
6

7
// dnd-kit sensor configuration
8
const pointerSensor = useSensor(PointerSensor, {
9
  activationConstraint: {
10
    delay: 250, // Hold 250ms before drag activates
11
    tolerance: 5, // Allow 5px movement during delay
12
  },
13
})

1
function cleanupDragState(): void {
2
  // Reset all visual states
3
  document.querySelectorAll(".drop-target-active").forEach((el) => {
4
    el.classList.remove("drop-target-active")
5
  })
6

7
  // Clear cached data
8
  dropTargetRects.clear()
9

10
  // Remove global listeners
11
  document.removeEventListener("pointermove", handleGlobalMove)
12
  document.removeEventListener("pointerup", handleGlobalUp)
13
}

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

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

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

1
element.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)
7

8
  e.dataTransfer?.setDragImage(img, 0, 0)
9

10
  requestAnimationFrame(() => img.remove())
11
})

1
// Only works with mouse
2
element.draggable = true
3
element.addEventListener("dragstart", handleDragStart)
4
// Touch users see nothing

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