DataTransferItemList: add() method

Baseline Widely available

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

The DataTransferItemList.add() method creates a new DataTransferItem using the specified data and adds it to the drag data list. The item may be a File or a string of a given type. If the item is successfully added to the list, the newly-created DataTransferItem object is returned.

Syntax

js
add(data, type)
add(file)

Parameters

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.

file

A File object. No type needs to be given in this case.

Return value

A DataTransferItem containing the specified data. If the drag item couldn't be created (for example, if the associated DataTransfer object has no data store), null is returned.

Exceptions

NotSupportedError DOMException

Thrown if the string data parameter was provided, and the list already contains an item whose kind is "Plain Unicode string" and whose type is equal to the specified type parameter.

Examples

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

HTML

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

css
div {
  margin: 0em;
  padding: 2em;
}
#source {
  color: blue;
  border: 1px solid black;
}
#target {
  border: 1px solid black;
}

JavaScript

js
const source = document.getElementById("source");
const target = document.getElementById("target");

source.addEventListener("dragstart", (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
  const 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");
});

source.addEventListener("dragend", (ev) => {
  console.log("dragEnd");
  const dataList = ev.dataTransfer.items;
  for (let i = 0; i < dataList.length; i++) {
    dataList.remove(i);
  }
  // Clear any remaining drag data
  dataList.clear();
});

target.addEventListener("drop", (ev) => {
  console.log("Drop");
  ev.preventDefault();
  // Loop through the dropped items and log their data
  for (const item of event.dataTransfer.items) {
    if (item.kind === "string" && item.type.match("^text/plain")) {
      // This item is the target node
      item.getAsString((s) => {
        ev.target.appendChild(document.getElementById(s));
      });
    } else if (item.kind === "string" && item.type.match("^text/html")) {
      // Drag data item is HTML
      item.getAsString((s) => {
        console.log(`… Drop: HTML = ${s}`);
      });
    } else if (item.kind === "string" && item.type.match("^text/uri-list")) {
      // Drag data item is URI
      item.getAsString((s) => {
        console.log(`… Drop: URI = ${s}`);
      });
    }
  }
});

target.addEventListener("dragover", (ev) => {
  console.log("dragOver");
  ev.preventDefault();
  // Set the dropEffect to move
  ev.dataTransfer.dropEffect = "move";
});

Result

Specifications

Specification
HTML
# dom-datatransferitemlist-add-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
add
Chrome – Full support
Chrome 13 (Release date: 2011-08-02)
footnote Full support
Edge – Full support
Edge 12 (Release date: 2015-07-29)
footnote Full support
Firefox – Full support
Firefox 50 (Release date: 2016-11-15)
footnote Full support
Opera – Full support
Opera 12 (Release date: 2012-06-14)
footnote Full support
Safari – Full support
Safari 6 (Release date: 2012-07-25)
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 50 (Release date: 2016-11-15)
footnote Full support
Opera Android – Full support
Opera Android 14 (Release date: 2013-05-21)
footnote Full support
Safari on iOS – Full support
Safari on iOS 6 (Release date: 2012-09-10)
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 6 (Release date: 2012-09-10)
footnote Full support

Legend

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

Full support
Full support