Kanban Board

Installation

npx hanzo-ui@latest add kanban

Usage

import { KanbanBoard } from "@/registry/default/ui/kanban"

const [board, setBoard] = useState({
  id: "board-1",
  title: "Project Board",
  columns: [
    {
      id: "todo",
      title: "To Do",
      cards: [
        {
          id: "card-1",
          title: "Setup project",
          description: "Initialize the project structure",
          priority: "high",
          assignee: "John Doe",
          dueDate: "2024-12-31",
          labels: [{ id: "bug", name: "Bug", color: "#ef4444" }],
          createdAt: new Date().toISOString(),
          updatedAt: new Date().toISOString(),
        }
      ],
      limit: 5
    },
    {
      id: "doing",
      title: "In Progress",
      cards: [],
    },
    {
      id: "done",
      title: "Done",
      cards: [],
    }
  ],
  labels: [
    { id: "bug", name: "Bug", color: "#ef4444" },
    { id: "feature", name: "Feature", color: "#22c55e" },
    { id: "improvement", name: "Improvement", color: "#3b82f6" }
  ]
})

<KanbanBoard
  board={board}
  onUpdateBoard={setBoard}
  className="h-screen"
/>

Features

Drag and Drop

• Card Movement: Drag cards between columns
• Card Reordering: Reorder cards within columns
• Visual Feedback: Smooth animations and drag overlay
• Column Limits: Respect maximum card limits per column

Card Management

• Create Cards: Add new cards to any column
• Edit Cards: Update card details in-place
• Delete Cards: Remove cards with confirmation
• Card Actions: Dropdown menu for card operations

Card Properties

• Title & Description: Basic card information
• Priority Levels: Low, Medium, High, Urgent with color coding
• Labels: Custom colored labels for categorization
• Assignee: Assign cards to team members
• Due Dates: Set and display due dates
• Timestamps: Automatic creation and update timestamps

Search and Filtering

• Real-time Search: Filter cards by title, description, or labels
• Preserved State: Search doesn't affect board state
• Highlight Matches: Visual indication of search results

Responsive Design

• Mobile Friendly: Works on all screen sizes
• Horizontal Scroll: Columns scroll horizontally on smaller screens
• Touch Support: Full touch device support

Types

interface KanbanCard {
  id: string
  title: string
  description?: string
  labels?: KanbanLabel[]
  priority?: "low" | "medium" | "high" | "urgent"
  assignee?: string
  dueDate?: string
  createdAt: string
  updatedAt: string
}

interface KanbanLabel {
  id: string
  name: string
  color: string
}

interface KanbanColumn {
  id: string
  title: string
  cards: KanbanCard[]
  limit?: number
}

interface KanbanBoard {
  id: string
  title: string
  columns: KanbanColumn[]
  labels: KanbanLabel[]
}

Props

KanbanBoard

Examples

Basic Kanban Board

Kanban with Labels

Project Management Board

Customization

Custom Priority Colors

// You can customize priority colors by extending the CSS
const priorityVariants = cva(
  "inline-flex items-center rounded-full border px-2 py-0.5 text-xs font-semibold",
  {
    variants: {
      priority: {
        low: "border-blue-200 bg-blue-50 text-blue-700",
        medium: "border-yellow-200 bg-yellow-50 text-yellow-700",
        high: "border-orange-200 bg-orange-50 text-orange-700",
        urgent: "border-red-200 bg-red-50 text-red-700",
      },
    },
  }
)

Custom Card Template

You can create custom card templates by extending the KanbanCardComponent:

function CustomKanbanCard({ card, onEdit, onDelete }) {
  return (
    <Card className="mb-3 group hover:shadow-md transition-shadow">
      {/* Your custom card layout */}
    </Card>
  )
}

Column Limits

Set limits on the number of cards per column:

const column = {
  id: "todo",
  title: "To Do",
  cards: [],
  limit: 5 // Maximum 5 cards
}

Integration Examples

With Local Storage

const useKanbanBoard = (boardId: string) => {
  const [board, setBoard] = useState(() => {
    const saved = localStorage.getItem(`kanban-${boardId}`)
    return saved ? JSON.parse(saved) : defaultBoard
  })

  const updateBoard = useCallback((newBoard: KanbanBoard) => {
    setBoard(newBoard)
    localStorage.setItem(`kanban-${boardId}`, JSON.stringify(newBoard))
  }, [boardId])

  return { board, updateBoard }
}

With API Integration

const useKanbanAPI = (boardId: string) => {
  const [board, setBoard] = useState<KanbanBoard | null>(null)

  const updateBoard = useCallback(async (newBoard: KanbanBoard) => {
    setBoard(newBoard)

    try {
      await fetch(`/api/boards/${boardId}`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(newBoard)
      })
    } catch (error) {
      console.error('Failed to save board:', error)
    }
  }, [boardId])

  return { board, updateBoard }
}

Real-time Collaboration

const useRealtimeKanban = (boardId: string) => {
  const [board, setBoard] = useState<KanbanBoard | null>(null)

  useEffect(() => {
    const socket = io()

    socket.emit('join-board', boardId)

    socket.on('board-updated', (updatedBoard: KanbanBoard) => {
      setBoard(updatedBoard)
    })

    return () => {
      socket.emit('leave-board', boardId)
      socket.disconnect()
    }
  }, [boardId])

  const updateBoard = useCallback((newBoard: KanbanBoard) => {
    setBoard(newBoard)
    socket.emit('update-board', { boardId, board: newBoard })
  }, [boardId])

  return { board, updateBoard }
}

Accessibility

The Kanban board component includes comprehensive accessibility features:

• Keyboard Navigation: Full keyboard support for drag and drop
• Screen Reader Support: Proper ARIA labels and descriptions
• Focus Management: Logical focus order and visible focus indicators
• Semantic HTML: Proper heading hierarchy and landmarks

Performance

• Optimized Rendering: Efficient re-rendering with React.memo
• Large Datasets: Handles boards with hundreds of cards
• Smooth Animations: Hardware-accelerated animations
• Memory Efficient: Proper cleanup and garbage collection

Troubleshooting

Cards Not Dragging

Make sure you have installed all required @dnd-kit dependencies:

npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities

Styling Issues

Ensure you have the required CSS classes in your Tailwind configuration and that all UI components are properly installed.

Performance Issues

For boards with many cards (100+), consider implementing virtualization or pagination for better performance.