Docs/API
Events
What drag events carry — the active drag, the target, the pointer, where the item is — and what onBeforeDrop answers.
Monitors (useDnDMonitor), the provider's events and droppables' hooks get a DnDEvent;
onDragEnd gets a DnDEndEvent. Sortable lists and trees pass their own drop events
(SortableDropEvent,
SortableTreeDropEvent) to their onBeforeDrop and onDrop.
Loading the demo…
<script setup lang="ts">
import { ref } from 'vue';
import { DnDProvider } from '@vue-dnd-kit/core';
import { describe, type LoggedEvent } from './describe';
import TaskColumn from './TaskColumn.vue';
import EventInspector from './EventInspector.vue';
const todo = ref([
{ id: 'docs', title: 'Write docs' },
{ id: 'bug', title: 'Fix #42' },
]);
const done = ref([{ id: 'ship', title: 'Ship v3' }]);
// Every event of the drag, described when it fires. A new drag starts a new log;
// moves fire every frame, so they share one entry, which keeps the latest.
const events = ref<LoggedEvent[]>([]);
let count = 0;
const record = (name: string, type: string, payload: unknown) => {
if (name === 'onDragStart') events.value = [];
const lines = describe(type, payload);
const move = name === 'onDragMove' && events.value.find((event) => event.name === name);
if (move) Object.assign(move, { lines, count: move.count + 1 });
else events.value.push({ id: ++count, name, type, lines, count: 1 });
};
</script>
<template>
<DnDProvider>
<div class="demo">
<div class="columns">
<TaskColumn id="todo" v-model="todo" :record="record" />
<TaskColumn id="done" v-model="done" :record="record" />
</div>
<EventInspector :events="events" :record="record" />
</div>
</DnDProvider>
</template>
<style scoped>
.demo {
display: flex;
flex-wrap: wrap;
align-items: flex-start;
justify-content: center;
gap: 16px;
}
.columns {
display: flex;
flex-direction: column;
gap: 10px;
width: 168px;
}
</style>DnDEvent
What drag events carry: monitors, the provider's events and the hooks of drop targets get it.
Active<T>The drag.
Over | nullThe drop target under the drag; null over nothing.
CoordinatesPointer in viewport coordinates, after modifiers.
CoordinatesOffset from the drag start, after modifiers.
Coordinates | nullWhere the dragged box's top-left corner is in over, from its padding edge and with its scroll: the left/top that put an absolutely positioned item where it was dropped (a note on a board). null over nothing. Of the overlay box, or of the element itself with overlay: false.
DragModeWhat a drop would do: 'move', 'copy' (a list's pull: 'clone', or the copy modifier held over items whose list can clone), 'swap' or 'insert'. A plain drop target reads it to copy instead of moving.
DragSourcePresent when the dragged items come from a sortable list.
ExternalDataA drag from outside the page: what it carries (active.external). Its data comes at the drop.
DnDEndEvent
What onDragEnd (and the target's onDrop) gets: the event of the drop, and how it went.
booleanFalse when the drag ended outside every drop target.
Key[]Ids accepted by onBeforeDrop (all dragged ids unless a subset was returned).
Key[]The other dragged ids: onBeforeDrop left them out, and they fly back. Empty when it took them all.
'move' | 'copy' | 'link'A drag out of the page (native) dropped somewhere else: what that place did with it. 'move' takes the items out of their sortable list here; 'copy' and 'link' leave them.
onBeforeDrop answers
What onBeforeDrop decides:
'accept'(ortrue, or nothing): the drop goes through;'reject'(orfalse): no drop, the items fly back;- a list of ids: only those items are accepted, the others fly back;
'continue': no drop, and the drag goes on. With a pointer the item follows it again (no button held) and the next release drops it, a click does; a touch takes it again; the keyboard moves it as before. Escape cancels it. The drop asksonBeforeDropagain.
type BeforeDropResult = boolean | void | Key[] | 'accept' | 'reject' | 'continue'See Deciding a drop.
The active drag
The running drag: the item it started from, and every item it carries.
KeyId of the item the drag started from.
Key[]Every dragged id, the primary one first (multi-drag).
DragItem<T>[]Every dragged item, the primary one first.
unknownThe data of the item the drag started from.
stringThe label of the item the drag started from, what people call it.
string[]The normalized type of the item the drag started from; empty means it fits any drop target.
HTMLElementElement the drag started from. It may get detached (virtual lists, cross-list moves).
RectLayout rect of element at drag start.
SensorTypeHow the drag moves: 'pointer' follows points, 'keyboard' moves by items (SensorActivation.type).
ExternalDataA drag from outside the page (files, a link, text, or items from another window of the app): what it carries. Its items are made for it (element is a stand-in).
booleanThe browser's own drag (native, or one from outside): the browser draws the dragged image, and there is no overlay.
One dragged item: the one the drag started from, or another one of a multi-drag.
The target
The drop target under the drag.
The source
Where the dragged items come from, when that is a sortable list.
What a drop does: 'move', 'copy' (the items stay, copies of them go in), 'swap' (behavior: 'swap': two items exchange places) or 'insert' (a plain draggable goes into a list as the item its createItem made).
type DragMode = 'move' | 'copy' | 'swap' | 'insert'