External Drag
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;
};
htmlEventis the pointer position. The widget reads onlyclientXandclientY. It never touchesDataTransfer.cardis the card to create. Omitidso Kanban generates one.targetis 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:
- On
dragstart, your app sets{ htmlEvent: null, card }. - On each
dragoverover the board's wrapper, your app replaces the descriptor with a copy that carries the current event, and callspreventDefault(). - The widget resolves the pointer against its own root. It uses the same hit testing as the internal card drag. It then writes
targetand also writes the destination column (and swimlane) intocardthrough the configured accessors. When the pointer is over a header, a gutter, a collapsed column or lane, or another board,targetisnull. - On
drop, whentargetisn'tnull, your app dispatchesadd-cardand clears the descriptor. Clear it ondragendtoo, 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 $state and pass it to <Kanban>. Set it when a drag starts, and refresh it on every dragover:
<script lang="ts">
import { Kanban, type CardProjection } from "@svar-ui/svelte-kanban";
let cardProjection = $state<CardProjection | null>(null);
function dragStart(task) {
// Omit the source id so Kanban generates the card id.
cardProjection = {
htmlEvent: null,
card: { label: task.text, priority: task.priority },
};
}
function dragOver(event: DragEvent) {
if (!cardProjection) return;
// A new object per dragover makes the pointer reactive.
cardProjection = { ...cardProjection, 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 lang="ts">
import {
Kanban,
type CardProjection,
type KanbanInstanceApi,
} from "@svar-ui/svelte-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" },
];
let tasks = $state([
{ id: 1, text: "Review pull request", priority: 1 },
{ id: 2, text: "Update onboarding docs", priority: 2 },
{ id: 3, text: "Triage bug reports", priority: 3 },
]);
let api = $state<KanbanInstanceApi>();
let cardProjection = $state<CardProjection | null>(null);
let dragged: number | null = null;
function dragStart(task: (typeof tasks)[number]) {
dragged = task.id;
cardProjection = {
htmlEvent: null,
card: { label: task.text, priority: task.priority },
};
}
function dragOver(event: DragEvent) {
if (!cardProjection) return;
cardProjection = { ...cardProjection, htmlEvent: event };
event.preventDefault();
}
function drop(event: DragEvent) {
if (!api || !cardProjection?.target) return;
event.preventDefault();
// The widget has written the destination column into the card.
api.exec("add-card", {
card: cardProjection.card,
before: cardProjection.target.before,
});
tasks = tasks.filter(task => task.id !== dragged);
dragEnd();
}
function dragEnd() {
cardProjection = null;
dragged = null;
}
</script>
<!-- svelte-ignore a11y_no_static_element_interactions -->
<div class="demo" ondragover={dragOver} ondrop={drop}>
<div class="tasks">
{#each tasks as task (task.id)}
<div
class="task"
draggable="true"
ondragstart={() => dragStart(task)}
ondragend={dragEnd}
>
{task.text}
</div>
{/each}
</div>
<Kanban bind:this={api} {cards} {columns} {cardProjection} />
</div>
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:
readonlydoesn't block a projection. If your app treats readonly as a full lock, don't setcardProjectionand 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
beforeanchor still defines the order in the card data. - The standard
RestDataProvidersends only the card in its POST request, so the server doesn't receive the position. To persist it, handleadd-cardyourself. See Working with server.