# Kanban
URL: /docs/web/components/kanban

A drag-and-drop kanban board with sortable columns and items, column reordering, overlay previews, and final drop zones for archiving or completing tasks.

**Demo:**

```tsx
'use client';

import { useCallback, useMemo, useState } from 'react';

import {
  Kanban,
  KanbanBoard,
  KanbanColumn,
  KanbanColumnHandle,
  KanbanFinalColumn,
  KanbanFinalZone,
  KanbanItem,
  KanbanItemTitle,
  KanbanOverlay
} from '@docyrus/ui/components/kanban';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { PropControls, type PropControl } from '@/components/prop-controls';

// ─── Types ───────────────────────────────────────────────────────────────────

interface Task {
  id: string;
  title: string;
  priority: 'low' | 'medium' | 'high';
  assignee: string;
  tag?: string;
}

// ─── Data ────────────────────────────────────────────────────────────────────

const PRIORITY_STYLES: Record
      ) : <span className="truncate text-sm font-medium leading-snug">{task.title}</span>}
      <div className="flex items-center justify-between">
        <div className="flex items-center gap-1.5">
          {task.tag && (
            <span className="rounded-sm bg-muted px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground">
              {task.tag}
            </span>
          )}
          <span
            className={cn(
              'rounded px-1.5 py-0.5 text-[10px] font-bold uppercase leading-none tracking-wide',
              PRIORITY_STYLES[task.priority]
            )}>
            {task.priority}
          </span>
        </div>
        <span className="flex size-6 items-center justify-center rounded-full bg-muted text-[10px] font-medium">
          {task.assignee}
        </span>
      </div>
    </div>
  );
}

// ─── KanbanDemo ──────────────────────────────────────────────────────────────

export function KanbanDemo() {
  const [columns, setColumns] = useState(INITIAL_TASKS);
  const [archivedCount, setArchivedCount] = useState(0);
  const [showDone, setShowDone] = useState(true);
  const [showArchive, setShowArchive] = useState(true);
  const [showCounts, setShowCounts] = useState(true);
  const [flatCursor, setFlatCursor] = useState(false);
  const [open, setOpen] = useState(false);
  const [clickedItem, setClickedItem] = useState<string | null>(null);

  const taskMap = useMemo(() => {
    const map = new Map<string, Task>();

    for (const items of Object.values(columns)) {
      for (const item of items) {
        map.set(item.id, item);
      }
    }

    return map;
  }, [columns]);

  const handleFinalDrop = useCallback((item: Task, finalColumnId: string | number) => {
    const targetColumn = String(finalColumnId);

    setColumns(prev => ({
      ...prev,
      [targetColumn]: [...(prev[targetColumn] ?? []), item]
    }));

    if (targetColumn !== 'done') {
      setArchivedCount(prev => prev + 1);
    }
  }, []);

  const controls: PropControl[] = [
    {
      type: 'boolean', name: 'showDone', label: 'Done Zone', value: showDone, onChange: setShowDone
    },
    {
      type: 'boolean', name: 'showArchive', label: 'Archive Zone', value: showArchive, onChange: setShowArchive
    },
    {
      type: 'boolean', name: 'showCounts', label: 'Counts', value: showCounts, onChange: setShowCounts
    },
    {
      type: 'boolean', name: 'flatCursor', label: 'Flat Cursor', value: flatCursor, onChange: setFlatCursor
    }
  ];

  return (
    <div className="w-full">
      <div className="mb-3 flex justify-end">
        <button
          type="button"
          className="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm font-medium transition-colors hover:bg-accent"
          onClick={() => setOpen(prev => !prev)}>
          <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" /><circle cx="12" cy="12" r="3" /></svg>
          Configure
          <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('transition-transform duration-200', open && 'rotate-180')}><path d="m6 9 6 6 6-6" /></svg>
        </button>
      </div>
      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 rounded-lg border border-border bg-card p-4">
            
          </div>
        </div>
      </div>

      {clickedItem && (
        <div className="mb-3 flex items-center gap-2 rounded-lg border border-primary/20 bg-primary/5 px-3 py-2 text-sm">
          <span className="font-medium text-primary">Item clicked:</span>
          <span className="text-foreground">{taskMap.get(clickedItem)?.title ?? clickedItem}</span>
          <button
            type="button"
            className="ml-auto text-muted-foreground hover:text-foreground"
            onClick={() => setClickedItem(null)}>
            <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M18 6 6 18" /><path d="m6 6 12 12" /></svg>
          </button>
        </div>
      )}

      
                </div>

                <div className="flex flex-col gap-2 p-2">
                  {items.map(task => (
                    
                  ))}
                  {items.length === 0 && (
                    <p className="py-8 text-center text-xs text-muted-foreground">
                      No tasks
                    </p>
                  )}
                </div>
              
            );
          })}
        

        {(showDone || showArchive) && (
          
            )}
            {showArchive && (
              
            )}
          
        )}

        
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-kanban
```

**Dependencies:**
- [@dnd-kit/sortable](https://www.npmjs.com/package/@dnd-kit/sortable)
- [@dnd-kit/core](https://www.npmjs.com/package/@dnd-kit/core)
- [@dnd-kit/utilities](https://www.npmjs.com/package/@dnd-kit/utilities)
- [@radix-ui/react-slot](https://www.npmjs.com/package/@radix-ui/react-slot)
- [@types/react](https://www.npmjs.com/package/@types/react)

## Usage

```tsx
import {
  Kanban,
  KanbanBoard,
  KanbanColumn,
  KanbanColumnHandle,
  KanbanItem,
  KanbanItemHandle,
  KanbanItemTitle,
  KanbanOverlay,
  KanbanFinalZone,
  KanbanFinalColumn
} from '@docyrus/ui/components/kanban';

const [columns, setColumns] = useState({
  todo: [{ id: '1', title: 'Task 1' }, { id: '2', title: 'Task 2' }],
  done: [{ id: '3', title: 'Task 3' }]
});

        {items.map((item) => (
          
        ))}
      
    ))}
  
  

```

### With Final Drop Zones

Use `finalColumns` on `Kanban` and `KanbanFinalZone` + `KanbanFinalColumn` to create drop targets that remove items from columns (e.g., archive or complete).

```tsx

  
    
  

  

```

### With Custom Overlay

The `KanbanOverlay` children can be a render function that receives the active item's value and variant.

```tsx

```

### Item Detail

Use `onItemClick` and `KanbanItemTitle` to open item details. `KanbanItemTitle` creates a clickable title zone that prevents drag-and-drop and triggers the callback instead.

```tsx

        {items.map((item) => (
          
            <p className="text-sm text-muted-foreground">{item.description}</p>
          
        ))}
      
    ))}
  
  

```

### Vertical Layout

Set `orientation="vertical"` for a top-to-bottom column layout.

```tsx

```

## Components

| Component | Description |
|-----------|-------------|
| `Kanban` | Root provider. Wraps `DndContext` with collision detection, keyboard navigation, and screen reader announcements. |
| `KanbanBoard` | Container for columns. Renders a `SortableContext` for column reordering. |
| `KanbanColumn` | A sortable column container. Renders a `SortableContext` for its items. |
| `KanbanColumnHandle` | Drag handle for reordering columns. Must be inside `KanbanColumn`. |
| `KanbanItem` | A sortable item within a column. Supports cross-column drag. |
| `KanbanItemHandle` | Drag handle for items. Must be inside `KanbanItem`. |
| `KanbanItemTitle` | Clickable title zone inside `KanbanItem`. Prevents drag-and-drop and fires `onItemClick`. |
| `KanbanOverlay` | Portal-rendered drag overlay preview. Accepts a render function for custom previews. |
| `KanbanFinalZone` | Container for final drop columns. Only visible during item drag. |
| `KanbanFinalColumn` | A droppable target inside `KanbanFinalZone` that triggers `onFinalDrop`. |

## API Reference

### Kanban

The root component. Manages drag state, collision detection, and value changes.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `Record<UniqueIdentifier, T[]>` | — | Column data. Keys are column IDs, values are item arrays. |
| `onValueChange` | `(columns: Record<UniqueIdentifier, T[]>) => void` | — | Called when items are moved between or within columns. |
| `getItemValue` | `(item: T) => UniqueIdentifier` | — | Extracts a unique ID from each item. Required when `T` is an object. |
| `onMove` | `(event: DragEndEvent & { activeIndex: number; overIndex: number }) => void` | — | Called on reorder instead of `onValueChange` when provided. Useful for server-side persistence. |
| `onFinalDrop` | `(item: T, finalColumnId: UniqueIdentifier) => void` | — | Called when an item is dropped onto a `KanbanFinalColumn`. |
| `onItemClick` | `(value: UniqueIdentifier) => void` | — | Called when a `KanbanItemTitle` is clicked. Receives the item's value. |
| `finalColumns` | `UniqueIdentifier[]` | — | IDs of final drop columns (must match `KanbanFinalColumn` values). |
| `strategy` | `SortableContextProps['strategy']` | `verticalListSortingStrategy` | Sorting strategy for items within columns. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Board layout direction. |
| `flatCursor` | `boolean` | `false` | Use `cursor-default` instead of `cursor-grab` for all drag handles. |
| `modifiers` | `DndContextProps['modifiers']` | — | dnd-kit modifiers for constraining drag movement. |
| `accessibility` | `DndContextProps['accessibility']` | — | Custom accessibility announcements (merged with built-in announcements). |

### KanbanBoard

Container for columns. Must be inside `Kanban`.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `asChild` | `boolean` | `false` | Render as child element using `Slot`. |
| `className` | `string` | — | Additional CSS classes. |

### KanbanColumn

A sortable column. Must be inside `KanbanBoard` or `KanbanOverlay`.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `UniqueIdentifier` | — | Unique column identifier. Must match a key in `Kanban`'s `value`. |
| `asChild` | `boolean` | `false` | Render as child element using `Slot`. |
| `asHandle` | `boolean` | `false` | Make the entire column a drag handle. |
| `disabled` | `boolean` | `false` | Disable column dragging. |
| `className` | `string` | — | Additional CSS classes. |

### KanbanColumnHandle

Drag handle for columns. Must be inside `KanbanColumn`.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `asChild` | `boolean` | `false` | Render as child element using `Slot`. |
| `disabled` | `boolean` | — | Override column's disabled state. |
| `className` | `string` | — | Additional CSS classes. |

### KanbanItem

A sortable item. Must be inside `KanbanColumn` (within `KanbanBoard` or `KanbanOverlay`).

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `UniqueIdentifier` | — | Unique item identifier. Must match the value returned by `getItemValue`. |
| `asChild` | `boolean` | `false` | Render as child element using `Slot`. |
| `asHandle` | `boolean` | `false` | Make the entire item a drag handle. |
| `disabled` | `boolean` | `false` | Disable item dragging. |
| `className` | `string` | — | Additional CSS classes. |

### KanbanItemHandle

Drag handle for items. Must be inside `KanbanItem`.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `asChild` | `boolean` | `false` | Render as child element using `Slot`. |
| `disabled` | `boolean` | — | Override item's disabled state. |
| `className` | `string` | — | Additional CSS classes. |

### KanbanItemTitle

Clickable title zone inside `KanbanItem`. Intercepts pointer events to prevent drag-and-drop activation, and fires the root `onItemClick` callback on click. Renders a `<button>` by default.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `asChild` | `boolean` | `false` | Render as child element using `Slot`. |
| `className` | `string` | — | Additional CSS classes. |

### KanbanOverlay

Portal-rendered drag preview overlay.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode \| ((params: { value: UniqueIdentifier; variant: 'column' \| 'item' }) => ReactNode)` | — | Static content or render function for custom preview. Receives the active item's value and whether it's a column or item. |
| `container` | `Element \| DocumentFragment \| null` | `document.body` | Portal container. |

### KanbanFinalZone

Container for final drop targets. Shows `data-dragging` attribute when an item is being dragged.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `asChild` | `boolean` | `false` | Render as child element using `Slot`. |
| `className` | `string` | — | Additional CSS classes. |

### KanbanFinalColumn

A droppable zone for permanently removing items from columns (e.g., archive, complete, delete).

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `UniqueIdentifier` | — | Unique identifier. Must be listed in `Kanban`'s `finalColumns` array. |
| `asChild` | `boolean` | `false` | Render as child element using `Slot`. |
| `className` | `string` | — | Additional CSS classes. |

### Data Attributes

| Attribute | Component | Description |
|-----------|-----------|-------------|
| `data-dragging` | `KanbanColumn`, `KanbanItem`, `KanbanColumnHandle`, `KanbanItemHandle`, `KanbanItemTitle`, `KanbanFinalZone`, `KanbanFinalColumn` | Present when the element (or its parent) is being dragged. |
| `data-disabled` | `KanbanColumn`, `KanbanItem`, `KanbanColumnHandle`, `KanbanItemHandle` | Present when the element is disabled. |
| `data-value` | `KanbanItem` | The item's unique identifier value. Used internally by `KanbanItemTitle`. |
| `data-over` | `KanbanFinalColumn` | Present when a dragged item is hovering over the final column. |
| `data-orientation` | `KanbanBoard` | Current board orientation (`horizontal` or `vertical`). |
| `data-slot` | All | Component identifier (`kanban-board`, `kanban-column`, `kanban-item`, etc.). |

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Space` / `Enter` | Pick up or drop the focused item/column. |
| `Arrow Keys` | Move the picked-up item/column in the corresponding direction. |
| `Escape` | Cancel the current drag operation. |