Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/feross/drag-drop
HTML5 drag & drop for humans
https://github.com/feross/drag-drop
browser browserify drag-and-drop drag-drop html5 javascript
Last synced: 7 days ago
JSON representation
HTML5 drag & drop for humans
- Host: GitHub
- URL: https://github.com/feross/drag-drop
- Owner: feross
- License: mit
- Created: 2014-03-05T07:49:33.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2023-10-24T05:12:34.000Z (about 1 year ago)
- Last Synced: 2024-10-29T15:19:30.865Z (about 2 months ago)
- Topics: browser, browserify, drag-and-drop, drag-drop, html5, javascript
- Language: JavaScript
- Homepage:
- Size: 162 KB
- Stars: 489
- Watchers: 14
- Forks: 62
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# drag-drop [![ci][ci-image]][ci-url] [![npm][npm-image]][npm-url] [![downloads][downloads-image]][downloads-url] [![javascript style guide][standard-image]][standard-url]
[ci-image]: https://img.shields.io/github/workflow/status/feross/drag-drop/ci/master
[ci-url]: https://github.com/feross/drag-drop/actions
[npm-image]: https://img.shields.io/npm/v/drag-drop.svg
[npm-url]: https://npmjs.org/package/drag-drop
[downloads-image]: https://img.shields.io/npm/dm/drag-drop.svg
[downloads-url]: https://npmjs.org/package/drag-drop
[standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg
[standard-url]: https://standardjs.com
### HTML5 drag & drop for humans
In case you didn't know, the
[HTML5 drag and drop API](https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API)
is a
[total disaster](http://www.quirksmode.org/blog/archives/2009/09/the_html5_drag.html)!
This is an attempt to make the API usable by mere mortals.
### live demo
See [https://instant.io](https://instant.io).
### features
- simple API
- supports files and directories
- excellent browser support (Chrome, Firefox, Safari, Edge)
- adds a `drag` class to the drop target on hover, for easy styling!
- optionally, get the file(s) as a Buffer (see [buffer](https://github.com/feross/buffer))
### install
```
npm install drag-drop
```
This package works in the browser with [browserify](https://browserify.org). If you do not use a bundler, you can use the [standalone script](https://bundle.run/drag-drop) directly in a `` tag.
### usage
```js
const dragDrop = require('drag-drop')
dragDrop('#dropTarget', (files, pos, fileList, directories) => {
console.log('Here are the dropped files', files) // Array of File objects
console.log('Dropped at coordinates', pos.x, pos.y)
console.log('Here is the raw FileList object if you need it:', fileList)
console.log('Here is the list of directories:', directories)
})
```
Another handy thing this does is add a `drag` class to the drop target when the user
is dragging a file over the drop target. Useful for styling the drop target to make
it obvious that this is a drop target!
### complete example
```js
const dragDrop = require('drag-drop')
// You can pass in a DOM node or a selector string!
dragDrop('#dropTarget', (files, pos, fileList, directories) => {
console.log('Here are the dropped files', files)
console.log('Dropped at coordinates', pos.x, pos.y)
console.log('Here is the raw FileList object if you need it:', fileList)
console.log('Here is the list of directories:', directories)
// `files` is an Array!
files.forEach(file => {
console.log(file.name)
console.log(file.size)
console.log(file.type)
console.log(file.lastModifiedDate)
console.log(file.fullPath) // not real full path due to browser security restrictions
console.log(file.path) // in Electron, this contains the actual full path
// convert the file to a Buffer that we can use!
const reader = new FileReader()
reader.addEventListener('load', e => {
// e.target.result is an ArrayBuffer
const arr = new Uint8Array(e.target.result)
const buffer = new Buffer(arr)
// do something with the buffer!
})
reader.addEventListener('error', err => {
console.error('FileReader error' + err)
})
reader.readAsArrayBuffer(file)
})
})
```
### get files as buffers
If you prefer to access file data as Buffers, then just require drag-drop like this:
```js
const dragDrop = require('drag-drop/buffer')
dragDrop('#dropTarget', files => {
files.forEach(file => {
// file is actually a buffer!
console.log(file.readUInt32LE(0))
console.log(file.toJSON())
console.log(file.toString('hex')) // etc...
// but it still has all the normal file properties!
console.log(file.name)
console.log(file.size)
console.log(file.type)
console.log(file.lastModifiedDate)
})
})
```
### detect drag-and-dropped text
If the user highlights text and drags it, we capture that as a separate event.
Listen for it like this:
```js
const dragDrop = require('drag-drop')
dragDrop('#dropTarget', {
onDropText: (text, pos) => {
console.log('Here is the dropped text:', text)
console.log('Dropped at coordinates', pos.x, pos.y)
}
})
```
### detect `dragenter`, `dragover` and `dragleave` events
Instead of passing just an `ondrop` function as the second argument, instead pass an
object with all the events you want to listen for:
```js
const dragDrop = require('drag-drop')
dragDrop('#dropTarget', {
onDrop: (files, pos, fileList, directories) => {
console.log('Here are the dropped files', files)
console.log('Dropped at coordinates', pos.x, pos.y)
console.log('Here is the raw FileList object if you need it:', fileList)
console.log('Here is the list of directories:', directories)
},
onDropText: (text, pos) => {
console.log('Here is the dropped text:', text)
console.log('Dropped at coordinates', pos.x, pos.y)
},
onDragEnter: (event) => {},
onDragOver: (event) => {},
onDragLeave: (event) => {}
})
```
You can rely on the `onDragEnter` and `onDragLeave` events to fire only for the
drop target you specified. Events which bubble up from child nodes are ignored
so that you can expect a single `onDragEnter` and then a single `onDragLeave`
event to fire.
Furthermore, neither `onDragEnter`, `onDragLeave`, nor `onDragOver` will fire
for drags which cannot be handled by the registered drop listeners. For example,
if you only listen for `onDrop` (files) but not `onDropText` (text) and the user
is dragging text over the drop target, then none of the listed events will fire.
### remove listeners
To stop listening for drag & drop events and remove the event listeners, just use the
`cleanup` function returned by the `dragDrop` function.
```js
const dragDrop = require('drag-drop')
const cleanup = dragDrop('#dropTarget', files => {
// ...
})
// ... at some point in the future, stop listening for drag & drop events
cleanup()
```
### support pasting files from the clipboard
To support users pasting files from their clipboard, use the provided
`processItems()` function to process the `DataTransferItemList` from the
browser's native `'paste'` event.
```js
document.addEventListener('paste', event => {
dragDrop.processItems(event.clipboardData.items, (err, files) => {
// ...
})
})
```
### a note about `file://` urls
Don't run your app from `file://`. For security reasons, browsers do not allow you to
run your app from `file://`. In fact, many of the powerful storage APIs throw errors
if you run the app locally from `file://`.
Instead, start a local server and visit your site at `http://localhost:port`.
### license
MIT. Copyright (c) [Feross Aboukhadijeh](http://feross.org).