Drag Drop Components

Web components to simplify drag-drop interface coding. Suitable for all UI that user drag and drop items from one container to another. Such as:

1. Kanban-like UI: Drag and drop an item from one board to another.
2. Board game: drag and drop pieces from one tile to another.

Live Examples: https://yookoala.github.io/dragdrop-components/examples/

Table of Contents

• How to Use
  • HTML
    • Simple Example
  • NodeJS
• API
  • Events
    • dragdrop-child
    • dragdrop-container
• Contribution
  • Building the Library
  • Development Mode
  • Playwright Test
  • Report Issue and Contribution
• License

How to Use

HTML

Just include the script from jsdelivr.net:

<script src="https://cdn.jsdelivr.net/npm/dragdrop-components" type="module"></script>

They you can use these 2 custom elements in your HTML:

• <dragdrop-child> A div-like block element to be dragged arround and drop into containers.

• <dragdrop-container> A div-like block element to receive <dragdrop-child>.

No framework. Couldn't have been easier.

Simple Example

There is very little pre-defined CSS style to stand in the way. A simple Kanban applicaiton can be structured like this:

<style>
main {
    display: flex;
}
dragdrop-container {
    border: 1px solid #ddd;
    min-height: 3em; /** prevent empty container from disappearing */
}
dragdrop-child {
    border: 1px solid #ddd;
    min-height: 3em; /** prevent empty child from disappearing */
}
</style>
<main>
    <section id="todo">
        <h2>Todo</h2>
        <dragdrop-container>
            <dragdrop-child data-task-id="my-task-1">
                <h3>My Task</h3>
            </dragdrop-child>
        </dragdrop-container>
    </section>
    <section id="doing">
        <h2>Doing</h2>
        <dragdrop-container></dragdrop-container>
    </section>
    <section id="done">
        <h2>Done</h2>
        <dragdrop-container></dragdrop-container>
    </section>
</main>
<script type="module">

document.getElementById("todo").addEventListener(
  "dnd:dropped",
  function (event) {
    const child = event.detail.child;
    const taskId = child.dataset.taskId;
    console.log('TODO: ', taskId);
  },
);

document.getElementById("doing").addEventListener(
  "dnd:dropped",
  function (event) {
    const child = event.detail.child;
    const taskId = child.dataset.taskId;
    console.log('DOING: ', taskId);
  },
);

document.getElementById("done").addEventListener(
  "dnd:dropped",
  function (event) {
    const child = event.detail.child;
    const taskId = child.dataset.taskId;
    console.log('DONE: ', taskId);
  },
);

</script>

More examples can be found in examples.

NodeJS

Install to your environment by:

npm install dragdrop-components

Use it on browser script:

// For the side-effects.
import 'dragdrop-components';

// Then use like simple HTML element, for example.
const container1 = document.createElement('dragdrop-container');
const container2 = document.createElement('dragdrop-container');
const child = document.createElement('dragdrop-child');
container1.appendChild(child);
document.documentElement.appendChild(container1);
document.documentElement.appendChild(container2);

API

Events

This library will fire a few custom events. The same event(s) will fire both with ordinary mouse drag-drop or touch drag-drop.

dragdrop-child

• dnd:dragstart
  • Fires when a it is started being dragged (both using mouse or touch).
  • Attributes
    • target (HTMLElement): the dragdrop-child element.
• dnd:dragend
  • Fires when a it is released from drag (both using mouse or touch).
  • Attributes
    • target (HTMLElement): the dragdrop-child element.

dragdrop-container

• dnd:dragleave

  • Fires when the dragdrop-child is dragging away from the container.
  • Attributes
    • target (HTMLElement): the dragdrop-container element.
    • detail (Object) with attribute:
      • child (HTMLElement): the dragdrop-child element being dragged.

• dnd:bounced

  • Fires when a previously dragged-away dragdrop-child is rejected from the destination container or otherwise being bounced back.
  • Attributes
    • target (HTMLElement): the dragdrop-container element.
    • detail (Object) with attribute:
      • child (HTMLElement): the dragdrop-child element being dragged.

• dnd:dropped

  • Fires when a dragdrop-child is dropped on this container.
  • Attributes
    • target (HTMLElement): the dragdrop-container element.
    • detail (Object) with attribute:
      • child (HTMLElement): the dragdrop-child element being dragged.

Contribution

You are very welcome to modify and backport changes here.

The best way is to work or extend on the examples along with proper test cases. All example depends on, and should always depend on, the built copy "dist/dragdrop-component.js" in this repository.

Building the Library

This command will build the "dist/dragdrop-component.js" file for distribution.

npm install
npm run build

Development Mode

To modify the library, you may run these to start the development mode. The source files will be monitored and built into the "dist" folder.

npm install
npm run dev

Playwright Test

This library uses Playwright test for the dragdrop effect verifications. To prevent regression, please verify that your changes can pass Playwright tests.

Playwright also provides very good support to VSCode's debugger. If you do not have a preferred editor, you're recommended to use VSCode along with the Playwright Test plugin.

Report Issue and Contribution

The library is hosted here. Please use our issue tracker to report issue, discuss or request new features. You're more than welcome to submit Pull Request for bug fixes and new features.

License

This software is licensed to the MIT License. A copy of the license can be found here.