@kongfu/kanban

A modern, flexible kanban board SDK for React applications with drag-and-drop support.

Features

• 🎯 Drag & Drop - Smooth drag and drop powered by @dnd-kit
• 🎨 Customizable - Flexible theming and component customization
• 📱 Responsive - Works on desktop and mobile devices
• 🌍 i18n Ready - Built-in support for multiple languages
• ⚡ Performance - Optimized rendering with Zustand state management
• 🔍 Search & Filter - Built-in search and filtering capabilities
• 📊 Statistics - Real-time task statistics
• 🎭 Multiple Views - Board, list, calendar, and timeline views (coming soon)
• ✅ TypeScript - Full TypeScript support

Installation

npm install @kongfu/kanban
# or
yarn add @kongfu/kanban
# or
pnpm add @kongfu/kanban

Quick Start

import { Kanban } from '@kongfu/kanban';
import '@kongfu/kanban/styles.css';

const columns = [
  { id: 'todo', title: 'To Do', order: 0 },
  { id: 'in-progress', title: 'In Progress', order: 1 },
  { id: 'done', title: 'Done', order: 2 },
];

const tasks = [
  {
    id: '1',
    title: 'Create kanban board',
    status: 'todo',
    order: 0,
    createdAt: new Date(),
    updatedAt: new Date(),
  },
  {
    id: '2',
    title: 'Add drag and drop',
    status: 'in-progress',
    order: 0,
    priority: 'high',
    createdAt: new Date(),
    updatedAt: new Date(),
  },
];

function App() {
  return (
    <div style={{ height: '600px' }}>
      <Kanban
        columns={columns}
        tasks={tasks}
        onTaskCreate={(task) => console.log('Create task:', task)}
        onTaskUpdate={(id, updates) => console.log('Update task:', id, updates)}
        onTaskMove={(id, from, to, order) => console.log('Move task:', id, from, to, order)}
      />
    </div>
  );
}

Advanced Usage

Custom Card Rendering

<Kanban
  columns={columns}
  tasks={tasks}
  renderCard={(task) => (
    <div className="custom-card">
      <h3>{task.title}</h3>
      <p>{task.description}</p>
      <div className="custom-footer">
        {task.assignee?.name}
      </div>
    </div>
  )}
/>

With Filters

const filters = [
  {
    id: 'priority',
    label: 'Priority',
    type: 'select',
    field: 'priority',
    options: [
      { label: 'Low', value: 'low' },
      { label: 'Normal', value: 'normal' },
      { label: 'High', value: 'high' },
      { label: 'Urgent', value: 'urgent' },
    ],
  },
  {
    id: 'assignee',
    label: 'Assignee',
    type: 'multiselect',
    field: 'assignee',
    options: [
      { label: 'John Doe', value: 'john' },
      { label: 'Jane Smith', value: 'jane' },
    ],
  },
];

<Kanban
  columns={columns}
  tasks={tasks}
  filters={filters}
  showFilters={true}
  showSearch={true}
/>

Column Limits

const columnsWithLimits = [
  { id: 'todo', title: 'To Do', order: 0 },
  { id: 'in-progress', title: 'In Progress', order: 1, limit: 3 },
  { id: 'done', title: 'Done', order: 2 },
];

<Kanban
  columns={columnsWithLimits}
  tasks={tasks}
/>

Using the Store

import { useKanbanStore } from '@kongfu/kanban';

function KanbanControls() {
  const {
    tasks,
    selectedTasks,
    bulkUpdateTasks,
    bulkDeleteTasks,
    clearSelection,
  } = useKanbanStore();

  const handleBulkComplete = () => {
    bulkUpdateTasks(selectedTasks, { status: 'done' });
    clearSelection();
  };

  const handleBulkDelete = () => {
    if (confirm('Delete selected tasks?')) {
      bulkDeleteTasks(selectedTasks);
      clearSelection();
    }
  };

  return (
    <div>
      {selectedTasks.length > 0 && (
        <>
          <button onClick={handleBulkComplete}>
            Mark as Done ({selectedTasks.length})
          </button>
          <button onClick={handleBulkDelete}>
            Delete ({selectedTasks.length})
          </button>
        </>
      )}
    </div>
  );
}

Dark Mode

<Kanban
  columns={columns}
  tasks={tasks}
  mode="dark"
  theme={{
    primaryColor: '#3b82f6',
    backgroundColor: '#1f2937',
    cardBackgroundColor: '#374151',
    textColor: '#f9fafb',
    borderColor: '#4b5563',
  }}
/>

API Reference

Kanban Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | columns | KanbanColumn[] | [] | Column definitions | | tasks | KanbanTask[] | [] | Initial tasks | | mode | 'light' \| 'dark' | 'light' | Color mode | | readOnly | boolean | false | Disable editing | | showAddCard | boolean | true | Show add task button | | showColumnActions | boolean | true | Show column actions | | showCardActions | boolean | true | Show card actions | | showFilters | boolean | true | Show filter button | | showSearch | boolean | true | Show search input | | showStats | boolean | true | Show statistics | | cardHeight | 'compact' \| 'normal' \| 'expanded' | 'normal' | Card display size | | animation | boolean | true | Enable animations | | theme | KanbanTheme | - | Custom theme | | locale | 'en' \| 'zh-CN' | 'en' | UI language | | filters | FilterConfig[] | - | Filter configurations | | onTaskCreate | (task, columnId) => Promise<KanbanTask> | - | Task creation handler | | onTaskUpdate | (taskId, updates) => Promise<void> | - | Task update handler | | onTaskDelete | (taskId) => Promise<void> | - | Task deletion handler | | onTaskMove | (taskId, from, to, order) => Promise<void> | - | Task move handler | | onTaskClick | (task) => void | - | Task click handler | | renderCard | (task) => ReactNode | - | Custom card renderer | | renderColumn | (column, children) => ReactNode | - | Custom column renderer |

Task Interface

interface KanbanTask {
  id: string;
  title: string;
  description?: string;
  status: string;
  priority?: 'low' | 'normal' | 'high' | 'urgent';
  assignee?: {
    id: string;
    name: string;
    avatar?: string;
  };
  tags?: Array<{
    id: string;
    name: string;
    color: string;
  }>;
  dueDate?: Date;
  createdAt: Date;
  updatedAt: Date;
  order: number;
  subtasks?: Array<{
    id: string;
    title: string;
    completed: boolean;
  }>;
  attachments?: Array<{
    id: string;
    name: string;
    url: string;
    type: string;
    size: number;
  }>;
}

Column Interface

interface KanbanColumn {
  id: string;
  title: string;
  color?: string;
  icon?: ReactNode;
  limit?: number;
  collapsed?: boolean;
  order: number;
}

Styling

The component comes with default styles that you can import:

import '@kongfu/kanban/styles.css';

You can also customize the appearance using:

1. CSS Variables - Override default CSS variables
2. Theme Object - Pass a custom theme object
3. Custom Classes - Add your own CSS classes
4. Render Props - Complete control over rendering

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

License

MIT © Kongfu Team