JavaScript Element insertAdjacentElement() Method

What You’ll Learn

Element.insertAdjacentElement() is an instance method that inserts an Element node at one of four positions relative to the target element: beforebegin, afterbegin, beforeend, and afterend. Learn the MDN position diagram, comparison with append() and insertAdjacentHTML(), and five try-it labs aligned with MDN.

Introduction

When you build dynamic UIs, you often need to place a new element in a precise spot: before a list item, as the first child of a panel, at the end of a container, or right after a card. insertAdjacentElement(position, element) does exactly that without manually calling parent.insertBefore().

MDN: the method inserts a given element node at a given position relative to the element it is invoked upon. You pass a position string and an Element to insert.

This page is part of JavaScript Element. See also append() for adding children at the end, and before() for inserting siblings.

Understanding the insertAdjacentElement() Method

Calling target.insertAdjacentElement(position, newEl) places newEl relative to target.

• It is an instance method on Element.
• First argument: position string (case-insensitive per MDN).
• Second argument: the Element node to insert.
• Returns the inserted element, or null if insertion failed (MDN).
• Throws SyntaxError if position is not recognized (MDN).
• Throws TypeError if the second argument is not a valid element (MDN).
• beforebegin / afterend require an element parent in the tree (MDN).

📝 Syntax

General form of Element.insertAdjacentElement (MDN):

insertAdjacentElement(position, element)

Parameters

position — One of "beforebegin", "afterbegin", "beforeend", or "afterend" (MDN).

element — The element node to insert into the tree (MDN).

Return value

The element that was inserted, or null if the insertion failed (MDN).

Position diagram (MDN)

<!-- beforebegin -->
<p>
  <!-- afterbegin -->
  foo
  <!-- beforeend -->
</p>
<!-- afterend -->

Common patterns

// MDN: insert before or after a selected element
const newElement = document.createElement("div");
selectedElem.insertAdjacentElement("beforebegin", newElement);
selectedElem.insertAdjacentElement("afterend", newElement);

// Prepend inside container (first child)
const first = document.createElement("span");
container.insertAdjacentElement("afterbegin", first);

// Append inside container (last child)
const last = document.createElement("span");
container.insertAdjacentElement("beforeend", last);

// Check return value
const inserted = box.insertAdjacentElement("beforeend", item);
if (!inserted) console.log("insertion failed");

Examples Gallery

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

function insertNewElement(position) {
  if (!selectedElem) return;

  const newElement = document.createElement("div");
  newElement.textContent = "New";
  newElement.className = "box";

  selectedElem.insertAdjacentElement(position, newElement);
}

// MDN demo uses:
insertNewElement("beforebegin"); // before selected
insertNewElement("afterend");    // after selected

div.box inserted before/after target

const list = document.getElementById("list");
const first = document.createElement("li");
first.textContent = "First item";

list.insertAdjacentElement("afterbegin", first);
console.log(list.firstElementChild === first); // true

true

const panel = document.getElementById("panel");
const note = document.createElement("p");
note.textContent = "Added at end";

panel.insertAdjacentElement("beforeend", note);
console.log(panel.lastElementChild === note); // true

true

const card = document.getElementById("card");
const banner = document.createElement("div");
banner.className = "banner";
banner.textContent = "New banner";

card.insertAdjacentElement("beforebegin", banner);
console.log(card.previousElementSibling === banner); // true

true

const box = document.getElementById("box");
const chip = document.createElement("span");
chip.textContent = "chip";

const inserted = box.insertAdjacentElement("beforeend", chip);

if (inserted) {
  console.log("inserted:", inserted.textContent);
} else {
  console.log("insertion failed");
}

inserted: chip

🚀 Common Use Cases

• Inserting items before/after a selected list row (MDN demo pattern).
• Prepending toolbar buttons with afterbegin.
• Appending messages to a chat panel with beforeend.
• Placing banners or alerts as siblings with beforebegin.
• Building dynamic forms without innerHTML strings.
• Moving existing elements to precise positions in the DOM tree.

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available, April 2018).
• Position strings are matched case-insensitively (MDN).
• Returns the inserted element, or null on failure (MDN).
• beforebegin and afterend need an element parent in the tree (MDN).
• Throws SyntaxError for unknown position; TypeError for invalid element (MDN).
• Related: append(), before(), after(), insertAdjacentHTML(), JavaScript hub.

💡 Best Practices