()
// 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()`).
> [!TIP]
> `onDrop`, `onCancel`, and `onLeave`-during-cancel fire AFTER `dnd.active.value` is cleared to `null` — read the `drag` argument, not the reactive ref. `onMove`, `onEnter`, `onLeave` during a drag, `onBeforeStart`, and `onBeforeDrop` run while `active` still holds the draft (or, for `onBeforeStart`, before it is written). The cleared-before-notify ordering on drop/cancel prevents re-entrance loops when a hook calls `dnd.cancel()` or unregisters a ticket.
`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.
```ts
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()
},
})
```
### Installing a plugin
A plugin is `(context) => disposer`. Nothing named `scroll()` or `flip()` is exported — write autoscroll or FLIP yourself against `active` and the registry event bus.
```ts
import { useDragDrop } from '@vuetify/v0'
import type { DragDropPlugin } from '@vuetify/v0'
const logDrops: DragDropPlugin = context => {
function onRegister (ticket: { id: string }) {
console.log('zone', ticket.id)
}
context.zones.on('register:ticket', onRegister)
return () => context.zones.off('register:ticket', onRegister)
}
const dnd = useDragDrop({ plugins: [logDrops] })
```
## 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](/composables/system/use-roving-focus) — one focus stop per zone, arrow keys move between items in the same zone **while idle**, Tab moves to the next zone. The two-list example uses `tabindex="0"` on every item instead, so every card is a tab stop.
- Provide a single live region per scope (``) 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).
Keyboard maps split on whether a drag is active:
| State | `Space` / `Enter` | Arrow keys | `Escape` |
|---|---|---|---|
| Idle | Pick up the focused ticket | Roving focus between items (your `useRovingFocus`, not the adapter) | — |
| Dragging | Drop | Nudge the drag point by `step` px (default 16). `KeyboardAdapter` calls `preventDefault`, so roving does not see these keys. | 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 ``, 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
::: faq
??? Why not use HTML5 drag-and-drop?
Native HTML5 DnD has terrible mobile support, an ugly default ghost element you can't customize cross-browser, no programmatic activation distance, and inconsistent event semantics across input devices. `PointerAdapter` uses Pointer Events instead — uniform mouse, touch, and pen handling, no default ghost (you render whatever you want), and full control over activation thresholds. Plug HTML5 in as a custom adapter if you need cross-window drops or OS file-drag integration; the headless contract doesn't lock it out.
??? When does `position.index` get set?
Only when the over-zone declares `orientation`. Without orientation, the zone is opaque — drops fire with `position.pointer` only. With orientation, the composable measures **every element child** of the zone `el` (`zoneEl.children`) and resolves an index against that list, not against registered draggables. Empty oriented zones default `index` to `0`. The indicator is `null` over the two slots flanking the dragged element's own position in its home zone — dropping there changes nothing, so no slot is proposed and the drop resolves `index` to the element's current position.
`position.index` is computed against the **pre-move** child list. If your `onDrop` removes the source first and then splices at that index, same-list downward moves overshoot by one — use `to > from ? to - 1 : to`. Cross-list drops do not need the `-1`; the destination's children never included the source. The two-list example and [createSortable](/composables/data/create-sortable)'s DnD demo both apply that adjustment.
??? How do I pick the right `Z` parameter?
`Z` is a discriminated union of every drag type the scope handles. Default to one variant. Widen only when two types actually interact in the same scope — otherwise a second `useDragDrop()` is cleaner. The types are distributive: narrowing `drag.type` narrows `drag.value`. `ActiveDrag.id` is the registry ticket id (pass `id` to `register` if you need it stable); your payload lives on `value`.
```ts
import { useDragDrop } from '@vuetify/v0'
// One type — every callback already knows the shape
const cards = useDragDrop<{ type: 'card', value: Card }>()
// Two types that meet — narrow on drag.type
type Kanban =
| { type: 'card', value: Card }
| { type: 'column', value: Column }
const dnd = useDragDrop()
dnd.zones.register({
el,
accept: ['card'],
onDrop: drag => {
drag.value // Card
},
})
```
??? Can the same DOM element be both a draggable and a zone?
Yes. Two registrations on the same element work because they live in different registries. The kanban use case relies on this: each column registers as a draggable (`type: 'column'`) for column-reordering and as a zone (`accept: ['card']`) for card drops.
??? What if I need autoscroll, FLIP animations, or multi-select drag?
These don't ship in v1 to keep the surface small. The plugin slot is the extension point — a plugin is `(context) => disposer`. Write autoscroll or FLIP against `active` and the registry event bus; nothing named `scroll()` or `flip()` is exported. See [Installing a plugin](#installing-a-plugin). Multi-select drag is best composed with [createSelection](/composables/selection/create-selection) so the selected set is its own first-class concept.
:::