Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
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

Move cards between two lists
Drop files from your computer

Syntax

JavaScript
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 usually dragenter) on every element that should accept drops. Without event.preventDefault() the cursor shows "not allowed" and drop never fires.
  • Cancel drop too when handling files. Otherwise the browser may open the dropped file and navigate away from your page.
  • dragleave is noisy. It fires when the pointer moves onto a child element. Check event.relatedTarget (as in the first example) or use a counter to avoid a flickering highlight.
  • Data is protected during the drag. getData() returns nothing in dragover; only the types and, via items, the kinds are visible. Use types to 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, not innerHTML.

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.