document.append() is an instance method from the ParentNode API. It inserts nodes or strings after the last child of the Document. Learn when to use it on a fresh new Document(), why it throws on a loaded page, how it compares to Element.append() and appendChild(), and five try-it labs.
Instance method
After last child
Nodes or strings
undefined
Use body
Baseline
Every web page has a document object—the root of the DOM tree. Most tutorials teach you to add content with document.body.append(...) or document.getElementById("app").append(...). Document.append() is different: it appends directly to the Document node itself, not inside <body>.
MDN: Document.append() inserts a set of Node objects or strings after the last child of the document. Strings are inserted as equivalent Text nodes. To append to an arbitrary element in the tree, see Element.append().
On a normal loaded page, the document already has an <html> root. You usually update document.body or a container element—not document itself. MDN’s main use case is building a brand-new in-memory document with new Document().
Related tutorials: Document constructor, Element.append(), Document.prepend(), documentElement.
document.append()An instance method on every Document (ParentNode mixin).
body or head).Node objects or strings (MDN).Text nodes automatically.undefined (unlike appendChild).<html> or <svg> (MDN).<html> throws HierarchyRequestError (MDN).General forms of Document.append (MDN):
append(param1)
append(param1, param2)
append(param1, param2, /* …, */ paramN)Node objects or strings to insert (MDN).None (undefined).
DOMException — thrown when the node cannot be inserted at the specified point in the hierarchy (MDN).// Build a new in-memory document (MDN)
const doc = new Document();
const html = doc.createElement("html");
doc.append(html);
// doc.children → HTMLCollection []
// On a live page — prefer body or a container
document.body.append("Hello");
document.getElementById("app").append(p, " ", span);| Goal | Code / note |
|---|---|
| Root on new Document | doc.append(doc.createElement("html")) |
| Update live page content | document.body.append(...) |
| Append text | el.append("Hello") |
| Append several items | el.append(a, " ", b) |
| Return value | undefined |
| MDN status | Baseline Widely available (Apr 2018) |
Four facts about document.append().
document.appendInstance
undefinedMDN
use bodyNot doc
baselineApr 2018
Document.append() vs Element.append()document.append(...) | element.append(...) | |
|---|---|---|
| Receives on | Document root | Any Element |
| Main use | New Document() root | Everyday DOM updates |
| Live HTML page | Second <html> fails | Works on body, div, etc. |
| Syntax & strings | Same ParentNode API | Same ParentNode API |
Examples follow MDN Document: append(). Start with a fresh Document(), then see what happens on a live page.
MDN’s core examples: build a document root and avoid invalid trees.
<html> to new Document()MDN: when creating a new document without any existing element, append a root HTML element.
const doc = new Document();
const html = doc.createElement("html");
doc.append(html);
console.log(doc.children.length); // 1
console.log(doc.documentElement === html); // trueAn empty Document() has no documentElement until you append the root. See the Document constructor tutorial.
HierarchyRequestError on a live pageAppending a second <html> to an existing HTML document throws (MDN).
const html = document.createElement("html");
try {
document.append(html);
} catch (err) {
console.log(err.name); // "HierarchyRequestError"
}MDN: the operation would yield an incorrect node tree. Use document.body.append() instead for page content.
What to use on a loaded page and how ParentNode helpers compare.
document.body.append() on a live pageAdd content where beginners expect—inside <body>.
const p = document.createElement("p");
p.textContent = "Added to the page";
document.body.append(p);
// Same ParentNode API as document.append, different targetSee the full Element.append() tutorial for multi-argument and string patterns on elements.
ParentNode append accepts several arguments in one call.
const doc = new Document();
const html = doc.createElement("html");
const body = doc.createElement("body");
const span = doc.createElement("span");
html.append(body);
body.append("Hello ", span, "!");
doc.append(html);
console.log(body.textContent); // "Hello !"Build structure on elements with append, then attach the root to the document with doc.append(html).
append() vs appendChild()appendChild takes one node; append takes nodes and strings.
const doc = new Document();
const html = doc.createElement("html");
const returned = doc.appendChild(html);
console.log(returned === html); // true — appendChild returns the node
doc.append(doc.createComment("note")); // append returns undefined
console.log(doc.lastChild.nodeType); // 8 (Comment)Both work on Document nodes. Prefer append when you need strings or multiple items. See appendChild().
<html> or <svg> on new Document() (MDN).XMLSerializer.document.body.append() or container el.append(), not document.append().document.append() Inserts Nodesdocument.append targets the Document node itself (MDN).
Strings become Text nodes; nodes append in order (MDN).
Invalid trees throw HierarchyRequestError (MDN).
New nodes appear after the document’s last child; method returns undefined.
Element.append().document.documentElement already exists—do not append another <html>.document.body.append() is the beginner-friendly choice.Document.append() is Baseline Widely available (MDN: across browsers since April 2018). Logos use the shared browser-image-sprite.png sprite from this project.
ParentNode append on Document — build roots on new Document(), use body.append on live pages.
Bottom line: Use document.append() to attach a root element to a new Document(). On a loaded page, prefer document.body.append() or Element.append().
document.append() inserts nodes or strings after the last child of the Document. MDN’s key lesson: use it to attach a root <html> or <svg> to a new empty document; on a live page, update document.body or specific elements instead.
Continue with ariaNotify(), ownerDocument, Element.append(), or the JavaScript hub.
doc.append(html) when bootstrapping new Document() (MDN)document.body.append() for live page contentcreateTextNode neededtry/catch for HierarchyRequestErrordocument.append(html) on a loaded HTML page (MDN)append returns the inserted nodedocument.append with document.writeappend()Document-level ParentNode append—roots on new docs, body on live pages.
instance
document.Document
MDNuse body
Tipundefined
ParentNodebaseline
2018MDN notes that Document.append() and Element.append() share the same ParentNode specification—but on a normal web page you almost always call append on an element, not on document itself.
Learn how document.ariaNotify() queues screen reader announcements at the document level.
6 people found this page helpful