createKanban

Headless two-level board state for columns of cards, with column reorder, in-column reorder, and a cross-column transfer primitive. Pure logic — no drag-and-drop, no keyboard, no DOM — so consumers can drive it from any input modality.

Usage

createKanban composes createSortable twice — once for the column order and once per column for item order — and links them through a cross-column transfer primitive. Drag-and-drop wiring, keyboard navigation, and rendering are consumer concerns.

import { createKanban } from '@vuetify/v0'

import type { KanbanColumnTicketInput, SortableTicketInput } from '@vuetify/v0'

interface CardInput extends SortableTicketInput {
  value: { title: string }
}

interface ColumnInput extends KanbanColumnTicketInput<CardInput> {
  value: { title: string }
}

const kanban = createKanban<CardInput, ColumnInput>()

const todo = kanban.columns.register({ value: { title: 'Todo' } })
const done = kanban.columns.register({
  value: { title: 'Done' },
  accept: (ticket, from, toIndex) => done.items.size < 5,
})

const a = todo.items.register({ value: { title: 'Write spec' } })
todo.items.register({ value: { title: 'Ship docs' } })

// Cross-column transfer: move item a to done column at index 0
kanban.transfer(a.id, done.id, 0)

// Subscribe to cross-column transfer events
kanban.on('transfer:ticket', ({ ticket, from, to, fromIndex, toIndex }) => {
  console.log(ticket.value.title, from, '→', to, '@', toIndex)
})

Architecture

createKanban orchestrates two tiers of createSortable. Column order and item order are independent sortables; transfer is the only cross-column primitive. An internal lookup registry maps each item id to its owning column id so transfer can resolve the source column without the caller providing it.

The composable adds the following on top of two createSortable instances:

Reactivity

Examples

Recipes

Disabling moves

Disable flags are layered: root, column, and item. Each gate is checked independently.

Root gate — freezes the entire board. All cross-column transfers no-op. Each column’s inner sortable also respects the root gate, so intra-column reorders are frozen too.

const kanban = createKanban({ disabled: toRef(() => isReadOnly.value) })

// transfer and column.items.move both no-op while isReadOnly is true
kanban.transfer(id, toColumnId, 0)

Column gate — freezes one column. Transfers in or out of that column are silently rejected. Item reorders within the column are also frozen.

const archive = kanban.columns.register({
  value: { title: 'Archive' },
  disabled: true,
})

kanban.transfer(id, archive.id, 0)  // no-op — destination is disabled
kanban.transfer(archiveItemId, todo.id, 0)  // no-op — source is disabled

Item gate — prevents one item from being transferred. Other items in the same column are unaffected.

const pinned = todo.items.register({
  value: { title: 'Pinned task' },
  disabled: true,
})

kanban.transfer(pinned.id, done.id, 0)  // no-op — ticket is disabled

Accept predicate (WIP-limit pattern)

Each column ticket can declare an accept function. It runs when an item is being transferred into that column from another column. Return false to silently reject.

The canonical use case is a WIP (work-in-progress) limit: block transfers into a column once it reaches a maximum item count.

const doing = kanban.columns.register({
  value: { title: 'Doing' },
  accept: (ticket, from, toIndex) => doing.items.size < 3,
})

// Transferring a fourth item into 'doing' silently no-ops
kanban.transfer(id, doing.id, 0)

accept receives the item ticket, the source column id, and the intended destination index. It is only called for cross-column transfers — same-column moves collapse to column.items.move and bypass accept entirely.

Subscribing to transfer events

kanban.on('transfer:ticket', cb) subscribes to every cross-column move. The callback receives a KanbanTransferPayload with five fields.

kanban.on('transfer:ticket', ({ ticket, from, to, fromIndex, toIndex }) => {
  // Persist the new board state to a backend
  persist({ itemId: ticket.id, fromColumn: from, toColumn: to, toIndex })
})

Same-column moves (intra-column reorder via kanban.transfer with toColumnId === fromColumnId) collapse to column.items.move and do not emit transfer:ticket. To observe intra-column reorders, subscribe to column.items.on('move:ticket', ...) instead.

Use kanban.off('transfer:ticket', cb) to remove a subscription with the same callback reference.

Reactive iteration

kanban.columns.values() and column.items.values() return non-reactive snapshots — calling them inside a template directly won’t update when the registry changes.

Wrap with useProxyRegistry to get a reactive { keys, values, entries, size } snapshot:

import { useProxyRegistry } from '@vuetify/v0'

// Reactive column list — updates when columns are registered, unregistered, or reordered
const columns = useProxyRegistry(kanban.columns)

// Reactive item list for a specific column — updates on intra-column moves and cross-column transfers
const items = useProxyRegistry(todo.items)

In templates, iterate columns.values (not columns.values()) — the proxy exposes values as a reactive array, not a function.

<template>
  <div v-for="column in columns.values" :key="column.id">
    {{ column.value.title }}
  </div>
</template>

Note that column.items itself is not reactive at the column level. If a new column registers after the component mounts, the new column’s items instance is attached to the new ticket — the existing columns proxy picks it up automatically via the registry event.

Listening to column and item reorder

Cross-column moves fire transfer:ticket on the kanban bus. Intra-column moves fire move:ticket on the relevant sortable’s own bus.

// Column reorder — fires when kanban.columns.move / swap / reorder is called
kanban.columns.on('move:ticket', ({ ticket, from, to }) => {
  console.log('column moved:', ticket.id, from, '→', to)
})

// Item reorder within a column — fires when column.items.move / swap / reorder is called
todo.items.on('move:ticket', ({ ticket, from, to }) => {
  console.log('item moved within todo:', ticket.id, from, '→', to)
})

Cross-column transfers do NOT fire move:ticket on either column’s items bus. They fire transfer:ticket on the kanban bus after the batch closes. If you need to observe every positional change regardless of whether it crossed a column boundary, subscribe to both event types.

FAQ