useDragDrop

Headless drag-and-drop primitive. Owns two registries — draggables and zones — plus the active-drag state.

Usage

Call useDragDrop once per scope and pass the returned context to children that register draggables or zones.

<script setup lang="ts">
  import { useDragDrop } from '@vuetify/v0'
  import { useTemplateRef } from 'vue'

  const dnd = useDragDrop<{ type: 'card', value: string }>()

  const draggable = useTemplateRef<HTMLElement>('draggable')
  const dropzone = useTemplateRef<HTMLElement>('dropzone')

  dnd.draggables.register({
    el: draggable,
    type: 'card',
    value: 'card-1',
  })

  dnd.zones.register({
    el: dropzone,
    accept: ['card'],
    orientation: 'vertical',
    onDrop: (drag, position) => {
      console.log(drag.value, position.index) // 'card-1', 0
    },
  })
</script>

<template>
  <div
    ref="draggable"
    data-draggable
    aria-roledescription="draggable"
  >
    Card
  </div>

  <div ref="dropzone" data-dropzone>
    Drop zone
  </div>
</template>

Architecture

The factory owns four pieces of state (draggables, zones, active, isDragging) plus a public cancel() action, and three extension points (adapters, plugins, lifecycle hooks). Pointer and keyboard adapters observe the DOM and emit a four-call lifecycle (start, move, drop, cancel); the factory pipes those through per-ticket and global hooks before mutating active.

Adapters

Adapters are pluggable input layers: an adapter observes the DOM (or any other input source) and emits the four lifecycle events the factory consumes. Default adapters are installed automatically.

PointerAdapter

Pointer Events for mouse, touch, and pen. Installed by default.

import { useDragDrop, PointerAdapter } from '@vuetify/v0'

const dnd = useDragDrop({ adapters: [new PointerAdapter({ threshold: 8 })] })

KeyboardAdapter

Keyboard activation: Space / Enter to pick up and drop, arrow keys to nudge, Escape to cancel. Installed by default.

import { useDragDrop, KeyboardAdapter } from '@vuetify/v0'

const dnd = useDragDrop({ adapters: [new KeyboardAdapter({ step: 32 })] })

Replacing the defaults

To use only one adapter, pass it explicitly. The default array is replaced entirely:

import { useDragDrop, PointerAdapter } from '@vuetify/v0'

// Pointer only — keyboard disabled.
const dnd = useDragDrop({ adapters: [new PointerAdapter()] })

To extend instead of replace, list the defaults alongside your custom adapter:

import { useDragDrop, PointerAdapter, KeyboardAdapter } from '@vuetify/v0'
import { TouchAdapter } from './touch-adapter'

useDragDrop({
  adapters: [new PointerAdapter(), new KeyboardAdapter(), new TouchAdapter()],
})

adapters: [] disables both defaults entirely — useful for server-driven or test scenarios.

Custom adapters

Extend the abstract DragDropAdapter base for shared cleanup + dispose() lifecycle and the locate() DOM-walk helper:

import { DragDropAdapter } from '@vuetify/v0'
import type { DragDropAdapterContext, DragType } from '@vuetify/v0'

class TouchAdapter<Z extends DragType = DragType> extends DragDropAdapter<Z> {
  setup (context: DragDropAdapterContext<Z>): void {
    // observe input, then call:
    //   context.emit.start(source, origin, 'touch')
    //   context.emit.move(point)
    //   context.emit.drop()
    //   context.emit.cancel()
    this.cleanup = () => { /* tear down listeners */ }
  }
}

context.emit exposes start(source, origin, via), move(point), drop(), and cancel() — call these as input arrives. Adapters declare their own via value (typed as DragVia) so consumers reading active.value.via can distinguish the input source. DragVia is Extensible<'pointer' | 'keyboard'> — additional modalities (e.g. 'touch', 'gamepad') flow through without type-level coordination.

Reactivity

Reactive fields

Every consumer-facing state field is a reactive ref . Reads in templates need .value.

Indicator rects are cached per zone; getBoundingClientRect runs only when the zone resizes or its children mount/unmount, not on each pointer move.

Methods

DOM attributes

The composable does not produce attribute objects — consumers wire data attributes themselves so the design-system layer can choose its own keys. The canonical wiring is:

Draggable element:

• data-draggable (always)

• aria-roledescription="draggable" (always)

• data-dragging toggled while ticket.isDragging.value is true

• touch-action: none (CSS or style="touch-action: none") so the browser doesn’t pan/zoom on pointer drag

Drop zone element:

• data-dropzone (always)

• data-over toggled while zone.isOver.value is true

• data-accepts toggled while both zone.isOver.value && zone.willAccept.value are true

Examples

Recipes

Multiple drag types in one scope

Default to a single type per scope (useDragDrop<{ type: 'card', value: Card }>()) — every draggable and zone shares one shape, every callback narrows trivially. Widen Z to a discriminated union only when you need cross-type interactions in the same scope (e.g. a kanban where cards drop on columns and columns drop on a column-row); a separate useDragDrop() per scope is cleaner whenever the types don’t meet.

When you do widen, type narrowing on drag.type carries the corresponding drag.value through, so each variant keeps its payload shape across onDrop and accept.

type KanbanTypes =
  | { type: 'card', value: Card }
  | { type: 'column', value: Column }

const dnd = useDragDrop<KanbanTypes>()

// Card zone accepts only cards
dnd.zones.register({ el, accept: ['card'], onDrop: (drag, position) => {
  // drag.type narrows to 'card', drag.value to Card
}})

// Column-row zone accepts only columns
dnd.zones.register({ el, accept: ['column'], orientation: 'horizontal' })

Vetoing drops

Either layer can veto. Per-zone vetoes route the drag through the cancel chain (onLeave on the active zone → onCancel on the source draggable → global onCancel) so consumers can roll back optimistic UI without subscribing to a separate “drop failed” event. Both onCancel callbacks (per-draggable and global) receive a second argument reason: 'cancel' | 'reject' — 'reject' when the cancel was triggered by a drop veto, 'cancel' for user-initiated aborts (Escape, programmatic dnd.cancel()).

accept (function form) must return synchronously — predicates that return a Promise / thenable are rejected with a console warning. Wrap async work in onBeforeDrop instead, returning false to veto.

dnd.zones.register({
  el,
  accept: ['card'],
  onBeforeDrop: (drag) => column.cards.length < column.wipLimit,
})

// Per-draggable cancel can react to the reason:
dnd.draggables.register({
  el,
  type: 'card',
  value: card,
  onCancel: (drag, reason) => {
    if (reason === 'reject') notify()
  },
})

Accessibility

WAI-ARIA does not standardize a kanban or “drag list” pattern. The primitive follows the list-of-lists convention used by Pragmatic DnD, dnd-kit, and headless-ui:

• Draggable tickets carry aria-roledescription="draggable" only — no aria-grabbed or aria-dropeffect, both deprecated in ARIA 1.1.

• Wrap each drop zone in a container with role="list" and the draggable list items with role="listitem".

• Each zone should wire a roving tabindex via useRovingFocus — one focus stop per zone, arrow keys move between items in the same zone, Tab moves to the next zone.

• Provide a single live region per scope (<div role="status" aria-live="polite">) and watch active to announce moves (“Card moved to Done, position 2 of 5”). The live region is the consumer’s responsibility — the headless contract excludes user-facing strings (PHILOSOPHY §5.5).

The default KeyboardAdapter honours the standard contract: Space / Enter to pick up and drop, arrow keys to nudge the drag point by step px (default 16), Escape to cancel.

Post-drop focus

After a successful keyboard drop, the moved element is typically replaced by the consumer’s onDrop handler — focus then lands on <body>, breaking keyboard flow. Restore it explicitly: in onDrop, after mutating the source list, call nextTick and refocus the new element by id (or rely on useRovingFocus to refocus the active item). Branch on drag.via === 'keyboard' (the first argument to onDrop) so the restoration only runs for keyboard drags, not pointer drags. dnd.active.value is already null inside onDrop / onCancel — read the drag argument instead.

FAQ

API