@yaredfall/react-kanban-dnd

Drag and drop for kanban boards with React

Motivation

This package was hugely inspired by react-beautiful-dnd. Although react-beautiful-dnd is amazing library, it's not perfect.

I decided to create @yaredfall/react-kanban-dnd because i wanted:

• better dragging experience - library should more accurately determine when to move things
• better DX - library should be simple and easy to use
• additional features
  • moving elements between lists with any level of nesting (with react-beautiful-dnd you can move elements only within same level)

Documentation

Contents

• <DnDContext />
• <Dropzone />
• <Draggable />
• Simple example

<DnDContext />

This component shares it's props between all children draggables. Wrap in <DnDContext /> the whole app, or just the part where you want to have dnd.

Props

interface DnDContextPublicProps {
    //required
    onDragEnd: DragEndHandler;
        
    //optional
    dndCoreSize?: number; // default: 24
    debug?: boolean; // default: false
}

type DragEndHandler = (result: DragState) => void;

interface DragState {
    source?: DragDestination,
    destination?: DragDestination;
}

type DragDestination = {
    dropzoneId: number | string;
    index: number;
};

• onDragEnd - this function will be called, when drag is over. It will pass the drag result as parameter. Use it to perform data mutation.
• dndCoreSize - size of draggable "core".
• debug - controls visibility of placeholder, draggable core and console logs.

Basic usage

import React from 'react';
import { DnDContext, DragEndHandler } from '@yaredfall/react-kanban-dnd';

type Props = {};

export default function Example({ }: Props) {

    const onDragEnd: DragEndHandler = (result) => {
        /*...*/
    };

    return (
        <DnDContext onDragEnd={onDragEnd}>
            <div>Your app with DnD</div>
        </DnDContext>
    );
}

<Dropzone />

This component declares its direct child as "dropzone" - a container for <Draggable />s

Props

interface DropzoneProps {
    dropzoneId: number | string;
    children: JSX.Element & { ref?: RefObject<HTMLElement> | null; };
};

• dropzoneId - identifier of dropzone. Must be unique. Note that id with number type will be converted to string.
• children - single element that represents container for draggables. Client box of this element will be used to decide if active draggable belongs to dropzone. This element must be capable of handling ref, i.e. legacy element like div, or forwardRef component.

Basic usage

import React from 'react';;
import { Dropzone } from '@yaredfall/react-kanban-dnd';

type Props = {};

export default function Example({ }: Props) {

    return (
        <Dropzone dropzoneId={"dropzone-1"}>
            <div>
                <h2>It's a droppable!</h2>
                {/* Draggables */}
            </div>
        </Dropzone>
    );
}

<Draggable />

This component declares it's direct child as "draggable" - an element that can be dragged.

Props

interface DraggableProps {
    draggableId: number | string;
    children: JSX.Element & { ref?: RefObject<HTMLElement> | null; };
};

• draggableId - identifier of draggable. Must be unique. Note that id with number type will be converted to string.
• children - single element that represents draggable element. Client box of this element will be used to decide position of active draggable within dropzone. This element must be capable of handling ref, i.e. legacy element like div, or forwardRef component.

Basic usage

import React from 'react';
import { Draggable } from '@yaredfall/react-kanban-dnd';

type Props = {};

export default function Example({ }: Props) {

    return (
        <Draggable draggableId={"draggable-1"}>
            <div>
                <h3>It's a draggable!</h3>
                {/* Draggable content */}
            </div>
        </Draggable>
    );
}

Simple example

Let's see how to use <DnDContext />, <Dropzone /> and <Draggable /> in conjunction.

import React from 'react';
import { DnDContext, DragEndHandler, Dropzone, Draggable } from '@yaredfall/react-kanban-dnd';

export function App() {

    const onDragEnd: DragEndHandler = (result) => {
        console.log(result);
    };

    return (
        <main className='p-8'>
            <DnDContext onDragEnd={onDragEnd} >
                <Dropzone dropzoneId={1}>
                    <ul>
                        <Draggable draggableId={1}>
                            <li>
                                <h3>Draggable 1</h3>
                                <p>Lorem ipsum dolor sit.</p>
                            </li>
                        </Draggable>
                        <Draggable draggableId={2}>
                            <li>
                                <h3>Draggable 2</h3>
                                <p>Lorem ipsum dolor sit amet consectetur.</p>
                            </li>
                        </Draggable>
                    </ul>
                </Dropzone>
                <Dropzone dropzoneId={2}>
                    <ul>
                        <Draggable draggableId={3}>
                            <li>
                                <h3>Draggable 3</h3>
                                <p>Lorem, ipsum dolor.</p>
                            </li>
                        </Draggable>
                    </ul>
                </Dropzone>
            </DnDContext>
        </main>
    );
}

Note that <Draggable />s within one <Dropzone /> must have same parent, which is direct children of the <Dropzone />.