Skip to main content

External Drag

PRO

The functionality is available in PRO Edition only

Users can drag items from outside the board, such as a backlog list or a search result, and drop them into a column to create cards. This guide covers how the drag descriptor works, how to wire the native drag events, and how to commit the drop.

How external drag works​

External drag uses the cardProjection prop. It's a descriptor that your app owns. Your app handles the native HTML drag events and the final mutation. The widget only resolves where the item would land and shows a preview there.

The descriptor has three fields:

type CardProjection = {
htmlEvent: { clientX: number; clientY: number } | null;
card: Partial<KanbanCard>;
target?: {
column: ColumnID;
swimlane?: SwimlaneID;
before: CardID | null; // null = end of the destination cell
} | null;
};
  • htmlEvent is the pointer position. The widget reads only clientX and clientY. It never touches DataTransfer.
  • card is the card to create. Omit id so Kanban generates one.
  • target is written by the widget, not by you. It holds the destination column, the swimlane (on boards with swimlanes), and the card to insert before.

A drag goes through four steps:

  1. On dragstart, your app sets { htmlEvent: null, card }.
  2. On each dragover over the board's wrapper, your app replaces the descriptor with a copy that carries the current event, and calls preventDefault().
  3. The widget resolves the pointer against its own root. It uses the same hit testing as the internal card drag. It then writes target and also writes the destination column (and swimlane) into card through the configured accessors. When the pointer is over a header, a gutter, a collapsed column or lane, or another board, target is null.
  4. On drop, when target isn't null, your app dispatches add-card and clears the descriptor. Clear it on dragend too, so a cancelled drag doesn't leave a preview behind.

The MIT edition accepts the prop and ignores it.

Wiring the drag events​

Keep the descriptor in a ref and pass it to <Kanban>. Set it when a drag starts, and refresh it on every dragover:

<script setup lang="ts">
import { ref } from "vue";
import { Kanban, type CardProjection } from "@svar-ui/vue-kanban";

const cardProjection = ref<CardProjection | null>(null);

function dragStart(task) {
// Omit the source id so Kanban generates the card id.
cardProjection.value = {
htmlEvent: null,
card: { label: task.text, priority: task.priority },
};
}

function dragOver(event: DragEvent) {
if (!cardProjection.value) return;
// A new object per dragover makes the pointer reactive.
cardProjection.value = { ...cardProjection.value, htmlEvent: event };
event.preventDefault();
}
</script>

Attach dragOver to an element that wraps both the source list and the board. Create a new object on each event instead of mutating htmlEvent in place. The widget reacts to the descriptor changing, so a mutated object won't move the preview. Calling preventDefault() tells the browser that a drop is allowed here.

Committing the drop​

The widget may replace card while it resolves the target, so always read cardProjection.card on drop instead of keeping your own copy. Here's the full example, with a backlog list next to the board:

<script setup lang="ts">
import { ref } from "vue";
import {
Kanban,
type CardProjection,
type KanbanInstanceApi,
} from "@svar-ui/vue-kanban";

const columns = [
{ id: "backlog", label: "Backlog" },
{ id: "doing", label: "In Progress" },
{ id: "done", label: "Done" },
];
const cards = [
{ id: 1, label: "Set up CI", column: "doing" },
{ id: 2, label: "Write release notes", column: "done" },
];

const tasks = ref([
{ id: 1, text: "Review pull request", priority: 1 },
{ id: 2, text: "Update onboarding docs", priority: 2 },
{ id: 3, text: "Triage bug reports", priority: 3 },
]);

const api = ref<KanbanInstanceApi>();
const cardProjection = ref<CardProjection | null>(null);
let dragged: number | null = null;

function dragStart(task: (typeof tasks.value)[number]) {
dragged = task.id;
cardProjection.value = {
htmlEvent: null,
card: { label: task.text, priority: task.priority },
};
}

function dragOver(event: DragEvent) {
if (!cardProjection.value) return;
cardProjection.value = { ...cardProjection.value, htmlEvent: event };
event.preventDefault();
}

function drop(event: DragEvent) {
if (!api.value || !cardProjection.value?.target) return;
event.preventDefault();
// The widget has written the destination column into the card.
api.value.exec("add-card", {
card: cardProjection.value.card,
before: cardProjection.value.target.before,
});
tasks.value = tasks.value.filter(task => task.id !== dragged);
dragEnd();
}

function dragEnd() {
cardProjection.value = null;
dragged = null;
}
</script>

<template>
<div class="demo" @dragover="dragOver" @drop="drop">
<div class="tasks">
<div
v-for="task in tasks"
:key="task.id"
class="task"
draggable="true"
@dragstart="dragStart(task)"
@dragend="dragEnd"
>
{{ task.text }}
</div>
</div>
<Kanban
ref="api"
:cards="cards"
:columns="columns"
:cardProjection="cardProjection"
/>
</div>
</template>

drop does nothing when target is null, so dropping outside a card cell is ignored. A successful drop is a single add-card action. It fires one onaddcard event and, with history on, creates one undo step. The example also removes the item from the source list, but that part is up to your app.

Preview and limitations​

While the pointer is over a valid cell, the board shows the same drop placeholder as an internal drag. In a stack column, its height is render.estimatedCardHeight. In a flow layout, it takes a grid slot the size of a card. The preview doesn't hide any card, doesn't mount a drag ghost, and never changes data. If an internal card drag is active at the same time, the internal drag wins.

Some limits to plan for:

  • readonly doesn't block a projection. If your app treats readonly as a full lock, don't set cardProjection and don't commit the drop.
  • The widget doesn't autoscroll during an external drag. To reach a column that's off screen, the user has to scroll first.
  • An active sort can override the position where the card shows up. The before anchor still defines the order in the card data.
  • The standard RestDataProvider sends only the card in its POST request, so the server doesn't receive the position. To persist it, handle add-card yourself. See Working with server.