@caldwell619/react-kanban
v0.0.11
Published
(fork of) Yet another Kanban/Trello board lib for React
Downloads
1,991
Readme
caldwell619 React Kanban
asseinfo's React Kanban
Forked from asseinfo's React Kanban
Shout out to all the contributors.
Why fork?
- The original library seems to not be maintained anymore. The last commit at this time is September of 2021.
- The original library did not include TypeScript types. It was written in JS without providing any types. This fork is natively written in TypeScript.
Road Map
Here is what's in the queue. If you want to see something, make an issue
Demo
Setup
yarn add @caldwell619/react-kanban
You will also need to install the peer dependencies on your own:
"peerDependencies": {
"react": ">=16",
"react-dom": ">=16",
"@hello-pangea/dnd": ">=16"
},
These are listed as peer dependencies because I do not want to pin specific versions as dependencies if you are already using them.
Usage
There are 2 main boards, Controlled
and Uncontrolled
.
This is a deviation from the original, as there was only one board exported. In the original, there's an in-library determination on whether or not the board is controlled. That is not quite how this works, as you will know upfront whether or not your board is controlled.
With that in mind, you can import each of the boards like this:
import { UncontrolledBoard, KanbanBoard } from '@caldwell619/react-kanban'
// import { ControlledBoard } from '@caldwell619/react-kanban'
import '@caldwell619/react-kanban/dist/styles.css' // import here for "builtin" styles
const board: KanbanBoard = {
columns: [
{
id: 1,
title: 'Backlog',
cards: [
{
id: 1,
title: 'Add card',
description: 'Add capability to add a card in a column'
},
]
},
{ ... }
]
}
<UncontrolledBoard initialBoard={board} />
Uncontrolled
With an uncontrolled board, you pass an initialBoard
prop, which will be the basis of the internal state. When a user moves something, that is all controlled by internal state.
Controlled
When you need a better control over the board, you should stick with the controlled board.
A controlled board means you need to deal with the board state yourself, you need to keep the state in your hands (component) and pass this state to the <Board />
, we just reflect this state.
If you go with the controlled one, you need to pass your board through the children
prop.
Board
If you really want to use the one unified board, you can still do so with Board
. Whether or not you provide initialBoard
or children
will determine which board you're using. If you provide both, UncontrolledBoard
takes priority.
See an example, here.
Helpers to work with the controlled board
Helpers are exposed to help with the management of your board state when using the ControlledBoard
. They are the same helpers used internally, so you can utilize them to assist in your controlled state.
import { ControlledBoard, moveCard, KanbanBoard, OnDragEndNotification, Card } from '@caldwell619/react-kanban'
const MyBoard = () => {
const [board, setBoard] = useState<KanbanBoard>(initialBoard)
const handleCardMove: OnDragEndNotification<Card> = (_card, source, destination) => {
setBoard((currentBoard) => {
return moveCard(currentBoard, source, destination)
})
}
return <ControlledBoard onCardDragEnd={handleCardMove}>{board}</ControlledBoard>
}
Board type
If you're using JS, this section doesn't have any effect on you.
The TypeScript type for the board is KanbanBoard
. It is a generic that accepts TCard extends Card
. Your data will undoubtedly need to be customized, so all the helpers and Board will accept your TCard
.
import { Card } from '@caldwell619/react-kanban'
interface CustomCard extends Card {
storyPoints: number
}
export const renderCard: UncontrolledBoardProps<CustomCard>['renderCard'] = (card) => {
// Can access with `card.storyPoints`
return <CardWithStoryPoints {...card} />
}
This behavior will applied throughout the render and confirm methods.
import { ControlledBoard, KanbanBoard } from '@caldwell619/react-kanban'
const CustomBoard = () => {
return (
<ControlledBoard<CustomCard>
renderCard={(card) => {
// `card.storyPoints`
return <CardWithStoryPoints {...card} />
}}
>
{board}
</ControlledBoard>
)
}
Props
For an exhaustive ( yet still WIP ) list of props you can pass, refer to this page.
Styling
You can either style all the board or import our style and override it with the styles you want. Ideally you would render the column instead of overriding CSS, however this may be helpful for you if your use case needs it.
| Class |
| ------------------------------------------- |
| react-kanban-board
|
| react-kanban-card
|
| react-kanban-card-skeleton
|
| react-kanban-card--dragging
|
| react-kanban-card__description
|
| react-kanban-card__title
|
| react-kanban-column
|
| react-kanban-card-adder-form
|
| react-kanban-card-adder-button
|
| react-kanban-card-adder-form__title
|
| react-kanban-card-adder-form__description
|
| react-kanban-card-adder-form__button
|
| react-kanban-column-header
|
| react-kanban-column-header__button
|
| react-kanban-column-adder-button
|
Contributing
PRs are welcome.
Steps
- File an issue, using the issue template.
- Fork this project.
- Clone your fork
- In your fork, run
yarn
to install deps - Begin work
- Add yourself to the contributors table, this is powered by all-contributors
yarn all-contributors add
yarn all-contributors generate
- Submit your PR across forks with the target base as
christopher-caldwell:master
.