# Kanban

A drag-and-drop board of columns and cards.

- Category: Core Elements
- Page: https://wunderui.com/components/kanban
- Tier: Core and Pro

## Install

Kanban ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { Kanban, ColumnHeader, KanbanCard, KanbanCardData, KanbanCardItem, KanbanCardProps, KanbanColumn, KanbanColumnAction, KanbanColumnHeader, KanbanColumnHeaderProps, KanbanColumnStatus, KanbanIndicator, KanbanLayout } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { Kanban, type KanbanColumn } from "@/components/ui/kanban"

const COLUMNS: KanbanColumn[] = [
  { id: "todo", title: "To do", cards: [{ id: "k1", title: "Design onboarding flow", tag: { label: "Design", color: "purple" } }] },
  { id: "done", title: "Done", cards: [{ id: "k2", title: "Ship the area chart", tag: { label: "Shipped", color: "green" } }] },
]

export function Board() {
  return <Kanban columns={COLUMNS} />
}
```

Expected result: You see two columns, To do and Done, each with one card and a count of 1. Drag a card to the other column, or Tab to a card, press Space, then ArrowRight and Space.

## When to use

### Use Kanban for

- Tasks, deals or tickets that move through stages
- A roadmap whose cards carry a progress value
- A board that has to work with the keyboard as well as the pointer

### Use something else

- [Data Table](https://wunderui.com/components/data-table) for many items that people sort, filter or edit field by field
- [List Group](https://wunderui.com/components/list-group) for one list of similar rows with no stages
- [Item Card](https://wunderui.com/components/item-card) for a single object on its own row, with one action

## Keyboard

The board is one tab stop: Tab reaches the card that had focus last, or the first card, and the arrow keys do the rest. Space or Enter picks a card up and drops it.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the board, to the card that had focus last or to the first card, and out of it again. The other cards are not tab stops. |
| `ArrowUp` or `ArrowDown` | Moves focus to the card above or below in the same column. At the first or last card nothing happens. |
| `ArrowLeft` or `ArrowRight` | Moves focus to the card at the same row in the next column to the left or right. Empty columns are skipped, and a shorter column gives its last card. |
| `Space` or `Enter` | Picks up the focused card. The card lifts and its focus ring stays on it. Press either key again to drop it where it is shown, which calls `onColumnsChange` once. Dropping a card where it started changes nothing. |
| `ArrowUp` or `ArrowDown` | While a card is held: moves it up or down inside its column. It stops at the first and last place. |
| `ArrowLeft` or `ArrowRight` | While a card is held: moves it to the next column on that side, to the same row or to the end of a shorter column. |
| `Escape` | Puts the held card back where it started and announces it. It does not close a dialog the board sits in. |

A board wider than its container takes a tab stop of its own first, so the arrow keys can scroll it. Tab or a click elsewhere while a card is held cancels the move.

## Behavior

What the board does with state, content, the DOM and motion.

- **Controlled or not:** With a change handler the board is controlled: it shows the columns you pass and reports the new columns after each drop. Without one it keeps its own copy and ignores new columns.
- **Pointer:** Cards use the browser's native drag and drop. A dashed Drop here slot follows the pointer: over the upper half of a card it sits above it, over the lower half below it. Dropping puts the card there; releasing outside every column does nothing.
- **Keyboard:** The keyboard move is previewed on the board while the card is held and reported once, at the drop. Losing focus or moving focus to another card cancels the move.
- **Announcements:** A polite live region reads each step: picked up with column and position, the new place after every move, dropped, or move cancelled. Cards describe themselves as sortable items.
- **Empty columns:** A column without cards shows its title, a count of 0 and a dashed box that says it is empty, and takes a drop at its start.
- **Layouts and scrolling:** Board scrolls sideways when the columns are wider than the container and then takes focus for the arrow keys; framed does the same in a frame. On a narrow screen a column takes the board's width. Stacked makes every column full width.
- **Height:** Each column is as tall as its cards; pass `items-start` in `className` to keep shorter columns short, or give the board a fixed height to keep the page still while cards move.
- **Limits and status strips:** A column with `limit` counts against it; when it is full the count turns yellow, a warning strip appears and Add item is disabled. Cards can still be moved into it. A `status` strip shows your own message, with Retry or Undo as a plain button; a new strip is announced in the live region.
- **Motion and reduced motion:** Fill, rim and shadow change with a short colour transition. The picked-up lift is set at once because the keyboard drives it, and nothing moves along a path, so reduced motion needs no fallback.

## Anatomy

- `Kanban`: The board, drawn from your columns: a row that scrolls sideways, columns sharing one 16 px frame, or columns stacked. Cards move by drag or keyboard, and every move is reported.
- `Column`: One stage, 352 px wide (the board's width on a narrower screen), in the page tone with a 1 px rim, 12 px padding and 12 px corners. While a card is dragged over it the rim turns dark grey and a dashed Drop here slot marks where the card lands. An empty column shows a dashed box and still takes a drop.
- `Column header`: The column title in 14 px semibold, the card count as a grey pill badge ("2 / 3" against a limit, yellow when the column is full) and, with column actions, a … button that opens the column menu.
- `Status strip`: A strip under the header from the column's `status`: a warning, a failed save with Retry or a done move with Undo, in the tint of its tone. A full column without its own status shows the limit warning. A new strip is read out once.
- `Add item`: A plain button at the end of every column, drawn with `onAddCard`. It is disabled while the column is at its limit.
- `Card`: One draggable item with a button role, a 12 px radius and 12 px padding, and a grip in the top right corner. It has hover, pressed and focus looks, and a picked-up look with a small lift. A card can also show a picture or an icon tile.
- `Card title`: The card title in 14 px medium, next to the icon tile when there is one. It wraps onto more lines when it is long.
- `Progress`: A bar with its percentage under the title, drawn when the card has a progress value from 0 to 100. It is named after the card title for assistive technology.
- `Tags`: Light Badges in pill shape, from `labels` (or the older single `tag`), in the Badge colours you choose.
- `Meta`: The footer: due date, comments and checklist with 12 px icons in 11 px tertiary text, and the people on the right as a small avatar stack.
- `Announcer`: A hidden live region that reads out each pick-up, move, drop and cancel with the column title and position. It is not in the figure.
- `KanbanCard`: The task card of the board on its own, with the content of a board card: tags, a due date, comments, checklist progress and people, plus a picture, a progress bar or an icon tile. With `onClick` it is a button, and `selected` draws the indigo rim. It replaces KanbanCardItem.
- `KanbanColumnHeader`: The top of a column on its own: a coloured dot, the title, a count badge and the buttons to add a card and open the menu. It is 40 px high with or without buttons. It replaces ColumnHeader.
- `ColumnHeader`
- `KanbanCardItem`
- `Column`
- `Column Header`
- `Column Indicator`
- `Column Meta`
- `Column Empty`
- `Drop Placeholder`
- `Column Status`

## Best practices

### When to use

- Use a Kanban when people move items through stages, such as tasks from To do to Done. When they sort, filter or edit fields across many items, use Data Table.

### Do

- Pass the columns change handler and store the result. Without it the board keeps its own copy: moves aren't reported and a new columns value is ignored.
- Give columns short, distinct titles. Screen readers hear them with every move, for example column Done, position 2 of 4.
- Give the board a height when other things sit around it. A board is as tall as its tallest column, so it changes height as cards move.
- Switch to the stacked layout on narrow screens. The board layout scrolls sideways, and columns past the edge are easy to miss.
- Offer another way to move a card on touch screens, such as a menu on your own card. Dragging uses the browser's native drag and drop, which many touch browsers don't start with a finger.
- Keep the column title the stage name: the total goes into meta and the stage colour into indicator.

### Don't

- Don't add your own key or drag handlers to the cards. Space or Enter picks a card up, the arrow keys move it, and Escape puts it back.

## API reference

### Kanban

| Prop | Type | Default | Description |
|---|---|---|---|
| columns* | KanbanColumn[] |  | The columns and their cards. A column is `{ id, title, cards, limit?, status? }`: `limit` is a work-in-progress limit, `status` is `{ tone, text, action? }` with tone warning, error or success. A card is `{ id, title }` plus any of `labels`, `due`, `comments`, `checklist`, `assignees`, `progress` (0 to 100), `image` (`{ src, alt }`), `icon` with `iconColor`, and the older `tag` and `meta`. Every `id` must be unique on the board. Without `onColumnsChange` this is only the starting state. |
| className | string |  | Classes for the board, for example a fixed height such as `h-96` or a width such as `w-full`. |
| columnActions | { label: string; onSelect: (columnId: string) => void }[] |  | Entries of the column menu behind the … button in each column header. Without them the button is not drawn. |
| layout | "board" \| "stacked" \| "framed" | "board" | `board` puts grey columns side by side and scrolls sideways. `framed` joins them in one frame with a line between them. `stacked` puts them under each other at full width. |
| onAddCard | (columnId: string) => void |  | Draws Add item at the end of every column and is called with the column's id. Add the card to your columns yourself. |
| onColumnsChange | (columns: KanbanColumn[]) => void |  | Called with the new columns after a drop, from the pointer or the keyboard. Passing it makes the board controlled: store the result and pass it back as `columns`. |

### ColumnHeader

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | React.ReactNode |  |  |
| className | string |  |  |
| count | React.ReactNode |  | Card count, or e.g. "3 / 3" when the column has a WIP limit. |
| dotClassName | string |  | Dot colour — any Tailwind bg class, defaults to muted. |
| onAdd | () => void |  |  |
| onMenu | () => void |  |  |

### KanbanCard

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | React.ReactNode |  | The task name. Required. |
| assignees | Person[] |  | The people on the task, shown as a stack of avatars at the end of the footer. |
| checklist | { done: number; total: number } |  | Checklist progress as `{ done, total }`, shown in the footer. |
| className | string |  | Extra classes on the card, such as its width. |
| comments | number |  | The number of comments in the footer. Hidden at 0. |
| due | React.ReactNode |  | The due date in the footer, with a calendar icon. |
| icon | React.ReactNode |  | An icon in a 32 px tint tile left of the title. |
| iconColor | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "alternative" |  | The hue of the icon tile. Indigo by default. |
| image | { src: string; alt: string } |  | A picture at the top of the card as `{ src, alt }`. Pass `alt=""` for a decorative one. |
| labels | { label: React.ReactNode; color?: BadgeColor }[] |  | Tags above the title, each a label and a badge colour. |
| meta | React.ReactNode |  | Free text at the start of the footer, such as a date without an icon. |
| onClick | () => void |  | Makes the card a button with hover and pressed fills, and runs on Enter and Space. |
| progress | number |  | 0 to 100: a progress bar with its percentage under the title. |
| progressLabel | string |  | Name of the progress bar for assistive technology. Default: the title when it is a string. |
| selected | boolean |  | Draws the indigo rim. A card that is given `selected` and `onClick` is a toggle button. |
| showHandle | boolean |  | A grip in the top right corner. Decorative: the whole card is the drag target. |

### KanbanCardItem

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | React.ReactNode |  |  |
| assignees | Person[] |  |  |
| checklist | { done: number; total: number } |  |  |
| className | string |  |  |
| comments | number |  |  |
| due | React.ReactNode |  |  |
| icon | React.ReactNode |  | An icon in a 32 px tint tile left of the title. |
| iconColor | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "alternative" |  | Hue of the icon tile. Default indigo. |
| image | { src: string; alt: string } |  | A picture at the top of the card. `alt` says what it shows; pass `""` for a purely decorative one. |
| labels | { label: React.ReactNode; color?: BadgeColor }[] |  |  |
| meta | React.ReactNode |  | Free text at the start of the footer, e.g. a date without an icon (the board's older `meta`). |
| onClick | () => void |  |  |
| progress | number |  | 0 to 100: a progress bar with its percentage under the title. |
| progressLabel | string |  | Name of the progress bar for assistive technology. Default: the title when it is a string. |
| selected | boolean |  |  |
| showHandle | boolean |  | A grip in the top right corner. Decorative: the whole card is the drag target. |

### KanbanColumnHeader

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | React.ReactNode |  | The column name. Required. |
| className | string |  | Extra classes on the header. |
| count | React.ReactNode |  | The number of cards, or a text such as `3 / 3` when the column has a limit. |
| dotClassName | string | "bg-muted-foreground" | A background class for the dot, such as `bg-primary`. Muted by default. |
| onAdd | () => void |  | Shows the add button, named Add card, and runs when it is pressed. |
| onMenu | () => void |  | Shows the menu button, named Column menu, and runs when it is pressed. |

## Examples

### Card types: default, image, progress and icon

### Layout: board, framed and stacked

### Moving cards: pointer and keyboard

### Card: the task card on its own, in four kinds

### Column header: dot, title, count and buttons

## In context

### Sprint board: the page owns the columns

The page owns the columns and hears about every drop, and the counts above the board come from the same state. Reset puts the cards back.

### Roadmap: cards with progress

A card with a progress value shows a bar. It keeps its value when you move it to another stage.

### Column dot and total

A column takes an `indicator` (the stage colour as a dot) and `meta` (quiet text after the title, e.g. the total), so the title stays the stage name. `title` may be formatted; then `label` names the column in announcements.

## For AI agents

`get_component("kanban")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
