JavaScript Document prepend() Method

Beginner
⏱️ 11 min read
📚 Updated: Jul 2026
🎯 5 Examples
🚀 5 Try-it labs
Baseline Widely available
Instance method
JavaScript document.prepend() method tutorial — prepend nodes or text to a Document
Overview

What You’ll Learn

document.prepend() is an instance method from the ParentNode API. It inserts nodes or strings before the first 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.prepend() and Document.append(), and five try-it labs.

01

Kind

Instance method

02

Inserts

Before first child

03

Args

Nodes or strings

04

Returns

undefined

05

Live page

Use body

06

Status

Baseline

Fundamentals

Introduction

Every web page has a document object—the root of the DOM tree. Most tutorials teach you to add content with document.body.prepend(...) or document.getElementById("app").prepend(...). Document.prepend() is different: it prepends directly to the Document node itself, not inside <body>.

MDN: Document.prepend() inserts a set of Node objects or strings before the first child of the document. Strings are inserted as equivalent Text nodes. To prepend to an arbitrary element in the tree, see Element.prepend().

💡
Beginner tip

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.prepend(), Document.append(), documentElement.

Concept

Understanding document.prepend()

An instance method on every Document (ParentNode mixin).

  • Target — the Document node (not body or head).
  • Arguments — one or more Node objects or strings (MDN).
  • Strings — become Text nodes automatically.
  • Order — multiple arguments are inserted in the order given.
  • Returns — undefined (unlike appendChild).
  • Empty document — typical first step: prepend root <html> or <svg> (MDN).
  • Live HTML page — prepending a second <html> throws HierarchyRequestError (MDN).
Foundation

📝 Syntax

General forms of document.prepend (MDN):

JavaScript
prepend(param1)
prepend(param1, param2)
prepend(param1, param2, /* …, */ paramN)

Parameters

  • param1, …, paramN — a set of Node objects or strings to insert (MDN).

Return value

None (undefined).

Exceptions

  • HierarchyRequestError DOMException — thrown when the node cannot be inserted at the specified point in the hierarchy (MDN).

Common patterns

JavaScript
// Build a new in-memory document (MDN)
const doc = new Document();
const html = doc.createElement("html");
doc.prepend(html);
// doc.children → HTMLCollection []

// On a live page — prefer body or a container
document.body.prepend("Hello");
document.getElementById("app").prepend(p, " ", span);
Cheat Sheet

⚡ Quick Reference

GoalCode / note
Root on new Documentdoc.prepend(doc.createElement("html"))
Update live page contentdocument.body.prepend(...)
Prepend textel.prepend("Hello")
Prepend several itemsel.prepend(a, " ", b)
Return valueundefined
MDN statusBaseline Widely available (Apr 2018)
Snapshot

🔍 At a Glance

Four facts about document.prepend().

Call
document.prepend

Instance

Returns
undefined

MDN

Live page
use body

Not doc

Status
baseline

Apr 2018

Compare

📋 Document.prepend() vs Element.prepend()

document.prepend(...)element.prepend(...)
Receives onDocument rootAny Element
Main useNew Document() rootEveryday DOM updates
Live HTML pageSecond <html> failsWorks on body, div, etc.
Syntax & stringsSame ParentNode APISame ParentNode API
Hands-On

Examples Gallery

Examples follow MDN Document: prepend(). Start with a fresh Document(), then see what happens on a live page.

📚 Getting Started

MDN’s core examples: build a document root and avoid invalid trees.

Example 1 — Prepend a root <html> to new Document()

MDN: when creating a new document without any existing element, prepend a root HTML element.

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

An empty Document() has no documentElement until you prepend the root. See the Document constructor tutorial.

Example 2 — MDN: HierarchyRequestError on a live page

Prepending a second <html> to an existing HTML document throws (MDN).

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

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

How It Works

MDN: the operation would yield an incorrect node tree. Use document.body.prepend() instead for page content.

📈 Practical Patterns

What to use on a loaded page and how ParentNode helpers compare.

Example 3 — Use document.body.prepend() on a live page

Add content where beginners expect—inside <body>.

JavaScript
const p = document.createElement("p");
p.textContent = "Added to the top of the page";

document.body.prepend(p);
// Same ParentNode API as document.prepend, different target
Try It Yourself

How It Works

See the full Element.prepend() tutorial for multi-argument and string patterns on elements.

Example 4 — Multiple nodes and strings

ParentNode prepend accepts several arguments in one call.

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

html.prepend(body);
body.prepend("Hello ", span, "!");

doc.prepend(html);
console.log(body.textContent); // "Hello !"
Try It Yourself

How It Works

Build structure on elements with prepend/append, then attach the root to the document with doc.prepend(html).

Example 5 — prepend() vs append()

Same ParentNode API; different insertion point.

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

const before = doc.createComment("before-html");
const after = doc.createComment("after-html");

doc.prepend(before); // becomes first child
doc.append(after);   // becomes last child

console.log(doc.firstChild.data); // "before-html"
console.log(doc.lastChild.data);  // "after-html"
Try It Yourself

How It Works

See also Document.append() for the end-of-list counterpart.

Applications

🚀 Common Use Cases

  • In-memory documents — set root <html> or <svg> on new Document() (MDN).
  • Test fixtures — build detached DOM trees before adopting into the live page.
  • Serialization pipelines — compose a document offline, then extract with XMLSerializer.
  • Live page UI — use document.body.prepend() or container el.prepend(), not document.prepend().
  • After parseHTML — parsed documents may already have structure; prepend only when you need a node before the existing root (rare).
  • Comments / text at doc level — rare; usually prepend inside elements instead.

🧠 How document.prepend() Inserts Nodes

1

Choose the parent

document.prepend targets the Document node itself (MDN).

Document
2

Pass nodes or strings

Strings become Text nodes; nodes are inserted in order (MDN).

ParentNode
3

Validate hierarchy

Invalid trees throw HierarchyRequestError (MDN).

DOM rules
4

Children updated

New nodes appear before the document’s first child; method returns undefined.

Important

📝 Notes

  • MDN: Baseline Widely available since April 2018.
  • Not Deprecated, Experimental, or Non-standard.
  • Same ParentNode specification as Element.prepend().
  • On a loaded HTML page, document.documentElement already exists—do not prepend another <html>.
  • For everyday updates, document.body.prepend() is the beginner-friendly choice.
  • Related: Document(), Element.prepend(), Document.append(), adoptNode().
Compatibility

Browser Support

Document.prepend() is Baseline Widely available (MDN: across browsers since April 2018). Logos use the shared browser-image-sprite.png sprite from this project.

✓ 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 48+
Yes
Apple Safari 10+
Yes
Opera 41+
Yes
Internet Explorer No
No
prepend() 100% supported

Bottom line: Use document.prepend() to attach a root element to a new Document(). On a loaded page, prefer document.body.prepend() or Element.prepend().

Wrap Up

Conclusion

document.prepend() inserts nodes or strings before the first 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 parseHTML(), Document.append(), Element.prepend(), or the JavaScript hub.

View Examples Gallery parseHTML()
Pro Tips

💡 Best Practices

✅ Do

  • Use doc.prepend(html) when bootstrapping new Document() (MDN)
  • Use document.body.prepend() for live page content
  • Pass strings directly—no createTextNode needed
  • Wrap risky prepends in try/catch for HierarchyRequestError
  • Cross-link with Element.prepend() for element targets

❌ Don’t

  • Call document.prepend(html) on a loaded HTML page (MDN)
  • Assume prepend returns the inserted node
  • Confuse document.prepend with document.write
  • Prepend foreign-document nodes without adoptNode()
  • Forget DOM hierarchy rules for root elements
Summary

Key Takeaways

Knowledge Unlocked

Five things to remember about prepend()

Document-level ParentNode prepend—roots on new docs, body on live pages.

5
Core concepts
📝01

Kind

instance

document.
🗂02

Target

Document

MDN
🔗03

Live page

use body

Tip
✓04

Returns

undefined

ParentNode
🛡05

Status

baseline

2018
🎯You know when to use document.prepend() vs body.prepend()
Review Quick Reference →

❓ Frequently Asked Questions

It inserts one or more Node objects or strings before the first child of the Document. Strings become Text nodes (MDN).
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, the document already has a root html element, so use document.body.prepend() or document.documentElement.prepend() to add content. document.prepend() is mainly for building a new empty Document() with a root html or svg element (MDN).
Nothing useful — the return value is undefined. Check document.children or childNodes to verify what was added.
MDN: prepending a second html element to an existing HTML document throws HierarchyRequestError because the tree would be invalid.
Both are ParentNode methods. prepend() inserts before the first child; append() inserts after the last child. Both accept multiple nodes/strings and return undefined (MDN).
Did you know?

MDN notes that Document.prepend() and Element.prepend() share the same ParentNode specification—but on a normal web page you almost always call prepend on an element, not on document itself.

Next: parseHTML()

Learn how Document.parseHTML() safely turns HTML strings into Document trees.

parseHTML() →

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)

6 people found this page helpful

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