Element: insertAdjacentElement() method

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since April 2018.

The insertAdjacentElement() method of the Element interface inserts a given element node at a given position relative to the element it is invoked upon.

Syntax

js
insertAdjacentElement(position, element)

Parameters

position

A string representing the position relative to the targetElement; must match (case-insensitively) one of the following strings:

  • 'beforebegin': Before the targetElement itself.
  • 'afterbegin': Just inside the targetElement, before its first child.
  • 'beforeend': Just inside the targetElement, after its last child.
  • 'afterend': After the targetElement itself.
element

The element to be inserted into the tree.

Return value

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

Exceptions

SyntaxError DOMException

Thrown if the position specified is not a recognized value.

TypeError

Thrown if the element specified is not a valid element.

Visualization of position names

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

Note: The beforebegin and afterend positions work only if the node is in a tree and has an element parent.

Examples

Inserting before and after

In this example we have a row of square boxes. The user can select a box by clicking on it: this gives the box a different border, to show that it is selected.

If a box is selected, and the user presses the "Insert before" or "Insert after" buttons, then the code creates a new box, gives it a random color, and inserts it before or after the selected box.

HTML

html
<p>
  Click colored box to select it, then use the first two buttons below to insert
  elements before and after your selection.
</p>

<section>
  <div></div>
  <div></div>
  <div></div>
  <div></div>
</section>

<button class="before">Insert before</button>
<button class="after">Insert after</button>
<button class="reset">Reset demo</button>

CSS

css
div {
  width: 50px;
  height: 50px;
  margin: 3px;
  border: 3px solid black;
  display: inline-block;
  background-color: red;
}

.selected {
  border-color: aqua;
}

JavaScript

js
let selectedElem;

// Function to select a new element
function selectElement(newSelection) {
  if (selectedElem !== newSelection) {
    if (selectedElem) {
      selectedElem.classList.remove("selected");
    }
    selectedElem = newSelection;
    newSelection.classList.add("selected");
  }
}

// Add click handlers that select the clicked element
const initElems = Array.from(document.querySelectorAll("section div"));
for (const initElem of initElems) {
  initElem.addEventListener("click", (e) => selectElement(e.target));
}

// Add click handlers to "beforeBtn" and "afterBtn"
// to insert a new element before/after the selected element
const beforeBtn = document.querySelector(".before");
const afterBtn = document.querySelector(".after");
beforeBtn.addEventListener("click", () => insertNewElement("beforebegin"));
afterBtn.addEventListener("click", () => insertNewElement("afterend"));

function insertNewElement(position) {
  function random() {
    return Math.floor(Math.random() * 255);
  }

  if (!selectedElem) {
    return;
  }

  const newElement = document.createElement("div");
  const randomColor = `rgb(${random(255)} ${random(255)} ${random(255)})`;
  newElement.style.backgroundColor = randomColor;
  newElement.addEventListener("click", (e) => selectElement(e.target));

  selectedElem.insertAdjacentElement(position, newElement);
}

// Reset the example
const resetBtn = document.querySelector(".reset");
resetBtn.addEventListener("click", () => window.location.reload(true));

Result

Specifications

Specification
DOM
# dom-element-insertadjacentelement

Browser compatibility

desktop mobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
insertAdjacentElement
Chrome – Full support
Chrome 1 (Release date: 2008-12-11)
footnote Full support
Edge – Partial support
Edge 12 – 16 (Release date: 2015-07-29)
footnote Partial support
footnote Only supported for HTMLElement, not all Element objects, such as SVGElement.
Edge – Full support
Edge 17 (Release date: 2018-04-30)
footnote Full support
Firefox – Full support
Firefox 48 (Release date: 2016-08-02)
footnote Full support
Opera – Full support
Opera 8 (Release date: 2005-04-19)
footnote Full support
Safari – Full support
Safari 3 (Release date: 2007-10-26)
footnote Full support
Chrome Android – Full support
Chrome Android 18 (Release date: 2012-06-27)
footnote Full support
Firefox for Android – Full support
Firefox for Android 48 (Release date: 2016-08-02)
footnote Full support
Opera Android – Full support
Opera Android 10.1 (Release date: 2010-11-09)
footnote Full support
Safari on iOS – Full support
Safari on iOS 1 (Release date: 2007-06-29)
footnote Full support
Samsung Internet – Full support
Samsung Internet 1 (Release date: 2013-04-27)
footnote Full support
WebView Android – Full support
WebView Android 4.4 (Release date: 2013-12-09)
footnote Full support
WebView on iOS – Full support
WebView on iOS 1 (Release date: 2007-06-29)
footnote Full support

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
Has more compatibility info.

See also