Skip to main contentSkip to navigation

Kanban Board

PreviousNext

A comprehensive drag-and-drop Kanban board component with cards, columns, labels, priorities, and search functionality.

Loading...

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

PropTypeDefaultDescription
boardKanbanBoard-The board data structure
onUpdateBoard(board: KanbanBoard) => void-Callback when board state changes
classNamestring-Additional CSS classes

Examples

Basic Kanban Board

Component kanban-basic not found in registry.

Kanban with Labels

Component kanban-labels not found in registry.

Project Management Board

Component kanban-project not found in registry.

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.