# Kanban board

> A complete project board inside the Arc app shell, with projects, saved views and live cycle progress in the sidebar, filters for priority, labels and assignee, and cards you can drag between columns or swimlanes. A details panel slides over the board to edit status, priority, assignee, labels, estimate and due date, with sub-issues, linked pull requests, activity and comments.

- Type: Screen (a complete app view, installed as a block)
- Page: https://uiarc.dev/components/screens/kanban-board
- Markdown: https://uiarc.dev/components/screens/kanban-board/markdown

- Access: Arc Pro
- Registry id: `kanban-board`
- Source file: `registry/blocks/kanban-board/kanban-board.tsx`
- Built from: Avatar, Checkbox, Segmented control, Animated counter
- Keywords: kanban, board, drag and drop, swimlanes, wip limit, issue tracker, project management, sprint, cycle, app screen

Use this for a team's issue or task board. Load columns, people and cards from your tracker, persist onCardsChange (it receives the full ordered list after every move or edit), and set limit on columns that need WIP limits.

## When to use

- A team's issue board with projects, filters and a details panel.
- Pipelines where ordering within a stage matters.
- Boards that need a per person swimlane view.

## When not to use

- Scheduling on dates; use gantt-timeline or week-calendar.
- Read only status summaries; use a table.
- Hundreds of cards per column; virtualize or use customers-table.

## Installation

Kanban board is part of Arc Pro. The live preview is public; the source and install command need Pro.

### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/kanban-board
```

### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

## Usage

```tsx
import { KanbanBoard } from "@/components/arc/blocks/kanban-board/kanban-board";

export function ProjectBoard({ issues, team, projects }) {
  const [cards, setCards] = useState(issues);
  return (
    <div style={{ height: "100dvh" }}>
      <KanbanBoard
        workspace="Acme"
        projects={projects}
        people={team}
        currentUser="me"
        cards={cards}
        onCardsChange={next => { setCards(next); saveOrder(next); }}
      />
    </div>
  );
}
```

## API reference

### KanbanBoard

A full project board screen inside the Arc screen shell. The sidebar holds My issues, the current cycle and all issues, projects with their own tinted icons and open counts, and the running cycle at its foot (points done on Arc's Progress, days left, day of the cycle), which opens the cycle view. The header has a filter row built from Arc's search field, popover pickers for priority, labels and assignee (each trigger swaps its icon for the count of active choices, so nothing shifts) and Arc's segmented control for Status or Assignee grouping; on a phone the row wraps into two. Cards show id, linked pull request and Figma file, assignee, priority, labels, sub-issue progress, comments and due date. Cards drag physically between columns and swimlanes with live WIP limits, and a details panel floats over the right of the board with editable properties, sub-issues, links, activity and comments.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `KanbanColumn[]` | `Backlog, Todo, In progress, In review, Done` | Columns in order. Set limit for a WIP limit and kind (backlog, unstarted, started, review, done) for the status mark. |
| `people` | `KanbanPerson[]` | `sample team` | Assignees, used for avatars, swimlanes, the assignee filter and the assignee picker. |
| `cards` | `KanbanCard[]` | – | Controlled cards in board order. Leave out for uncontrolled use. |
| `defaultCards` | `KanbanCard[]` | `sample cards` | Initial cards when uncontrolled. |
| `onCardsChange` | `(cards: KanbanCard[]) => void` | – | Called with the full ordered list after every move, edit, sub-issue toggle or new card. |
| `defaultGroupBy` | `"status" \| "assignee"` | `"status"` | Start in columns only or in swimlanes by assignee. |
| `currentUser` | `string` | `first person` | Person id for new cards, comments, activity and the My issues view. |
| `title` | `string` | – | Renames the first project, which the board opens on. |
| `projects` | `KanbanProject[]` | `four sample projects` | Projects in the sidebar, each with a key for new card ids, a tone and an optional icon (KanbanIcon, such as a lucide icon) drawn in that tone. Cards without a project belong to the first one. |
| `labels` | `KanbanLabel[]` | `sample labels` | Labels cards can carry, matched by id or name, each with a tone and an optional icon drawn in that tone on an Arc badge. Without an icon a tag glyph is used; labels never use coloured dots. |
| `defaultProject` | `string` | – | Project id the board opens on. Defaults to the first project. |
| `workspace` | `string` | `"Larkspur"` | Workspace name in the sidebar and the trail. |
| `today` | `string` | `"Nov 12"` | Today's date in the cards' "Nov 12" form, for due soon and overdue marks and the cycle's day count. |
| `cycle` | `{ name: string; start: string; end: string }` | `{ name: "Cycle 24", start: "Nov 9", end: "Nov 22" }` | The running cycle shown at the foot of the sidebar and in the details panel, with dates in the "Nov 12" form. |
| `activity` | `Record<string, KanbanActivity[]>` | `sample history` | Seeded activity and comments per card id. Cards without an entry get a short generated history. |
| `className` | `string` | – | Extra class on the root. |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| Arrow keys | Move focus between cards, across columns and lanes. The highlight lands instantly. |
| Enter | Opens the focused card's details. |
| Space | Lifts the focused card; arrows move it, Space or Enter drops it. |
| Shift + arrow up / down | Moves a lifted card to the neighbouring swimlane. |
| J / K | Next and previous issue while the details panel has focus. |
| / | Focuses the filter field. |
| C | Opens a new issue in the Todo column. |
| ? | Lists the keyboard shortcuts. |
| Escape | Cancels a drag, closes a list, or closes the details panel and returns focus to the card. |

## Accessibility

- Cards are one tab stop with roving focus; each is a button with a draggable role description and a label with id, title, assignee and priority.
- Every pick up, move and drop is announced in a live region with the column and position, as is copying a link.
- Filters, properties and pickers are listboxes inside Arc's Popover with aria-selected options and an instant keyboard highlight; Escape and outside presses close them and focus returns to the trigger.
- Sub-issues are Arc checkboxes with their text as the label; icon buttons in the details bar carry names and tooltips with their shortcut.
- The details panel is a labelled region that takes focus when it opens and gives it back to the card when it closes.
- Priority, due state, WIP limits and pull request state are shown with text or shape as well as colour.

## Motion

- The lifted card rides pointer motion values, lifts to 1.02 and tilts on a critically damped spring from horizontal speed.
- Neighbours glide aside with layout springs as the slot moves; on release a critically damped spring chases the slot's live position.
- Switching to swimlanes flies every card to its lane with shared layout ids. Typing a filter or moving a card from the keyboard updates instantly.
- The details panel slides 24px in on the smooth spring and leaves faster; switching cards crossfades its content once.
- Counts roll on Arc's animated counter, filter triggers crossfade their icon to a count in a fixed slot, and hover fills are instant.
- Reduced motion drops tilt, travel and crossfades; drops land at once.

## Responsive behavior

- At desktop widths four columns show and Done peeks in with an edge fade; the board scrolls sideways and each column scrolls on its own.
- Below 900px the sidebar is a sheet; below 600px columns are almost full width with snap, the filter row scrolls and the details panel covers the board.
- Auto scroll works on the board and the column under the pointer while dragging near an edge.

## Performance

- Only the dragged card moves every frame, through transforms; hit testing reads a few rects per move.
- Cards are memoized and use position only layout animation.
- Comfortable up to a few hundred cards.

## Notes for AI

- Choose this for issue trackers, sprint boards, hiring pipelines or any status workflow with manual ordering, shown as a whole app screen.
- It fills its parent, so give the parent a height; the screen shell handles the sidebar sheet below 900px and the phone layout below 600px.
- Persist onCardsChange: the array order is the order within each column. Cards you move or edit stay visible until the filter changes.
- Touch starts a drag after a short press so swipes still scroll the board.
- Links are content: map your pull requests (kind github, with state) and design files (kind figma) onto card.links.

## Related

- [Project board](https://uiarc.dev/components/screens/project-board/markdown): A full project overview screen: live progress stats, a milestone track that picks the task list, recent activity and a team panel. Tasks group by stage with filters and drag to reorder, and the task panel edits fields, subtasks and comments in place.
- [Gantt timeline](https://uiarc.dev/components/screens/gantt-timeline/markdown): A roadmap app screen where you drag gantt bars to reschedule, follow dependency arrows past a today line, zoom by day, week or month, and group by phase, team or owner. Selecting a task opens a details panel for owner, dates and progress, and the same plan also shows as a sortable list and an updates feed.
- [Week calendar](https://uiarc.dev/components/screens/week-calendar/markdown): A full calendar app with a week grid. Drag to create, move and resize events, answer invites right on the grid, and overlay teammates' calendars from a side panel with a mini month and the next meeting. Pages for invites and booking links complete the app.

## Guidance for AI tools

Blocks are complete, self-contained screens with sample data. Replace the sample data and connect the callbacks described above. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt