DataTransfer.setDragImage()

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 <image> element but it can also be a <canvas> or any other image element. The method's x and y coordinates are offsets where the image should appear relative to the mouse pointer.

The coordinates specify the offset into the image where the mouse cursor should be. To center the image, for instance, use values that are half the width and height of the image.

This method must be called in the dragstart event handler.

Syntax

void dataTransfer.setDragImage(img, xOffset, yOffset);

Arguments

img
An image Element element to use for the drag feedback image.
xOffset
A long indicating the horizontal offset within the image.

 

yOffset
A long indicating the vertical offset within the image.

 

Return value

void
 

Example

This example shows how to use the setDragImage() method. Note the example refers to an image file named example.gif. If that file is present, it will be used as the drag image and if that file is not present, the browser will use its default drag image.

demo

<!DOCTYPE html>
<html lang=en>
<title>Example of DataTransfer.setDragImage()</title>
<meta name="viewport" content="width=device-width">
<style>
  div {
    margin: 0em;
    padding: 2em;
  }
  #source {
    color: blue;
    border: 1px solid black;
  }
  #target {
    border: 1px solid black;
  }
</style>
<script>
function dragstart_handler(ev) {
 console.log("dragStart");
 // Set the drag's format and data. Use the event target's id for the data 
 ev.dataTransfer.setData("text/plain", ev.target.id);
 // Create an image and use it for the drag image
 // NOTE: change "example.gif" to an existing image or the image will not
 // be created and the default drag image will be used.
 var img = new Image(); 
 img.src = 'example.gif'; 
 ev.dataTransfer.setDragImage(img, 10, 10);
}

function dragover_handler(ev) {
 console.log("dragOver");
 ev.preventDefault();
}

function drop_handler(ev) {
 console.log("Drop");
 ev.preventDefault();
 // Get the data, which is the id of the drop target
 var data = ev.dataTransfer.getData("text");
 ev.target.appendChild(document.getElementById(data));
}
</script>
<body>
<h1>Example of <code>DataTransfer.setDragImage()</code></h1>
 <div>
   <p id="source" ondragstart="dragstart_handler(event);" 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" ondrop="drop_handler(event);" ondragover="dragover_handler(event);">Drop Zone</div>
</body>
</html>

Specifications

Specification Status Comment
HTML Living Standard
The definition of 'setDragImage()' in that specification.
Living Standard  
HTML 5.1
The definition of 'setDragImage()' in that specification.
Recommendation Not included in W3C HTML5 Recommendation

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
Basic supportChrome Full support YesEdge Full support 18Firefox Full support YesIE ? Opera ? Safari ? WebView Android Full support YesChrome Android Full support YesEdge Mobile ? Firefox Android Full support YesOpera Android ? Safari iOS ? Samsung Internet Android ?

Legend

Full support  
Full support
Compatibility unknown  
Compatibility unknown

See also

Document Tags and Contributors

Last updated by: fscholz,