DataTransfer: setDragImage() method

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since October 2018.

When a drag occurs, a translucent image is generated from the drag target (the element the dragstart event is fired at), and follows the mouse pointer during the drag. This image is created automatically, so you do not need to create it yourself. However, if a custom image is desired, the DataTransfer.setDragImage() method can be used to set the custom image to be used. The image will typically be an <img> element but it can also be a <canvas> or any other visible element.

The method's x and y coordinates define how the image should appear relative to the mouse pointer. These coordinates define the offset into the image where the mouse cursor should be. For instance, to display the image so that the pointer is at its center, use values that are half the width and height of the image.

This method must be called in the dragstart event handler.

Syntax

js
setDragImage(imgElement, xOffset, yOffset)

Parameters

imgElement

An image Element element to use for the drag feedback image.

If Element is an img element, then set the drag data store bitmap to the element's image (at its intrinsic size); otherwise, set the drag data store bitmap to an image generated from the given element (the exact mechanism for doing so is not currently specified).

Note: If the Element is an existing HTMLElement it needs to be visible in the viewport in order to be shown as a drag feedback image. Alternatively, you can create a new DOM element that might be off-screen specifically for this purpose.

xOffset

A long indicating the horizontal offset within the image.

yOffset

A long indicating the vertical offset within the image.

Return value

None (undefined).

Examples

Using setDragImage()

html
<div>
  <p id="source" draggable="true">
    Select this element, drag it to the Drop Zone and then release the selection
    to move the element.
  </p>
</div>
<div id="target">Drop Zone</div>
css
div {
  margin: 0em;
  padding: 2em;
}
#source {
  color: blue;
  border: 1px solid black;
}
#target {
  border: 1px solid black;
}
js
const source = document.getElementById("source");
const target = document.getElementById("target");

// Create an image and use it for the drag image
// Use the image URL that you desire
const img = new Image();
img.src = "/shared-assets/images/examples/favicon32.png";

source.addEventListener("dragstart", (ev) => {
  // Set the drag's format and data. Use the event target's id for the data
  ev.dataTransfer.setData("text/plain", ev.target.id);
  ev.dataTransfer.setDragImage(img, 10, 10);
});

target.addEventListener("dragover", (ev) => {
  ev.preventDefault();
});

target.addEventListener("drop", (ev) => {
  ev.preventDefault();
  // Get the data, which is the id of the drop target
  const data = ev.dataTransfer.getData("text");
  ev.target.appendChild(document.getElementById(data));
});

Specifications

Specification
HTML
# dom-datatransfer-setdragimage-dev

Browser compatibility

desktop mobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
setDragImage
Chrome – Full support
Chrome 3 (Release date: 2009-09-15)
footnote Full support
Edge – Full support
Edge 18 (Release date: 2018-10-02)
footnote Full support
Firefox – Full support
Firefox 3.5 (Release date: 2009-06-30)
footnote Full support
Opera – Full support
Opera 12.1 (Release date: 2012-11-20)
footnote Full support
Safari – Full support
Safari 4 (Release date: 2009-06-08)
footnote Full support
Chrome Android – Full support
Chrome Android 18 (Release date: 2012-06-27)
footnote Full support
Firefox for Android – Full support
Firefox for Android 4 (Release date: 2011-03-29)
footnote Full support
Opera Android – Full support
Opera Android 12.1 (Release date: 2012-10-09)
footnote Full support
Safari on iOS – Full support
Safari on iOS 3.2 (Release date: 2010-04-03)
footnote Full support
Samsung Internet – Full support
Samsung Internet 1 (Release date: 2013-04-27)
footnote Full support
WebView Android – Full support
WebView Android 4.4 (Release date: 2013-12-09)
footnote Full support
WebView on iOS – Full support
WebView on iOS 3.2 (Release date: 2010-04-03)
footnote Full support

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

See also