JavaScript Reference ยท DOM: Events
Drag and drop events
Reference for the HTML drag and drop events: dragstart, dragover, drop and dragend, the dataTransfer object, draggable elements and dropping files.
The HTML drag and drop API lets users pick up an element, text or a file and drop it somewhere else. It is built from seven events. Three fire on the thing being dragged (the source): dragstart, drag and dragend. Four fire on elements the pointer passes over (the targets): dragenter, dragover, dragleave and drop.
To make an element draggable, set the draggable="true" attribute (images, links and selected text are draggable by default). The data travels in event.dataTransfer. The most common mistake is forgetting that a drop target must cancel dragover; if it does not, the browser never fires drop.
card.addEventListener("dragstart", (event) => { event.dataTransfer.setData("text/plain", card.id); }); zone.addEventListener("dragover", (event) => event.preventDefault()); // allow drop zone.addEventListener("drop", (event) => { event.preventDefault(); const id = event.dataTransfer.getData("text/plain"); zone.append(document.getElementById(id)); });
Try it
Syntax
element.addEventListener("dragstart", listener); element.addEventListener("dragover", listener); element.addEventListener("drop", listener);
The events
| Event | Fires on | When |
|---|---|---|
dragstart |
source | The user starts dragging. Set the data here. |
drag |
source | Repeatedly (every few hundred milliseconds) while dragging. |
dragend |
source | The drag finished, by dropping or cancelling (Escape). Check dataTransfer.dropEffect. |
dragenter |
target | The pointer enters an element while dragging. |
dragover |
target | Repeatedly while the pointer is over an element. Cancel it to allow a drop. |
dragleave |
target | The pointer leaves an element (this includes entering a child). |
drop |
target | The user released the item over a valid target. |
The dataTransfer object
| Name | Description |
|---|---|
setData(type, data) |
Stores a string under a MIME type such as text/plain. Call it in dragstart. |
getData(type) |
Reads that string back. It works only in drop (it returns an empty string during dragover). |
types |
The list of available types ("Files" when files are dragged). |
files |
A FileList of files dragged from the operating system. |
items |
A list of DataTransferItem objects, readable during dragover for their kind and type. |
effectAllowed |
Set in dragstart: none, copy, move, link, copyMove, all and so on. |
dropEffect |
Set in dragover: none, copy, move or link. It changes the cursor. |
setDragImage(element, x, y) |
Replaces the ghost image that follows the pointer. |
Usage notes
- Cancel
dragover(and usuallydragenter) on every element that should accept drops. Withoutevent.preventDefault()the cursor shows "not allowed" anddropnever fires. - Cancel
droptoo when handling files. Otherwise the browser may open the dropped file and navigate away from your page. dragleaveis noisy. It fires when the pointer moves onto a child element. Checkevent.relatedTarget(as in the first example) or use a counter to avoid a flickering highlight.- Data is protected during the drag.
getData()returns nothing indragover; only the types and, viaitems, the kinds are visible. Usetypesto decide whether to accept. - Nothing is moved for you. The API only reports the gesture. You must move or copy the elements yourself in
drop. - Touch screens. Drag and drop works poorly or not at all on many touch devices. For touch-friendly sorting, build it from pointer events, or use a library.
- Keyboard users. Dragging is mouse-centred. Offer an alternative such as "Move to..." buttons so the feature is accessible.
- Security. Dropped text and HTML are untrusted input. Insert them with
textContent, notinnerHTML.
Browser support
The drag and drop events work in all desktop browsers. Support on mobile browsers is partial and inconsistent, so test on real devices if you depend on it.