DataTransferItemList.add()

This article needs a technical review. How you can help.

The DataTransferItemList.add() method adds a new drag data item to the drag data list. The item may be a File or a string of a specific type. If the item is successfully added to the list, a new DataTransferItem object will be returned.

Syntax

DataTransferItem dataTransferItemList.add(data, type);
DataTransferItem dataTransferItemList.add(file);

Arguments

The arguments for the first invocation are:

data
A string representing the drag item's data.
type
A string of the drag item's type. Some example types are text/html and text/plain.

The arguments for the second invocation are:

file
A File object.

Return value

DataTransferItem
If the drag data item is successfully added to the drag item list, a new DataTransferItem object is returned; otherwise null is returned.

If the first invocation of this method (adding a string) is used, and the list already contains an item whose kind is Plan Unicode string and whose type is equal to the value of the type argument, a NotSupportedError exception is thrown.

Example

This example shows the use of the add() method.

<!DOCTYPE html>
<html lang=en>
<title>Examples of DataTransferItemList methods and property</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");
  // Add this element's id to the drag payload so the drop handler will
  // know which element to add to its tree
  var dataList = ev.dataTransfer.items;
  dataList.add(ev.target.id, "text/plain");
  // Add some other items to the drag payload 
  dataList.add("<p>... paragraph ...</p>", "text/html");
  dataList.add("http://www.example.org","text/uri-list");
}

function drop_handler(ev) {
  console.log("Drop");
  ev.preventDefault();
  var data = event.dataTransfer.items;
  // Loop through the dropped items and log their data
  for (var i = 0; i < data.length; i++) {
    if ((data[i].kind == 'string') && (data[i].type.match('^text/plain'))) {
      // This item is the target node
      data[i].getAsString(function (s){
        ev.target.appendChild(document.getElementById(s)); 
      });
    } else if ((data[i].kind == 'string') && (data[i].type.match('^text/html'))) {
      // Drag data item is HTML
      data[i].getAsString(function (s){
        console.log("... Drop: HTML = " + s);
      });
    } else if ((data[i].kind == 'string') && (data[i].type.match('^text/uri-list'))) {
      // Drag data item is URI
      data[i].getAsString(function (s){
        console.log("... Drop: URI = " + s);
      });
    }
  }
}

function dragover_handler(ev) {
  console.log("dragOver");
  ev.preventDefault();
  // Set the dropEffect to move
  ev.dataTransfer.dropEffect = "move"
}

function dragend_handler(ev) {
  console.log("dragEnd");
  var dataList = ev.dataTransfer.items;
  for (var i = 0; i < dataList.length; i++) {
    dataList.remove(i);
  }
  // Clear any remaining drag data
  dataList.clear();
}
</script>
<body>
<h1>Example uses of <code>DataTransferItemList</code> methods and property</h1>
 <div>
   <p id="source" ondragstart="dragstart_handler(event);" ondragend="dragend_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
WHATWG HTML Living Standard
The definition of 'add()' in that specification.
Living Standard  
HTML5.1
The definition of 'add()' in that specification.
Working Draft Not included in W3C HTML5 Recommendation

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support No support No support No support 12 No support
Feature Android Android Webview Chrome for Android Firefox Mobile (Gecko) Firefox OS IE Mobile Opera Mobile Safari Mobile
Basic support No support No support No support No support No support No support No support No support

Document Tags and Contributors

 Contributors to this page: rolfedh, AFBarstow
 Last updated by: rolfedh,