W3cubDocs

/Web APIs

DocumentFragment

The DocumentFragment interface represents a minimal document object that has no parent.

It is used as a lightweight version of Document that stores a segment of a document structure comprised of nodes just like a standard document. The key difference is due to the fact that the document fragment isn't part of the active document tree structure. Changes made to the fragment don't affect the document.

EventTarget Node DocumentFragment

Constructor

DocumentFragment()

Creates and returns a new DocumentFragment object.

Instance properties

This interface has no specific properties, but inherits those of its parent, Node.

DocumentFragment.childElementCount Read only

Returns the amount of child elements the DocumentFragment has.

DocumentFragment.children Read only

Returns a live HTMLCollection containing all objects of type Element that are children of the DocumentFragment object.

DocumentFragment.firstElementChild Read only

Returns the Element that is the first child of the DocumentFragment object, or null if there is none.

DocumentFragment.lastElementChild Read only

Returns the Element that is the last child of the DocumentFragment object, or null if there is none.

Instance methods

This interface inherits the methods of its parent, Node.

DocumentFragment.append()

Inserts a set of Node objects or string objects after the last child of the document fragment.

DocumentFragment.prepend()

Inserts a set of Node objects or string objects before the first child of the document fragment.

DocumentFragment.querySelector()

Returns the first Element node within the DocumentFragment, in document order, that matches the specified selectors.

DocumentFragment.querySelectorAll()

Returns a NodeList of all the Element nodes within the DocumentFragment that match the specified selectors.

DocumentFragment.replaceChildren()

Replaces the existing children of a DocumentFragment with a specified new set of children.

DocumentFragment.getElementById()

Returns the first Element node within the DocumentFragment, in document order, that matches the specified ID. Functionally equivalent to Document.getElementById().

Usage notes

A common use for DocumentFragment is to create one, assemble a DOM subtree within it, then append or insert the fragment into the DOM using Node interface methods such as appendChild(), append(), or insertBefore(). Doing this moves the fragment's nodes into the DOM, leaving behind an empty DocumentFragment.

This interface is also of great use with Web components: <template> elements contain a DocumentFragment in their HTMLTemplateElement.content property.

An empty DocumentFragment can be created using the document.createDocumentFragment() method or the constructor.

Performance

The performance benefit of DocumentFragment is often overstated. In fact, in some engines, using a DocumentFragment is slower than appending to the document in a loop as demonstrated in this benchmark. However, the difference between these examples is so marginal that it's better to optimize for readability than performance.

Example

HTML

html

<ul></ul>

JavaScript

js

const ul = document.querySelector("ul");
const fruits = ["Apple", "Orange", "Banana", "Melon"];

const fragment = new DocumentFragment();

for (const fruit of fruits) {
  const li = document.createElement("li");
  li.textContent = fruit;
  fragment.append(li);
}

ul.append(fragment);

Result

Specifications

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
DocumentFragment 29 17 24 No 16 8 4.4 29 24 16 8 2.0
DocumentFragment 1 12 1 6 8 3 4.4 18 4 10.1 1 1.0
append 54 17 49 No 41 10 54 54 49 41 10 6.0
childElementCount 29 17 25 No 16 9 4.4 29 25 16 9 2.0
children 29 16 25 No 16 9 4.4 29 25 16 9 2.0
firstElementChild 29 17 25 No 16 9 4.4 29 25 16 9 2.0
getElementById 36 17 28 No 23 9 37 36 28 24 9 3.0
lastElementChild 29 17 25 No 16 9 4.4 29 25 16 9 2.0
prepend 54 17 49 No 41 10 54 54 49 41 10 6.0
querySelector 2 12 3.5 9
8querySelectorAll() is supported, but only for CSS 2.1 selectors.
10 4 ≤37 18 4 10.1 3 1.0
querySelectorAll 2 12 3.5 9
8querySelectorAll() is supported, but only for CSS 2.1 selectors.
10 4 ≤37 18 4 10.1 3 1.0
replaceChildren 86 86 78 No 72 14 86 86 79 61 14 14.0

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment