JavaScript Node insertBefore() Method

Beginner
5 min read
Updated: Oct 2026
3 examples
Live preview
JavaScript Node.insertBefore() — insert a child before a reference sibling
Definition

What Is insertBefore()?

parent.insertBefore(newNode, referenceNode) inserts newNode as a child of parent, immediately before referenceNode (MDN). If referenceNode is null, the node is added at the end.

Status: Baseline Widely available (since July 2015) — not Deprecated, Experimental, or Non-standard. There is no insertAfter() — emulate with nextSibling.

Remember
parent.insertBefore(newNode, referenceNode)
→ newNode sits just before referenceNode
→ returns newNode (empty fragment if DocumentFragment)

referenceNode === null  → insert at end (like appendChild)
Existing newNode in document → moved (not copied)

insertAfter?
  parent.insertBefore(newNode, ref.nextSibling)
GoalPrefer
Insert before a siblinginsertBefore(newNode, ref)
Append at the endinsertBefore(newNode, null) or appendChild()
Insert after a siblinginsertBefore(newNode, ref.nextSibling)
Element API (sibling of self)Element.before()
Approach

How to Use insertBefore()

Pick a parent, a new node, and the sibling that should come after it.

  1. Get the parent (often referenceNode.parentNode).
  2. Create or select newNode.
  3. Pass a child of that parent as referenceNode, or pass null for the end.
  4. Call parent.insertBefore(newNode, referenceNode) — always pass the second argument.
PieceRequired?Role
parentYesNode that receives the child
newNodeYesNode to insert (or a DocumentFragment)
referenceNodeYes (or null)Existing child to insert before; null = append
Return—The inserted newNode (empty fragment if fragment)

Pseudocode

Pseudocode
ref = getElementById("child")
parent = ref.parentNode
newNode = createElement("span")

parent.insertBefore(newNode, ref)
→ children: [..., newNode, ref, ...]

parent.insertBefore(newNode, null)
→ newNode at end

// insert after ref:
parent.insertBefore(newNode, ref.nextSibling)
Reference

Cheat Sheet

Keep these facts handy when inserting siblings.

TopicDetail
Syntaxparent.insertBefore(newNode, referenceNode)
ReturnsInserted newNode (or empty fragment)
null referenceInsert at end of children
Existing nodeMoved, not cloned
Second argRequired — pass a Node or null (MDN)
insertAfterinsertBefore(newNode, ref.nextSibling)
StandardBaseline Widely available (since July 2015)
Try it

Live Preview

Insert before the marker, append with null, or insert after the marker via nextSibling.

List
  • A
  • marker
  • C

Browser demo of Node.insertBefore() — before, null, and after.

Result
Choose an action, then Run…
Code

JavaScript Examples

Short, copy-ready snippets. Open DevTools Console, or use Try It Yourself for a live editor.

Example 1 — Insert Before a Sibling

Create a node and place it immediately before an existing child (MDN).

JavaScript
const sp1 = document.createElement("span");
sp1.textContent = "NEW";

const sp2 = document.getElementById("childElement");
const parent = sp2.parentNode;

parent.insertBefore(sp1, sp2);
console.log(parent.firstElementChild.textContent); // "NEW"
Try It Yourself

How It Works

  1. Create the new node. Not in the tree yet.
  2. Find the reference child. The sibling that should come after.
  3. Use its parent. Call insertBefore on that parent.
  4. Result. newNode sits immediately before sp2.

Example 2 — null Appends at the End

MDN: pass null as the reference to insert at the end of the child list.

JavaScript
const list = document.getElementById("list");
const li = document.createElement("li");
li.textContent = "last";

list.insertBefore(li, null);
console.log(list.lastElementChild.textContent); // "last"
Try It Yourself

How It Works

  1. Second argument is required. Pass null explicitly (MDN).
  2. Null means “end”. Node becomes the last child.
  3. Same idea as appendChild. Useful when the reference may be missing.
  4. Do not omit the arg. Invalid / missing values differ by browser.

Example 3 — Emulate insertAfter

There is no insertAfter(). Use nextSibling (MDN).

JavaScript
const parent = document.getElementById("parent");
const sp2 = document.getElementById("child");
const sp1 = document.createElement("span");
sp1.textContent = "AFTER";

parent.insertBefore(sp1, sp2.nextSibling);
// if sp2 is last, nextSibling is null → sp1 goes at the end
Try It Yourself

How It Works

  1. Want after sp2. Insert before whatever follows sp2.
  2. Use nextSibling. That node becomes the reference.
  3. Last child case. nextSibling is null → appends at end.
  4. Same method. Still insertBefore — no separate API.

Edge Cases & Pitfalls

Check these before relying on insertBefore() in real UIs.

args

Second argument is required

MDN: always pass a Node or null. Omitting it or passing invalid values can differ by browser.

move

Existing nodes are moved

A node cannot live in two places. Use cloneNode() when you need a copy.

ref

Reference must be a child of the parent

Inserting with a reference that is not under that parent can throw (hierarchy / NotFound errors).

modern

Element.before / prepend alternatives

For element siblings, before() / prepend() can be clearer — insertBefore still works on any Node parent.

Compatibility

Browser Support

Node.insertBefore() is marked Baseline Widely available on MDN (since July 2015).

✓ Baseline · Widely available

Node.insertBefore()

Inserts a child before a reference node (or at the end when the reference is null). Moves existing nodes. Returns the inserted child.

100% Widely available
Google Chrome Yes (Baseline)
Yes
Microsoft Edge Yes (Baseline)
Yes
Mozilla Firefox Yes (Baseline)
Yes
Apple Safari Yes (Baseline)
Yes
Opera Yes (Baseline)
Yes
Internet Explorer Supported (legacy)
Yes
insertBefore() Excellent

Bottom line: Safe everyday DOM API. Always pass the second argument. See the MDN insertBefore reference.

Analysis

Performance Notes

ApproachCostBest for
One insertBeforeOne DOM updateSingle ordered insert
Many inserts in a loopCan reflow oftenAvoid for large lists
DocumentFragment then one insertOne attachBatch many children

For many nodes, build into a fragment, then insertBefore once — fewer layout thrashers than N separate inserts.

Remember

Key Takeaways

  • Inserts before: newNode sits just ahead of referenceNode.
  • null = end: same idea as appending.
  • Moves: existing document nodes relocate — clone to copy.
  • No insertAfter: use ref.nextSibling as the reference.

One line: insertBefore(newNode, ref) places a child before a sibling — pass null for the end, or ref.nextSibling for after.

Frequently Asked Questions

It inserts newNode as a child of the parent, immediately before referenceNode. If referenceNode is null, newNode is inserted at the end of the parent’s children.
No. MDN marks Node.insertBefore() as Baseline Widely available (since July 2015). It is a standard DOM method — not Deprecated, Experimental, or Non-standard.
insertBefore moves it from its old position to the new one. A node cannot be in two places at once. Use cloneNode() if you need a copy.
No. MDN shows you can emulate it with parent.insertBefore(newNode, referenceNode.nextSibling). If there is no next sibling, nextSibling is null and the node is appended at the end.
No. MDN says referenceNode is required — pass a Node or explicitly null. Omitting it or passing invalid values can behave differently across browsers.
It returns the inserted child. If newNode is a DocumentFragment, it returns the emptied fragment after its contents move.

Next: isDefaultNamespace()

Check whether a namespace URI is the default for a node.

isDefaultNamespace 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)

9 people found this page helpful

JavaScript Node hasChildNodes() Method JavaScript Node isDefaultNamespace() Method