react-custom-kanban-board

KanbanBoard Component

A flexible and customizable Kanban board component for applications. The KanbanBoard component allows you to create interactive and draggable task cards organized into columns, making it ideal for project management and task tracking.

KanbanBoard Component

Here are some visual examples of the Kanban board component:

• 
• 

Features

• Drag and Drop Functionality: Move task cards between columns with ease
• Customizable Card Rendering: Tailor the appearance of task cards to fit your design
• Add, Edit, and Delete Tasks: Manage tasks directly from the Kanban board
• Support for Avatars: Display avatars on task cards for better team representation
• Custom Search Interface: Replace the default search with your own implementation
• Custom Filter Menus: Create advanced filter controls using your preferred UI library
• WIP Limits: Set limits on the number of cards allowed in each column
• Card Details with Expand/Collapse: Show or hide detailed information for each card
• Dynamic Filtering: Filter cards by various properties (priority, assignee, status)
• Search Functionality: Search for cards by title
• UI Library Integration: Seamlessly integrate with popular UI libraries like Chakra UI
• Responsive Design: Works on desktop and mobile devices
• Accessibility Features: Built with accessibility in mind

Installation

Install the KanbanBoard component via NPM:

npm install react-custom-kanban-board

or using yarn:

yarn add react-custom-kanban-board

Usage

Basic Example

Import and use the Kanban board in your React project:

import React from "react";
import KanbanBoard from "react-custom-kanban-board";

const columns = [
  { title: "To Do", key: "todo", color: "#BDBDCD" },
  { title: "In Progress", key: "in-progress", color: "#FDDDE3" },
  { title: "Done", key: "done", color: "#71C781" },
];

const initialCards = [
  {
    id: "1",
    title: "Task 1",
    status: "todo",
    avatarPath: "https://i.pravatar.cc/40?img=1",
  },
  {
    id: "2",
    title: "Task 2",
    status: "in-progress",
    avatarPath: "https://i.pravatar.cc/40?img=2",
  },
];

const App = () => {
  return (
    <div>
      <h1>My Kanban Board</h1>
      <KanbanBoard
        columns={columns}
        initialCards={initialCards}
        columnForAddCard="todo"
      />
    </div>
  );
};

export default App;

Advanced Example with Chakra UI Integration

Here's how to integrate the Kanban board with Chakra UI for enhanced UI components:

import React, { useState, useEffect, useRef } from "react";
import KanbanBoard from "react-custom-kanban-board";
import {
  ChakraProvider,
  InputGroup,
  Input,
  InputLeftElement,
  InputRightElement,
  IconButton,
  Box,
  Text,
  Menu,
  MenuButton,
  MenuList,
  MenuItem,
  Button,
  Divider,
  extendTheme,
} from "@chakra-ui/react";
import { SearchIcon, ChevronDownIcon, CloseIcon } from "@chakra-ui/icons";
import "./App.css";

// Create a theme
const theme = extendTheme({
  // Your theme customizations here (optional)
});

const App = () => {
  // Sample columns with WIP limits
  const columns = [
    { title: "To Do", key: "todo", color: "#B8C2CC" },
    { title: "In Progress", key: "in-progress", color: "#FFB1C1", limit: 3 }, // WIP limit
    { title: "Review", key: "review", color: "#FFD580" },
    { title: "Done", key: "done", color: "#91D18B" },
  ];

  // Sample cards data
  const initialCards = [
    {
      id: "1",
      title: "Create user authentication flow",
      status: "todo",
      avatarPath: "https://i.pravatar.cc/40?img=1",
      priority: "High",
      dueDate: "2023-06-30",
      tags: ["frontend", "auth"],
      description:
        "Implement user registration, login, and password reset flows.",
      assignee: "john",
    },
    // ... more cards
  ];

  // Filter configurations
  const filterConfigs = [
    {
      field: "priority",
      label: "Priority",
      options: [
        { value: "High", label: "High Priority" },
        { value: "Medium", label: "Medium Priority" },
        { value: "Low", label: "Low Priority" },
      ],
    },
    // ... more filter configs
  ];

  const [cards, setCards] = useState(initialCards);
  const [loading, setLoading] = useState(true);

  // Simulate loading data
  useEffect(() => {
    setTimeout(() => {
      setLoading(false);
    }, 1500);
  }, []);

  // Custom Search Input Component using Chakra UI
  const CustomSearchInput = ({ searchTerm, setSearchTerm }) => {
    const inputRef = useRef(null);

    return (
      <InputGroup size="md" maxW="400px">
        <InputLeftElement pointerEvents="none">
          <SearchIcon color="gray.400" />
        </InputLeftElement>
        <Input
          ref={inputRef}
          value={searchTerm}
          onChange={(e) => setSearchTerm(e.target.value)}
          placeholder="Find tasks..."
          borderRadius="full"
          bg="white"
          borderColor="gray.300"
        />
        {searchTerm && (
          <InputRightElement>
            <IconButton
              size="sm"
              variant="ghost"
              icon={<CloseIcon w={3} h={3} />}
              onClick={() => {
                setSearchTerm("");
                inputRef.current?.focus();
              }}
              aria-label="Clear search"
            />
          </InputRightElement>
        )}
      </InputGroup>
    );
  };

  // Custom Filter Menu Component using Chakra UI
  const CustomFilterMenu = ({ config, selectedValue, onChange }) => {
    const selectedOption = config.options.find(
      (opt) => opt.value === selectedValue
    );
    const displayValue = selectedOption
      ? selectedOption.label
      : `All ${config.label}s`;

    return (
      <Box mx={2}>
        <Text fontSize="xs" color="gray.500" mb={1}>
          {config.label}
        </Text>
        <Menu closeOnSelect={true}>
          <MenuButton
            as={Button}
            rightIcon={<ChevronDownIcon />}
            size="sm"
            variant="outline"
            w="160px"
          >
            {displayValue}
          </MenuButton>
          <MenuList zIndex={100}>
            <MenuItem
              onClick={() => onChange(config.field, null)}
              fontWeight={!selectedValue ? "bold" : "normal"}
            >
              All {config.label}s
            </MenuItem>
            <Divider />
            {config.options.map((option) => (
              <MenuItem
                key={option.value}
                onClick={() => onChange(config.field, option.value)}
                fontWeight={selectedValue === option.value ? "bold" : "normal"}
              >
                {option.label}
              </MenuItem>
            ))}
          </MenuList>
        </Menu>
      </Box>
    );
  };

  // Wrapper functions to match the expected function signature
  const customSearchWrapper = (searchTerm, setSearchTerm) => {
    return (
      <CustomSearchInput
        searchTerm={searchTerm}
        setSearchTerm={setSearchTerm}
      />
    );
  };

  const customFilterWrapper = (config, selectedValue, onChange) => {
    return (
      <CustomFilterMenu
        config={config}
        selectedValue={selectedValue}
        onChange={onChange}
      />
    );
  };

  return (
    <ChakraProvider theme={theme}>
      <div className="app-container">
        <header className="app-header">
          <h1>Project Task Board</h1>
        </header>

        <main className="board-container">
          <KanbanBoard
            columns={columns}
            initialCards={cards}
            columnForAddCard="todo"
            isLoading={loading}
            emptyColumnMessage="No tasks yet"
            enableSearch={true}
            enableFiltering={true}
            filterConfigs={filterConfigs}
            renderSearchInput={customSearchWrapper}
            renderFilterMenu={customFilterWrapper}
          />
        </main>
      </div>
    </ChakraProvider>
  );
};

export default App;

Props

KanbanBoard Component Props

Prop	Type	Default	Description
columns	Column[]	[]	Array of columns to display. Each object should include title, key, and color.
initialCards	Card[]	[]	Array of cards to display initially. Each object should include id, title, status, and optionally avatarPath.
columnForAddCard	string	-	Key of the column where new cards will be added.
onCardMove	(cardId: string, newStatus: string) => void	-	Callback function when a card is moved.
onCardEdit	(cardId: string, newTitle: string) => void	-	Callback function when a card is edited.
onCardDelete	(cardId: string) => void	-	Callback function when a card is deleted.
onTaskAddedCallback	(title: string) => void	-	Callback function when a new task is added.
renderCard	(card: Card, handleDragStart: (e: React.DragEvent<HTMLDivElement>, card: Card) => void, isExpanded?: boolean, toggleExpand?: (id: string) => void) => ReactNode	-	Custom function to render cards.
renderAvatar	(avatarPath?: string) => ReactNode	-	Custom function to render avatars.
renderAddCard	(column: string, setCards: React.Dispatch<React.SetStateAction<Card[]>>) => ReactNode	-	Custom function to render the add card button.
isLoading	boolean	false	Shows loading spinner when true.
loadingComponent	ReactNode	-	Custom loading component.
emptyColumnMessage	string	"No cards yet"	Message to display when a column is empty.
enableSearch	boolean	false	Enable search functionality.
enableFiltering	boolean	false	Enable filtering functionality.
filterConfigs	FilterConfig[]	[]	Configuration for filters.
onFilterChange	(filters: Record<string, string | null>) => void	-	Callback when filters change.
renderSearchInput	(searchTerm: string, setSearchTerm: (term: string) => void) => ReactNode	-	Custom function to render search input.
renderFilterMenu	(config: FilterConfig, value: string | null, handleFilterChange: (field: string, value: string | null) => void) => ReactNode	-	Custom function to render filter menu.

Column Interface

Property	Type	Description
title	string	Title of the column.
key	string	Unique key for the column.
color	string	Background color for the column.
limit	number	Optional WIP limit for the column.

Card Interface

Property	Type	Description
id	string	Unique identifier for the card.
title	string	Title of the card.
status	string	Status of the card, corresponds to column key.
avatarPath	string	URL to the avatar image.
priority	string	Priority level (e.g., "High", "Medium", "Low").
dueDate	string	Due date for the card.
tags	string[]	Array of tags for the card.
description	string	Detailed description of the card.
assignee	string	Person assigned to the card.
[key: string]	any	Any additional custom properties you need.

FilterConfig Interface

Property	Type	Description
field	string	Field to filter by (e.g., "priority", "assignee").
label	string	Display label for the filter.
options	FilterOption[]	Array of available filter options.

FilterOption Interface

Property	Type	Description
value	string	Value of the filter option.
label	string	Display label for the filter option.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

Contact

For any questions or issues, please contact HamdyIIbarhim.