Kanban

Installation

pnpm dlx shadcn@latest add @spaceui/components-spaceui-kanban

Usage

import {
  Kanban,
  KanbanBoard,
  KanbanColumn,
  KanbanColumnContent,
  KanbanColumnHandle,
  KanbanItem,
  KanbanItemHandle,
  KanbanOverlay,
} from '@/components/spaceui/kanban'

<Kanban value={columns} onValueChange={setColumns} getItemValue={(item) => item.id}>
  <KanbanBoard>
    {Object.entries(columns).map(([id, items]) => (
      <KanbanColumn key={id} value={id}>
        <KanbanColumnHandle>
          <h3>{id}</h3>
        </KanbanColumnHandle>
        <KanbanColumnContent value={id}>
          {items.map((item) => (
            <KanbanItem key={item.id} value={item.id}>
              <KanbanItemHandle>{item.content}</KanbanItemHandle>
            </KanbanItem>
          ))}
        </KanbanColumnContent>
      </KanbanColumn>
    ))}
  </KanbanBoard>
  <KanbanOverlay>
    <div className="bg-muted size-full rounded-md" />
  </KanbanOverlay>
</Kanban>

Examples

Overlay

Persist to a backend

Persisting moves

Keep value and onValueChange so the board reshuffles live while dragging, and use onValueCommit to save. It fires once per completed drag (never during the hover preview) with the final board and a previousValue snapshot, so you can update optimistically and roll back on error. Its meta.kind tells you whether a card moved ("item") or a column was reordered ("column").

const moveCard = api.board.moveCard.useMutation()
const reorderColumns = api.board.reorderColumns.useMutation()

<Kanban
  value={columns}
  onValueChange={setColumns}
  getItemValue={(task) => task.id}
  onValueCommit={(next, meta) => {
    if (meta.kind === "column") {
      reorderColumns.mutate({ order: Object.keys(next) })
      return
    }
    moveCard.mutate(
      {
        id: String(meta.event.active.id),
        to: meta.overContainer,
        index: meta.overIndex,
      },
      {
        onError: () => {
          setColumns(meta.previousValue) // roll back
          toast.error("Could not move the card. Your board was restored.")
        },
      },
    )
  }}
>
  {/* ... */}
</Kanban>

If a user might start another drag before the mutation settles, prefer a refetch in onError instead of restoring the snapshot, so a newer arrangement is not clobbered.

If you do not need the live cross-column preview, onMove is a simpler alternative: it fires once on drop for item moves and lets you apply the move yourself. Column reorders still arrive through onValueChange.

API Reference

Kanban

The root component that provides the kanban context and manages the items state.

KanbanCommitMeta<T> is { kind: "item" | "column"; event: DragEndEvent; activeContainer: string; activeIndex: number; overContainer: string; overIndex: number; previousValue: Record<string, T[]> }.

KanbanBoard

The horizontal container for kanban columns.

KanbanColumn

An individual column within the kanban board.

KanbanColumnHandle

The drag handle for a column (if columns are sortable).

KanbanColumnContent

The scrollable area within a column that holds the items.

KanbanItem

An individual draggable item within a column.

KanbanItemHandle

The drag handle for an individual item.

KanbanOverlay

The ghost element displayed during a drag operation.

All 6 variations

Kanban board with frame columns

Minimal kanban with stacked frame

Feature roadmap kanban with progress