https://github.com/yookoala/dragdrop-components
Web Components for Simple Drag and Drop Operations
https://github.com/yookoala/dragdrop-components
drag-and-drop drag-drop webcomponent
Last synced: 2 months ago
JSON representation
Web Components for Simple Drag and Drop Operations
- Host: GitHub
- URL: https://github.com/yookoala/dragdrop-components
- Owner: yookoala
- License: mit
- Created: 2023-10-26T10:31:42.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-09-12T03:20:24.000Z (9 months ago)
- Last Synced: 2025-04-12T02:05:53.998Z (2 months ago)
- Topics: drag-and-drop, drag-drop, webcomponent
- Language: TypeScript
- Homepage:
- Size: 116 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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/][examples-url]
[![CI test][ci-badge]][ci-url] [![NPM][npm-badge]][npm-url] [![Downloads][npm-download-badge]][npm-url]
[examples-url]: https://yookoala.github.io/dragdrop-components/examples/
[ci-url]: https://github.com/yookoala/dragdrop-components/actions?query=branch%3Amain+workflow%3APlaywright
[ci-badge]: https://github.com/yookoala/dragdrop-components/actions/workflows/playwright.yml/badge.svg?branch=main
[npm-url]: https://www.npmjs.com/package/dragdrop-components
[npm-badge]: https://img.shields.io/npm/v/dragdrop-components
[npm-download-badge]: https://img.shields.io/npm/dm/dragdrop-components
---
**Table of Contents**
- [How to Use](#how-to-use)
- [HTML](#html)
- [Simple Example](#simple-example)
- [NodeJS](#nodejs)
- [API](#api)
- [Events](#events)
- [dragdrop-child](#dragdrop-child)
- [dragdrop-container](#dragdrop-container)
- [Contribution](#contribution)
- [Building the Library](#building-the-library)
- [Development Mode](#development-mode)
- [Playwright Test](#playwright-test)
- [Report Issue and Contribution](#report-issue-and-contribution)
- [License](#license)
---
## How to Use
### HTML
Just include the script from jsdelivr.net:
```html
```
They you can use these 2 custom elements in your HTML:
* ``
A div-like block element to be dragged arround and drop into containers.
* ``
A div-like block element to receive ``.
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:
```html
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 */
}
Todo
My Task
Doing
Done
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);
},
);
```
More examples can be found in [examples](examples).
### NodeJS
Install to your environment by:
```shell
npm install dragdrop-components
```
Use it on browser script:
```js
// 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:dragenter`
* Fires when the dragdrop-child is dragging into the container.
* Attributes
- target (HTMLElement): the dragdrop-container element.
- detail (Object)
with attribute:
- child (HTMLElement): the dragdrop-child element being dragged.
* `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](examples) along with proper
[test cases](tests). 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](https://playwright.dev/docs/getting-started-vscode)
along with the [Playwright Test](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright)
plugin.
### Report Issue and Contribution
The library is hosted [here](https://github.com/yookoala/dragdrop-components). Please
use our [issue tracker](https://github.com/yookoala/dragdrop-components/issues) to
report issue, discuss or request new features. You're more than welcome to submit
[Pull Request](https://github.com/yookoala/dragdrop-components/pulls) for bug fixes
and new features.
## License
This software is licensed to the MIT License. A copy of the license can be found [here](LICENSE).