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 July 2015.
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
add(data, type)
add(file)
Parameters
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 whosekind
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
<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>
CSS
div {
margin: 0em;
padding: 2em;
}
#source {
color: blue;
border: 1px solid black;
}
#target {
border: 1px solid black;
}
JavaScript
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
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");
}
function drop_handler(ev) {
console.log("Drop");
ev.preventDefault();
const data = event.dataTransfer.items;
// Loop through the dropped items and log their data
for (let 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((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((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((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");
const dataList = ev.dataTransfer.items;
for (let i = 0; i < dataList.length; i++) {
dataList.remove(i);
}
// Clear any remaining drag data
dataList.clear();
}
Result
Specifications
Specification |
---|
HTML Standard # dom-datatransferitemlist-add-dev |
Browser compatibility
BCD tables only load in the browser