Draggable Web Components

This project is a folk of Drag Drop Components, all credits goes to original authors.

Two vanilla Web Components draggable-container and draggable-element to simplify drag-drop interface coding. Suitable for all UI that users 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.

A CodePen demo

Table of Contents

• How to Use
  • HTML
    • Simple Example
  • NodeJS
• API
  • Events
    • draggable-element
    • draggable-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/draggable-web-components" type="module"></script>

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

• <draggable-element> A div-like block element to be dragged around and drop into containers.

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

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 application can be structured like this:

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

NodeJS

Install to your environment by:

npm install draggable-web-components

Use it on browser script:

// For the side-effects.
import 'draggable-web-components';

// Then use like simple HTML element, for example.
const container1 = document.createElement('draggable-container');
const container2 = document.createElement('draggable-container');
const child = document.createElement('draggable-element');
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.

draggable-element

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

draggable-container

• dnd:dragenter

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

• dnd:dragleave

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

• dnd:bounced

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

• dnd:dropped

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

Contribution

You are very welcome to modify and backport changes here.

Building the Library

This command will build the "dist/dragdrop-components.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 drag and drop effect verifications. To prevent regression, please verify that your changes can pass Playwright tests.

npm test

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.