JavaScript Element before() Method

What You’ll Learn

Element.before() is an instance method from the ChildNode API. It inserts nodes or strings in the parent’s child list, just before the element you call it on. Learn multi-argument inserts, text coercion, how it compares to after(), and five try-it labs.

Introduction

Older DOM code often used parent.insertBefore(newNode, ref) to place something before a sibling. before() makes that intent clear: call it on the element that should come second, and pass what should appear ahead of it.

You can pass elements, other nodes, or plain strings. Strings become Text nodes automatically—handy for labels and spacing without creating nodes by hand.

This page is part of JavaScript Element. Related DOM helpers include insertBefore() and after().

Understanding the before() Method

Calling el.before(...nodes) does not add children inside el. It updates el’s parent so the new nodes sit immediately before el among siblings.

• It is an instance method on Element (ChildNode mixin).
• Arguments can be Node objects or strings (as Text).
• Multiple arguments insert in the order you pass them.
• Existing nodes in the document are moved, not cloned.
• Return value is undefined—inspect the DOM to confirm.

📝 Syntax

General forms of Element.before (MDN):

before(param1)
before(param1, param2)
before(param1, param2, /* …, */ paramN)

Parameters

• param1, …, paramN — a set of Node objects or strings to insert. Strings are inserted as equivalent Text nodes.

Return value

None (undefined).

Exceptions

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

Common patterns

const p = document.querySelector("p");
const span = document.createElement("span");

p.before(span);                 // insert one element
p.before("Text");               // insert a Text node
p.before(span, "Text");         // element, then text
p.before(" · ", span, " · ");  // several siblings in order

Examples Gallery

Examples follow MDN Element.before() patterns. Use View Output or Try It Yourself for each case.

let container = document.createElement("div");
let p = document.createElement("p");
container.appendChild(p);
let span = document.createElement("span");

p.before(span);

console.log(container.outerHTML);
// "<div><span></span><p></p></div>"

<div><span></span><p></p></div>

let container = document.createElement("div");
let p = document.createElement("p");
container.appendChild(p);

p.before("Text");

console.log(container.outerHTML);
// "<div>Text<p></p></div>"

<div>Text<p></p></div>

let container = document.createElement("div");
let p = document.createElement("p");
container.appendChild(p);
let span = document.createElement("span");

p.before(span, "Text");

console.log(container.outerHTML);
// "<div><span></span>Text<p></p></div>"

<div><span></span>Text<p></p></div>

const item = document.getElementById("item");
const badge = document.createElement("strong");
badge.textContent = "NEW";
const note = document.createElement("em");
note.textContent = "sale";

item.before(badge, " — ", note);

console.log(item.parentElement.innerHTML);
// <strong>NEW</strong> — <em>sale</em><li id="item">Shoes</li>

<strong>NEW</strong> — <em>sale</em><li id="item">Shoes</li>

const list = document.getElementById("list");
const a = document.getElementById("a");
const b = document.getElementById("b");

b.before(a);

console.log([...list.children].map((el) => el.id).join(", "));
// "a, b"  (a moved to sit before b)

a, b

🚀 Common Use Cases

• Inserting a badge, icon, or label right before a title or list item.
• Adding helper text or separators without wrapping extra containers.
• Reordering siblings by moving an existing node ahead of another.
• Replacing the classic parent.insertBefore(newNode, ref) pattern with clearer code.
• Building small UI trails (element + text + element) in one call.
• Teaching sibling insertion vs appending children inside an element.

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available since April 2018).
• before() inserts siblings, not children of the element.
• Return value is always undefined.
• Invalid hierarchy can raise HierarchyRequestError.
• Same ChildNode family: after(), append(), prepend(), replaceWith().
• Related: after(), insertBefore(), children, JavaScript hub.

💡 Best Practices