JavaScript Document prepend() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method
Decorative image with the word PREPEND

Definition

document.prepend() inserts one or more Node objects or strings before the first child of the Document. Strings become Text nodes. On a normal loaded page, you usually want document.body.prepend() instead.

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call document.prepend. Start with this line.

JavaScript
document.prepend(…nodesOrStrings)
CallWhat it does
document.prepend(…nodesOrStrings)Primary signature.
document.prepend(...)Call with the arguments your case needs.

Built into the browser. Call prepend(...) on document — no import required.

Library declarations
JavaScript
document.prepend(…nodesOrStrings)

Parameters

ParameterDescription
param1…paramNRequired. Nodes and/or strings to insert

Return Value

Return ValueDescription
*Always undefined

JavaScript Examples

Example 1 — Prepend a Root to new Document()

MDN pattern: attach an <html> root to an empty document.

JavaScript
const doc = new Document();
const html = doc.createElement("html");

doc.prepend(html);

console.log(doc.children.length);              // 1
console.log(doc.documentElement === html);     // true
Try It Yourself

How It Works

  1. Start empty. new Document() has no element children yet.
  2. Create the root. Use that document’s createElement("html").
  3. Prepend the root. doc.prepend(html) makes it the document element.
  4. Verify. children.length is 1 and documentElement matches.

Example 2 — Live Page Throws HierarchyRequestError

A loaded HTML document already has a root. Prepending another html fails.

JavaScript
const html = document.createElement("html");

try {
  document.prepend(html);
} catch (err) {
  console.log(err.name);
  // "HierarchyRequestError"
}
Try It Yourself

How It Works

  1. The page already has <html>. A Document may have only one element child of that kind.
  2. Try to prepend another. The engine rejects an invalid tree.
  3. Catch the error. Name is HierarchyRequestError (MDN).
  4. Fix. Prepend under body (or another element), not onto document.

Example 3 — Everyday Content with body.prepend()

Same ParentNode API on an element — insert at the start of body.

JavaScript
const note = document.createElement("p");
note.textContent = "Hello";

document.body.prepend(note, " from prepend");

console.log(document.body.firstChild === note);
// true
console.log(note.nextSibling.textContent);
// " from prepend"
Try It Yourself

How It Works

  1. Create a paragraph. This is normal page content, not a document root.
  2. Prepend to body. Pass a node and a string in one call.
  3. Order matters. Arguments keep order: note is first, then the text node.
  4. Why this path. On live pages, Element.prepend / body.prepend is the safe ParentNode prepend.
Compatibility

Browser Support

Document.prepend() is a browser DOM API marked Baseline Widely available on MDN (across browsers since April 2018).

✓ Baseline Widely available

Document.prepend()

ParentNode prepend on Document — build roots on new Document(); use body.prepend on live pages.

Baseline Widely available
Google Chrome 54+
Yes
Microsoft Edge 17+
Yes
Mozilla Firefox 49+
Yes
Apple Safari 10+
Yes
Opera 41+
Yes
Internet Explorer No
No
prepend() Excellent in browsers

Bottom line: Safe in modern browsers. On a loaded page prefer document.body.prepend(). See the MDN Document.prepend() reference.

Frequently Asked Questions

It inserts one or more Node objects or strings before the first child of the Document. Strings become Text nodes. The return value is undefined.
No. MDN marks Document.prepend() as Baseline Widely available (across browsers since April 2018). It is not Deprecated, Experimental, or Non-standard.
On a loaded HTML page, use document.body.prepend() (or Element.prepend) to add content. document.prepend() is mainly for attaching a root html or svg element to a new empty Document().
undefined. Check document.children or documentElement to verify what was added.
A live HTML document already has a root html element. Prepending another one throws HierarchyRequestError because the tree would be invalid.
Both are ParentNode methods and accept multiple nodes/strings. prepend() inserts before the first child; append() inserts after the last child. Both return undefined.

Next: parseHTML()

Learn how to parse HTML into a new Document safely.

parseHTML() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

19 people found this page helpful

JavaScript Document open() Method JavaScript Document parseHTML() Method