W3cubDocs

/DOM

HTML Drag and Drop API: Drag operations

The following describes the steps that occur during a drag and drop operation.

The drag operations described in this document use the DataTransfer interface. This document does not use the DataTransferItem interface nor the DataTransferItemList interface.

The Draggable Attribute

Within a web page, there are certain cases where a default drag behavior is used. These include text selections, images, and links. When an image or link is dragged, the URL of the image or link is set as the drag data, and a drag begins. For other elements, they must be part of a selection for a default drag to occur. To see this in effect, select an area of a webpage, and then click and hold the mouse and drag the selection. An OS-specific rendering of the selection will appear and follow the mouse pointer as the drag occurs. However, this behavior is only the default drag behavior, if no listeners adjust the data to be dragged.

In HTML, apart from the default behavior for images, links, and selections, no other elements are draggable by default. In XUL, all elements are draggable.

To make another HTML element draggable, three things must be done:

Set the draggable attribute to true on the element that you wish to make draggable.
Add a listener for the dragstart event
Set the drag data within the listener defined above.

Here is an example which allows a section of content to be dragged.

<div draggable="true" ondragstart="event.dataTransfer.setData('text/plain', 'This text may be dragged')">
  This text <strong>may</strong> be dragged.
</div>

The draggable attribute is set to true, so this element becomes draggable. If this attribute were omitted or set to false, the element would not be dragged, and instead, the text would be selected. The draggable attribute may be used on any element, including images and links. However, for these last two, the default value is true, so you would only use the draggable attribute with a value of false to disable dragging of these elements.

Note that when an element is made draggable, text or other elements within it can no longer be selected in the normal way by clicking and dragging with the mouse. Instead, the user must hold down the alt key to select text with the mouse, or use the keyboard.

For XUL elements, you do not need to use the draggable attribute, as all XUL elements are draggable.

<button label="Drag Me" ondragstart="event.dataTransfer.setData('text/plain', 'Drag Me Button');">

Starting a Drag Operation

In this example, a listener is added for the dragstart event by using the ondragstart attribute.

<div draggable="true" ondragstart="event.dataTransfer.setData('text/plain', 'This text may be dragged')">
  This text <strong>may</strong> be dragged.
</div>

When a user begins to drag, the dragstart event is fired. In this example the dragstart listener is added to the draggable element itself; however, you could listen to a higher ancestor as drag events bubble up as most other events do. Within the dragstart event, you can specify the drag data, the feedback image, and the drag effects, all of which are described below. However, only the drag data is required; the default image and drag effects are suitable in many situations.

Drag Data

All drag events have a property called dataTransfer which holds the drag data (dataTransfer is a DataTransfer object).

When a drag occurs, data must be associated with the drag which identifies what is being dragged. For example, when dragging the selected text within a textbox, the data associated with the drag data item is the text itself. Similarly, when dragging a link on a web page, the drag data item is the URL of the link.

The drag data contains two pieces of information, the type (or format) of the data, and the data value. The format is a type string (such as text/plain for text data), and the value is a string of text. When the drag begins, you add data by providing a type and the data. During the drag, in an event listener for the dragenter and dragover events, you use the data types of the data being dragged to check whether a drop is allowed. For instance, a drop target that accepts links would check for the link type text/uri-list. During a drop event, a listener would retrieve the data being dragged and insert it at the drop location.

The drag data's types property returns a list of MIME-type like DOMStrings, such as text/plain or image/jpeg. You can also create your own types. The most commonly used types are listed in the article Recommended Drag Types.

A drag may include data items of several different types. This allows data to be provided in more specific types, often custom types, yet still provide fallback data for drop targets that do not support more specific types. It is usually the case that the least specific type will be normal text data using the type text/plain. This data will be a simple textual representation.

To set a drag data item within the dataTransfer, use the setData() method. It takes two arguments, the type of data and the data value. For example:

event.dataTransfer.setData("text/plain", "Text to drag");

In this case, the data value is "Text to drag" and is of the format text/plain.

You can provide data in multiple formats. To do this, call the setData() method multiple times with different formats. You should call it with formats in order from most specific to least specific.

var dt = event.dataTransfer;
dt.setData("application/x-bookmark", bookmarkString);
dt.setData("text/uri-list", "http://www.mozilla.org");
dt.setData("text/plain", "http://www.mozilla.org");

Here, data is added in three different types. The first type 'application/x-bookmark' is a custom type. Other applications won't support this type, but you can use a custom type for drags between areas of the same site or application. By providing data in other types as well, we can also support drags to other applications in less specific forms. The 'application/x-bookmark' type can provide data with more details for use within the application whereas the other types can include just a single URL or text version.

Note that both the text/uri-list and text/plain contain the same data in this example. This will often be true, but doesn't need to be the case.

If you attempt to add data twice with the same format, the new data will replace the old data, but in the same position within the list of types as the old data.

You can clear the data using the clearData() method, which takes one argument, the type of the data to remove.

event.dataTransfer.clearData("text/uri-list");

The type argument to the clearData() method is optional. If the type is not specified, the data associated with all types is removed. If the drag contains no drag data items, or all of the items have been subsequently cleared, then no drag will occur.

Setting the drag feedback image

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, you can use setDragImage() to specify a custom drag feedback image.

event.dataTransfer.setDragImage(image, xOffset, yOffset);

Three arguments are necessary. The first is a reference to an image. This reference will typically be to an image element, but it can also be to a canvas or any other element. The feedback image will simply be generated from whatever the image looks like on screen, although for images, they will be drawn at their original size. The second and third arguments to the setDragImage() method are offsets where the image should appear relative to the mouse pointer.

It is also possible to use images and canvases that are not in a document. This technique is useful when drawing custom drag images using the canvas element, as in the following example:

function dragWithCustomImage(event) {
  var canvas = document.createElementNS("http://www.w3.org/1999/xhtml","canvas");
  canvas.width = canvas.height = 50;

  var ctx = canvas.getContext("2d");
  ctx.lineWidth = 4;
  ctx.moveTo(0, 0);
  ctx.lineTo(50, 50);
  ctx.moveTo(0, 50);
  ctx.lineTo(50, 0);
  ctx.stroke();

  var dt = event.dataTransfer;
  dt.setData('text/plain', 'Data to Drag');
  dt.setDragImage(canvas, 25, 25);
}

In this example, we make one canvas the drag image. As the canvas is 50 pixels wide and 50 pixels high, we use offsets of half of this (25 and 25) so that the image appears centered on the mouse pointer.

Using XUL panels as drag images

Requires Gecko 9.0(Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6)

For Gecko developers (whether you're doing an add-on or Mozilla application code), Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6) adds support for using a XUL panel element as a drag feedback image. Simply pass your panel element to the setDragImage() method.

Consider this XUL panel:

<panel id="panel" style="opacity: 0.6">
  <description id="pb">Drag Me</description>
</panel>

<vbox align="start" style="border: 1px solid black;" ondragstart="startDrag(event)">
  <description>Drag Me</description>
</vbox>

When the user begins a drag by clicking and dragging from the vbox above, the startDrag() function below is called.

function startDrag(event) {
  event.dataTransfer.setData("text/plain", "<strong>Body</strong>");
  event.dataTransfer.setDragImage(document.getElementById("panel"), 20, 20);
}

This uses the panel as the drag image, with the string "<strong>Body</strong>" as its data, in HTML format. Dropping the panel into a text editor results in the text "Body" being inserted into the text at the drop location.

Drag Effects

When dragging, there are several operations that may be performed. The copy operation is used to indicate that the data being dragged will be copied from its present location to the drop location. The move operation is used to indicate that the data being dragged will be moved, and the link operation is used to indicate that some form of relationship or connection will be created between the source and drop locations.

You can specify which of the three operations are allowed for a drag source by setting the effectAllowed property within a dragstart event listener.

event.dataTransfer.effectAllowed = "copy";

In this example, only a copy is allowed. You can combine the values in various ways:

none: no operation is permitted
copy: copy only
move: move only
link: link only
copyMove: copy or move only
copyLink: copy or link only
linkMove: link or move only
all: copy, move, or link

Note that these values must be used exactly as listed above. For example, setting the effectAllowed property to copyMove allows a copy or move operation but prevents the user from performing a link operation. If you don't change the effectAllowed property, then any operation is allowed, just like with the 'all' value. So you don't need to adjust this property unless you want to exclude specific types.

During a drag operation, a listener for the dragenter or dragover events can check the effectAllowed property to see which operations are permitted. A related property, dropEffect, should be set within one of these events to specify which single operation should be performed. Valid values for dropEffect are none, copy, move, or link. The combination values are not used for this property.

With the dragenter and dragover event, the dropEffect property is initialized to the effect that the user is requesting. The user can modify the desired effect by pressing modifier keys. Although the exact keys used vary by platform, typically the Shift and Control keys would be used to switch between copying, moving, and linking. The mouse pointer will change to indicate which operation is desired; for instance, for a copy, the cursor might appear with a plus sign next to it.

You can modify the dropEffect property during the dragenter or dragover events, if for example, a particular drop target only supports certain operations. You can modify the dropEffect property to override the user effect, and enforce a specific drop operation to occur. Note that this effect must be one listed within the effectAllowed property. Otherwise, it will be set to an alternate value that is allowed.

event.dataTransfer.dropEffect = "copy";

In this example, copy is the effect that is performed.

You can use the value none to indicate that no drop is allowed at this location, although it is preferred not to cancel the event in this case.

Within the drop and dragend events, you can check the dropEffect property to determine which effect was ultimately chosen. If the chosen effect were "move", then the original data should be removed from the source of the drag within the dragend event.

Specifying Drop Targets

A listener for the dragenter and dragover events are used to indicate valid drop targets, that is, places where dragged items may be dropped. Most areas of a web page or application are not valid places to drop data. Thus, the default handling of these events is not to allow a drop.

If you want to allow a drop, you must prevent the default handling by cancelling the event. You can do this either by returning false from an attribute-defined event listener, or by calling the event's preventDefault() method. The latter may be more feasible in a function defined in a separate script.

<div ondragover="return false">
<div ondragover="event.preventDefault()">

Calling the preventDefault() method during both a dragenter and dragover event will indicate that a drop is allowed at that location. However, you will commonly wish to call the preventDefault() method only in certain situations, for example, only if a link is being dragged. To do this, call a function which checks a condition and only cancels the event when the condition is met. If the condition is not met, don't cancel the event, and a drop will not occur there if the user releases the mouse button.

It is most common to accept or reject a drop based on the type of drag data in the data transfer -- for instance, allowing images or links or both. To do this, you can check the types property of the event's dataTransfer (property). The types property returns an array of the string types that were added when the drag began, in the order from most significant to least significant.

function contains(list, value) {
    for( var i = 0; i < list.length; ++i ) {
        if(list[i] === value) return true;
    }
    return false;
}

function doDragOver(event) {
  var isLink = contains( event.dataTransfer.types, "text/uri-list");
  if (isLink) {
    event.preventDefault();
  }
}

In this example, we use the contains method to check if the type text/uri-list is present in the list of types. If it is, we will cancel the event so that a drop may be allowed. If the drag data does not contain a link, the event will not be cancelled, and a drop cannot occur at that location.

You may also wish to set either the effectAllowed, dropEffect property, or both at the same time, if you wish to be more specific about the type of operation that will performed. Naturally, changing either property will have no effect if you do not cancel the event as well.

Updates to DataTransfer.types

Note that the latest spec now dictates that DataTransfer.types should return a frozen array of DOMStrings rather than a DOMStringList (this is supported in Firefox 52 and above).

As a result, the contains method no longer works on the property; the includes method should be used instead to check if a specific type of data is provided, using code like the following:

if ([...event.dataTransfer.types].includes('text/html')) {
  // Do something
}

You could always use some feature detection to determine which method is supported on types, and run code as appropriate.

Drop Feedback

There are several ways in which you can indicate to the user that a drop is allowed at a certain location. The mouse pointer will update as necessary depending on the value of the dropEffect property. Although the exact appearance depends on the user's platform, typically a plus sign icon will appear for a 'copy' for example, and a 'cannot drop here' icon will appear when a drop is not allowed. This mouse pointer feedback is sufficient in many cases.

However, you can also update the user interface with an insertion point or highlight as needed. For simple highlighting, you can use the -moz-drag-over CSS pseudoclass on a drop target.

.droparea:-moz-drag-over {
  border: 1px solid black;
}

In this example, the element with the class droparea will receive a 1 pixel black border while it is a valid drop target, that is, if the preventDefault() method was called during the dragenter event. Note that you must cancel the dragenter event for this pseudoclass to apply, as this state is not checked for the dragover event.

For more complex visual effects, you can also perform other operations during the dragenter event, for example, by inserting an element at the location where the drop will occur. For example, this might be an insertion marker or an element that represents the dragged element in its new location. To do this, you could create an image or separator element, for example, and simply insert it into the document during the dragenter event.

The dragover event will fire at the element the mouse is pointing at. Naturally, you may need to move the insertion marker around a dragover event as well. You can use the event's clientX and clientY properties as with other mouse events to determine the location of the mouse pointer.

Finally, the dragleave event will fire at an element when the drag leaves the element. This is the time when you should remove any insertion markers or highlighting. You do not need to cancel this event. Any highlighting or other visual effects specified using the -moz-drag-over pseudoclass will be removed automatically. The dragleave event will always fire, even if the drag is cancelled, so you can always ensure that any insertion point cleanup can be done during this event.

Performing a Drop

When the user releases the mouse, the drag and drop operation ends. If the mouse was released over an element that is a valid drop target, that is, one that cancelled the last dragenter or dragover event, and then the drop will be successful, and a drop event will fire at the target. Otherwise, the drag operation is cancelled, and no drop event is fired.

During the drop event, you should retrieve that data that was dropped from the event and insert it at the drop location. You can use the dropEffect property to determine which drag operation was desired.

As with all drag-related events, the event's domxref("DragEvent.dataTransfer","dataTransfer")}} property will hold the data that is being dragged. The getData() method may be used to retrieve the data again.

function onDrop(event) {
  var data = event.dataTransfer.getData("text/plain");
  event.target.textContent = data;
  event.preventDefault();
}

The getData() method takes one argument, the type of data to retrieve. It will return the string value that was set when setData() was called at the beginning of the drag operation. An empty string will be returned if data of that type does not exist. Naturally, though, you would likely know that the right type of data was available, as it was previously checked during a dragover event.

In the example here, once we have retrieved the data, we insert the string as the textual content of the target. This has the effect of inserting the dragged text where it was dropped, assuming that the drop target is an area of text such as a p or div element.

In a web page, you should call the preventDefault() method of the event if you have accepted the drop so that the default browser handling does not handle the dropped data as well. For example, when a link is dragged to a web page, Firefox will open the link. By cancelling the event, this behavior will be prevented.

You can retrieve other types of data as well. If the data is a link, it should have the type text/uri-list. You could then insert a link into the content.

function doDrop(event) {
  var lines = event.dataTransfer.getData("text/uri-list").split("\n");
  for (let line of lines) {
    if (line.startsWith("#"))
      continue;

    let link = document.createElement("a");
    link.href = line;
    link.textContent = line;
    event.target.appendChild(link);
  }
  event.preventDefault();
}

This example inserts a link from the dragged data. As you might be able to guess from the name, the text/uri-list type actually may contain a list of URLs, each on a separate line. In this code, we use the split to split the string into lines, then iterate over the list of lines, inserting each as a link into the document. Note also that we skip links starting with a number sign (#) as these are comments.

For simple cases, you can use the special type URL just to retrieve the first valid URL in the list. For example:

var link = event.dataTransfer.getData("URL");

This eliminates the need to check for comments or iterate through lines yourself; however, it is limited to only the first URL in the list.

The URL type is a special type used only as a shorthand, and it does not appear within the list of types specified in the types property.

Sometimes you may support some different formats, and you want to retrieve the data that is most specific that is supported. In this example, three formats are supported by a drop target.

The following example returns the data associated with the best-supported format:

function doDrop(event) {
  var types = event.dataTransfer.types;
  var supportedTypes = ["application/x-moz-file", "text/uri-list", "text/plain"];
  types = supportedTypes.filter((value) => types.includes(value));
  if (types.length)
    var data = event.dataTransfer.getData(types[0]);
  event.preventDefault();
}

This method relies on JavaScript functionality available in Firefox 3. However, the code could be adjusted to support other platforms.

Finishing a Drag

Once the drag is complete, a dragend event is fired at the source of the drag (the same element that received the dragstart event). This event will fire if the drag was successful[1] or if it was cancelled. However, you can use the dropEffect property to determine what drop operation occurred.

If the dropEffect property has the value none during a dragend, then the drag was cancelled. Otherwise, the effect specifies which operation was performed. The source can use this information after a move operation to remove the dragged item from the old location. The mozUserCancelled property will be set to true if the user cancelled the drag (by pressing Escape), and false if the drag was cancelled for other reasons such as an invalid drop target, or if it was successful.

A drop can occur inside the same window or over another application. The dragend event will always fire regardless. The event's screenX and screenY properties will be set to the screen coordinate where the drop occurred.

After the dragend event has finished propagating, the drag and drop operation is complete.

[1] In Gecko, dragend is not dispatched if the source node is moved or removed during the drag (e.g. on drop or dragover). bug 460801