swbullis / react-kanban

Yet another Kanban/Trello board like lib for React.

Yet another Kanban/Trello board like lib for React.

▶️ Demo

Usage

❓ Why?

• 👊 Reliable: 100% tested on CI; 100% coverage; 100% SemVer.
• 🎮 Having fun: Play with Hooks 🎣 and Styled Components 💅🏻.
• ♿️ Acessible: Keyboard and mobile friendly.

🛠 Install and usage

Since this project use Hooks and Styled Components, you have to install them:

• react>=16.8.0
• styled-components>=3

After, Install the lib on your project:

yarn add @lourenci/react-kanban

Import the lib and use it on your project:

import Board from '@lourenci/react-kanban'

const board = {
  lanes: [
    {
      id: 1,
      title: 'Backlog',
      cards: [
        {
          id: 1,
          title: 'Add card',
          description: 'Add capability to add a card in a lane'
        },
      ]
    }
    {
      id: 2,
      title: 'Doing',
      cards: [
        {
          id: 2,
          title: 'Drag-n-drop support',
          description: 'Move a card between the lanes'
        },
      ]
    }
  ]
}

<Board
  onCardDragEnd={() => {}}
  onLaneDragEnd={() => {}}
  renderCard={() => {}}
  renderLaneHeader={() => {}}
  allowAddLane
  onNewLane={() => {}}
>
  {board}
</Board>

🔥 API

⚙️ Props

Prop	Description
children (required)	The board to render
onCardDragEnd	Callback that will be called when the card move ends
onLaneDragEnd	Callback that will be called when the lane move ends
renderCard	A card to be rendered instead of the default card
renderLaneHeader	A lane header to be rendered instead of the default lane header
allowAddLane (required if onNewLane)	Allow a new lane be added by the user
onNewLane (required if allowAddLane)	Callback that will be called when a new lane is added

children

const board = {
  lanes: {
    id: ${unique-required-laneId},
    title: {$required-laneTitle},
    cards: {
      id: ${unique-required-cardId},
      title: ${required-cardTitle},
      description: ${required-cardDescription}
    }
  }
}

These cards props are required to the card's default template, except the id that is required for your template too. See renderCard.

These lanes props are required to the lane's default template, except the id that is required for your template too. See renderLaneHeader.

OnCardDragEnd

When the user moves a card, this callback will be called passing these parameters:

Arg	Description
board	The modified board
source	An object with the card source { laneId, index }
destination	An object with the card destination { laneId, index }

Source and destination

Prop	Description
laneId	In source: lane source id; In destination: lane destination id;
index	In source: card's index in lane source's array; In destination: card's index in lane destination's array;

OnLaneDragEnd

When the user moves a lane, this callback will be called passing these parameters:

Arg	Description
board	The modified board
source	An object with the lane source { index }
destination	An object with the lane destination { index }

Source and destination

Prop	Description
index	In source: lane index before the moving; In destination: lane index after the moving;

renderCard

Use this if you want to render your own card. You have to pass a function and return your card component. The function will receive these parameters:

Arg	Description
card	The card props
isDragging	Whether the card is being dragged

Ex.:

const board = {
  lanes: {
    id: ${unique-required-laneId},
    title: ${laneTitle},
    cards: {
      id: ${unique-required-cardId},
      dueDate: ${cardDueDate},
      content: ${cardContent}
    }
  }
}

<Board
  renderCard={({ dueDate, content }, isDragging) => (
    <YourCard dueDate={dueDate} content={content} isDragging={isDragging} />
  )}
>
{board}
</Board>

renderLaneHeader

Use this if you want to render your own lane header. You have to pass a function and return your lane header component. The function will receive this parameter:

Arg	Description
lane	The lane props

Ex.:

const board = {
  lanes: {
    id: ${unique-required-laneId},
    title: ${laneTitle},
    wip: ${wip},
    cards: {
      id: ${unique-required-cardId},
      title: ${required-cardTitle},
      description: ${required-cardDescription}
    }
  }
}

<Board
  renderLaneHeader={({ title, wip }) => (
    <YourLaneHeader title={title} wip={wip} />
  )}
>
{board}
</Board>

allowAddLane

Allow the user to add a new lane directly by the board. Use this together with onNewLane prop.

onNewLane

When the user adds a new lane, this callback will be called passing the lane title typed by the user.

You must return the new lane with its new id in this callback.

Ex.:

function onNewLane (newLane) {
  const newLane = { id: ${required-new-unique-laneId}, ...newLane }
  return newLane
}

<Board allowAddLane onNewLane={onNewLane}>{board}</Board>

🚴‍♀️ Roadmap

You can view the next features here. Feel welcome to help us with some PRs.

🤝 Contributing

PRs are welcome:

• Fork this project.
• Setup it:

  yarn
  yarn start
  

• Make your change.
• Add yourself to the contributors table:

  yarn contributors:add
  

• Open the PR.

✍️ Guidelines for contributing

• You need to test your change.
• Try to be clean on your change. CodeClimate will keep an eye on you.
• It has to pass on CI.

🤖 Contributors

Thanks goes to these wonderful people (emoji key):

Leandro Lourenci 💬 🐛 💻 📖 💡 ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!