Kanban

Anatomy

Seven parts, three of them optional. Kanban owns the data and the drag; KanbanBoard lays the columns out; KanbanColumn and KanbanItem register themselves under the value you give them. The board does not draw your columns — you map over value yourself, in key order.

import {
  Kanban, KanbanBoard, KanbanColumn, KanbanColumnHandle,
  KanbanItem, KanbanItemHandle, KanbanOverlay,
} from '@comitor/ui'

<Kanban value={columns} onValueChange={setColumns} getItemValue={(card) => card.id}>
  <KanbanBoard>                        {/* the row — or stack — of columns */}
    <KanbanColumn value="todo">        {/* one per key of value, in key order */}
      <KanbanColumnHandle />           {/* optional: without it the column stays put */}
      <KanbanItem value="DS-403">      {/* one per card: value = getItemValue(card) */}
        <KanbanItemHandle />           {/* optional: a grip, instead of asHandle */}
      </KanbanItem>
    </KanbanColumn>
  </KanbanBoard>
  <KanbanOverlay>                      {/* optional: the copy that follows the pointer */}
    {({ value, variant }) => <LiftedCopy id={value} kind={variant} />}
  </KanbanOverlay>
</Kanban>

• A card is dragged by a KanbanItemHandle inside it, or — with asHandle — by the whole card.
• A column moves only if it has a KanbanColumnHandle or asHandle. Without either it is a drop zone that stays where it is.
• KanbanOverlay draws the copy that follows the pointer, and the original stays in the list as a half-opaque placeholder. Without an overlay the card itself travels, at half opacity.

A task board

Four status columns, cards assembled from StatusPill, Badge and AvatarGroup, and counts in the headers that follow the drag — onValueChange runs while the card is still moving, not only when it lands. Each card is dragged by its grip, so the ⋯ menu beside it stays clickable, and the menu moves a card with no drag at all. The sentence under the board is computed from value after each change: that is the moment to save.

The value is yours

value is a plain object — column key → array of cards. Its key order is the column order and each array is the card order. The board keeps no copy: every change arrives through onValueChange and goes back in as value. Drag a card below and watch both panels — the object changes while the card is still in the air.

• During the drag, each time the card enters another column (it joins the end of that column, then moves among its cards) or passes another card in its own column.
• On drop, for a column move or a last step inside one column. With onMove set, the board calls it instead and leaves that reorder to you.
• On cancel — Escape, a drop refused by cancelDrop, a resized window, a hidden tab — once more if anything had moved, with the value from the moment the card was picked up.

So save on drop, not in onValueChange: it fires several times per drag, with states the user passed through on the way. And in onDragEnd the board has not applied its last reorder yet — read the final position on the next render, as the task board does. Doing below takes two cards: cancelDrop refuses a third, and the refusal is a cancel, so the card goes back to where it started. Cards can be plain strings, as here; then they are their own id and getItemValue is optional.

{
  "backlog": [
    "Renew the SSL certificate",
    "Draft the Q4 roadmap",
    "Archive 2025 invoices"
  ],
  "doing": [
    "Migrate billing to v2",
    "Onboard Linh Vo"
  ],
  "done": [
    "Rotate the API keys"
  ]
}

Drag a card to see them.

Moving columns

Columns are sortable too, once they have a handle — KanbanColumnHandle in the header here, or asHandle on the whole column. A column move lands on drop, as a new key order of the same object, which is also why a column key must never look like an integer (see Known limitations). The overlay’s children can be a function of { value, variant }, so one KanbanOverlay lifts either a list or a card. Drag a list by the grip beside its name.

Keyboard

The board listens to three sensors: mouse, touch and keyboard. With the keyboard, every drag activator is a tab stop, and the whole drag happens on it.

This is the part the port had to fix. dnd-kit’s keyboard sensor calls preventDefault() on the Space or Enter that starts a drag, and upstream ignored every drag event whose starting event had been default-prevented — its way of letting an app cancel from onDragStart. So a keyboard drag lifted the card, announced the drop, and never touched the data. The port measured it with real keys: Space, ArrowRight, Space — the live region said the card was dropped in the next column, and onValueChange was not called once. Try the same keys below; the line under the board prints what the live region says.

What the port guarantees

Upstream behaviour that changed on the way into the package, phrased as what you can now rely on.

• A keyboard drop changes the data. The default-prevented guard now applies to mouse and touch only. The side effect: calling event.activatorEvent.preventDefault() in your onDragStart no longer cancels a keyboard drag — refuse drops with cancelDrop, which works for every sensor.
• Escape puts the card back. Every move is written to onValueChange while the card travels, so upstream’s cancel left it wherever it had got to — against its own spoken instruction to “press Escape to cancel”. The board now keeps the value from pick-up and hands it back on cancel, whatever caused the cancel.
• Arrow keys do not freeze. The keyboard coordinate getter came from dnd-kit’s multiple-containers example, where skipping a drop zone without a measured rect was a return inside forEach. Upstream turned the loop into for…of and kept the return — so one unmeasured drop zone ended the function and the arrow keys stopped moving anything. It is a continue now.
• Announcements speak the app’s language. Upstream hard-coded English sentences; changing them meant rewriting accessibility.announcements and recomputing position and total yourself. Here four functions receive them ready-made, per key, through labels.
• Handles have a name and a role. A grip is nearly always a lone icon — a button with no name. Both handles now default to “Drag to move card / column”, set before your props so your aria-label wins; the role description reads “draggable card / column” instead of dnd-kit’s “sortable”.
• [data-disabled] means disabled. Upstream wrote data-disabled="false" on enabled columns and cards — the attribute was present, so every [data-disabled] selector matched them. It is now absent unless the part is disabled.
• Tokens, not a palette. Columns are bg-muted (upstream’s zinc-100 / zinc-900 are blocked by the package’s colour gate) with the decorative border-border, and a column or card inside KanbanOverlay is lifted with shadow-overlay.

Language

Every string Kanban produces is for assistive technology — the four drag announcements, the keyboard instructions, two role descriptions and two handle names. A screenshot never shows the wrong language; a screen reader does. They live in the kanban namespace and follow the nearest ComitorLocaleProvider — English by default, Vietnamese built in (set the language once, at the root). Switch the demo and move a deal: the announcement, the grip’s name and the instructions change with the provider; the stage names and the amounts are the app’s, formatted with useComitorLocale().locale.

• labels is Partial<KanbanLabels>, merged key by key over the provider’s table: the component’s own prop wins, then the nearest provider, then English.
• DEFAULT_KANBAN_LABELS is the English table since 3.0.0, and the component no longer reads it — spread it when you build a table of your own. The Vietnamese one is comitorMessagesVi.kanban.
• Four keys are functions — pickedUp, moved, dropped, cancelled — because a number and a column sit in the middle of the sentence and word order differs by language. They receive { variant, value, position, total, column } already computed. Functions cannot cross from a Server Component into a client one, so declare them in a client component.
• column is there only when the card has just entered another column, and it is that column’s key: the default English reads “…in column in-review”. In practice that is moved — by the time of the drop the card already sits in its new column, so dropped gives just the position. Map keys to names, as every demo on this page does; the helper below keeps the provider’s sentence and swaps the word.
• accessibility.announcements, dnd-kit’s own prop, is still honoured and wins over labels entirely.
• The provider chooses strings; it does not set lang. Vietnamese read with English rules is barely intelligible — keep <html lang> in step with the provider, as the demo does for its own region.

Read live from comitorMessagesEn.kanban and comitorMessagesVi.kanban: a card at position 2 of 5, and for moved a column name the app supplied in place of the key.

'use client'

import { useMemo, useState } from 'react'
import { Kanban, useComitorMessages } from '@comitor/ui'
import type { KanbanAnnouncementInfo, KanbanLabels } from '@comitor/ui'

// 1. Keep the provider's sentences — in whatever language it is — and swap the
//    column KEY for a name. Pass a stable names object (module constant or memo).
export function useColumnNames(names: Record<string, string>) {
  const t = useComitorMessages('kanban')
  return useMemo<Partial<KanbanLabels>>(() => {
    const named = (info: KanbanAnnouncementInfo) =>
      info.column === undefined ? info : { ...info, column: names[String(info.column)] ?? info.column }
    return {
      moved: (info) => t.moved(named(info)),
      dropped: (info) => t.dropped(named(info)),
    }
  }, [t, names])
}

// 2. Or write the sentence yourself. value is the card id, so the card can be named;
//    the words are then yours to translate (next-intl, in a Comitor app).
const ownSentences: Partial<KanbanLabels> = {
  pickedUp: ({ value, position, total }) => `Picked up ${titleOf(value)}, ${position} of ${total}.`,
}

// Either way, labels is merged key by key over the provider's table.
export function Board() {
  const [columns, setColumns] = useState(INITIAL)
  const labels = useColumnNames(COLUMN_NAMES)
  return <Kanban value={columns} onValueChange={setColumns} labels={labels}>…</Kanban>
}

Props

KanbanBoard takes asChild and div props, sets data-orientation, and starts as flex size-full gap-4 — a grid class replaces the flex, as every demo here does. UniqueIdentifier is dnd-kit’s string | number.

Kanban

KanbanColumn and KanbanItem

KanbanColumnHandle and KanbanItemHandle

KanbanOverlay

Known limitations

• A press on a handle starts a drag at once. The mouse and touch sensors have no activation distance or delay, as upstream. dnd-kit swallows the click that ends such a press — an asHandle card never sees a click, nor does anything inside it — and on touch a swipe that starts on a handle drags instead of scrolling. Every handle is touch-none: asHandle cards always were, and since 3.0.1 so are KanbanItemHandle and KanbanColumnHandle — in 3.0.0 a swipe on a grip scrolled the page instead of lifting the card. Workaround: a KanbanItemHandle on any card with something to click, with room to scroll between grips. A threshold needs your own sensors with an activationConstraint — from @dnd-kit/core, which your app then lists itself — and it replaces the keyboard sensor too: the board’s arrow-key logic is not exported, and dnd-kit’s default keyboard sensor moves 25px per key press instead of jumping to the next card.
• Column keys must not look like integers. JavaScript orders integer-like keys ("1", "2", "10") numerically, ahead of every other key, whatever order you insert them in. The board moves a column by rebuilding the object in the new key order, so with such keys the move is silently undone. Use todo, col-1 or a UUID.
• Ids are board-wide. dnd-kit keeps one registry per board, and the board treats any id that is also a key of value as a column. Two cards with the same id — or a card whose id is done on a board with a done column — break the drag.
• disabled freezes a column, not its cards. A disabled column cannot be picked up and is no longer a drop target itself, but its cards still are: drag over one of them and the card goes in. To make a column refuse cards, return true from cancelDrop (the card goes back on drop), or ignore the change in onValueChange so it never enters.
• strategy is ignored. It is accepted and stored, as upstream, but the sorting strategy of the board and of every column comes from orientation.

Accessibility

• Keyboard: Tab reaches every drag activator; Space or Enter picks up; the arrow keys move to the nearest card or column; Space, Enter or Tab drops; Escape cancels and restores. The full map is under Keyboard.
• Handles render a real <button type="button">; with asHandle the card or column itself gets role button and tabIndex 0. Every activator carries aria-roledescription (“draggable card”, “draggable column”), aria-describedby pointing at a visually hidden copy of labels.instructions, aria-pressed while lifted, and — on handles — aria-controls pointing at the card or column.
• Announcements go through dnd-kit’s live region (role="status", aria-live="assertive", aria-atomic): at pick-up, at every new position, at drop and at cancel. The region and the instructions mount after hydration; until then aria-describedby points at nothing.
• After a keyboard drop, dnd-kit puts focus back on the handle — also when the card changed column and React re-created its element.
• An asHandle card shows the package’s focus ring, ring-2 in ring/50 with a 2px offset — the same as Checkbox and RadioGroup. A handle built from Button keeps Button’s outline.
• KanbanBoard is a plain div with no role, so it carries no ARIA; its orientation is in data-orientation, for styling. Fixed in 3.0.1 — in 3.0.0 the board kept upstream’s aria-orientation, which axe reports as aria-allowed-attr; there, pass aria-orientation={undefined} to drop it.
• What the app still has to do. Name every handle after its card or column — the default name is the same for all of them. Put names into the announcements through labels — by default they give a position and a column key, never which card. Offer a way to move a card without dragging (WCAG 2.5.7, Dragging Movements): a Move to menu like the task board’s, or a status field in the card’s detail view. Keep interactive content out of asHandle cards. And mark the overlay copy inert, so a picture of a card that is still on the board is not read twice or tabbed into.

Related