JavaScript insertBefore() Method

What Is the JavaScript insertBefore() Method?

The JavaScript insertBefore() method inserts a node into the DOM immediately before a specified reference node. You call it on the parent node and provide the new node and the reference child. If the reference node is null, the new node is added at the end of the parent’s child list.

This method is useful when the position of a new element matters and you need to insert it before an existing child without replacing that child.

Syntax

parentNode.insertBefore(newNode, referenceNode);

• parentNode: The parent node where the new node will be inserted.
• newNode: The node you want to insert.
• referenceNode: The existing child node before which the new node is inserted. Pass null to append the new node at the end.

Return value: The method returns the inserted node.

Basic Example of insertBefore()

The following example inserts a new paragraph before an existing paragraph inside a container.

<div id="container">
  <p id="second">Second paragraph</p>
</div>

<script>
  const container = document.getElementById("container");
  const second = document.getElementById("second");

  const first = document.createElement("p");
  first.textContent = "First paragraph";

  container.insertBefore(first, second);
</script>

The new paragraph appears before the paragraph with the ID second.

Insert a New List Item Before an Existing Item

You can use insertBefore() to add an item at a specific position in a list.

<ul id="languages">
  <li id="css">CSS</li>
  <li>JavaScript</li>
</ul>

<script>
  const list = document.getElementById("languages");
  const cssItem = document.getElementById("css");

  const htmlItem = document.createElement("li");
  htmlItem.textContent = "HTML";

  list.insertBefore(htmlItem, cssItem);
</script>

The resulting order is HTML, CSS, and JavaScript because the new list item is inserted before the CSS item.

Insert a Node at the Beginning of a Parent

To insert a node at the beginning, use the parent’s firstChild as the reference node.

const list = document.getElementById("languages");
const newItem = document.createElement("li");

newItem.textContent = "Python";
list.insertBefore(newItem, list.firstChild);

This inserts the new item before the first child node. If the parent is empty, firstChild is null, and the new node is inserted as the first child.

Insert a Node at the End Using null

When the second argument is null, insertBefore() inserts the new node at the end of the parent’s child list.

const list = document.getElementById("languages");
const newItem = document.createElement("li");

newItem.textContent = "TypeScript";
list.insertBefore(newItem, null);

This behavior is similar to using appendChild() for adding a node at the end.

Insert Text Before an Existing Node

The insertBefore() method accepts any DOM node, including text nodes. Use document.createTextNode() when you need to insert plain text rather than an HTML element.

<div id="message">
  <strong>World</strong>
</div>

<script>
  const message = document.getElementById("message");
  const strong = message.querySelector("strong");

  const greeting = document.createTextNode("Hello ");
  message.insertBefore(greeting, strong);
</script>

The container now displays the text “Hello ” before the strong element.

Move an Existing Node with insertBefore()

If the node you pass as newNode already exists in the document, insertBefore() moves it from its current position to the new position. It does not create a duplicate node.

<ul id="tasks">
  <li id="task1">Task 1</li>
  <li id="task2">Task 2</li>
  <li id="task3">Task 3</li>
</ul>

<script>
  const tasks = document.getElementById("tasks");
  const task3 = document.getElementById("task3");
  const task1 = document.getElementById("task1");

  tasks.insertBefore(task3, task1);
</script>

The order becomes Task 3, Task 1, and Task 2. The original Task 3 node is moved to the beginning of the list.

Use insertBefore() with a Conditional Reference Node

You can check whether a reference element exists before inserting a new node. This helps avoid passing an unintended reference.

const parent = document.getElementById("content");
const reference = document.getElementById("target");

const newElement = document.createElement("p");
newElement.textContent = "New content";

if (parent) {
  parent.insertBefore(newElement, reference);
}

If reference is null, the new paragraph is appended to the parent. If it refers to a child of another parent, the browser throws a NotFoundError.

insertBefore() vs appendChild()

Both methods insert a node into a parent, but they differ in how the insertion position is selected.

Use insertBefore() when you need a specific position. Use appendChild() when the node should be added at the end.

Common Errors When Using insertBefore()

• NotFoundError: The reference node is not a child of the parent on which insertBefore() is called.
• Null parent: A selector may return null if the parent element does not exist. Check the parent before calling the method.
• Unexpected text nodes: firstChild can refer to whitespace text. Use firstElementChild when you specifically need the first element child.
• Moving instead of copying: Inserting an existing node moves it. Use cloneNode() if you need a separate copy.

Browser Support

The insertBefore() method is part of the standard DOM Node interface and is supported by all modern browsers, including Chrome, Firefox, Safari, and Edge.