Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท DOM: Document and Elements

Element.insertAdjacentHTML()

Reference for Element.insertAdjacentHTML(): insert HTML before, after or inside an element without re-parsing its existing children, with positions and security notes.

The insertAdjacentHTML() method parses a string as HTML and inserts the resulting nodes at one of four positions relative to an element: before it, after it, or at the start or end of its children. The element's existing content is left alone, which makes it the right tool for "add this markup next to what is already there".

Compare it with innerHTML +=, which throws away every child, re-parses all the markup and builds new nodes. That loses event listeners, form state and focus on the old children. insertAdjacentHTML() only creates the new nodes.

JavaScript
element.insertAdjacentHTML("beforeend", "<li>New item</li>");

Try it

The four positions
Appending without losing state

The first button keeps the script-changed value of the input. The second one rebuilds the input from its markup, so the value goes back to untouched.

Syntax

JavaScript
element.insertAdjacentHTML(position, text)
Name Description
position Where to insert, relative to element. One of "beforebegin" (before the element itself), "afterbegin" (inside, before its first child), "beforeend" (inside, after its last child) or "afterend" (after the element itself). Matching is case-insensitive.
text A string of HTML to parse and insert.

Return value: undefined.

Exceptions:

  • SyntaxError (DOMException) if position is not one of the four values.
  • NoModificationAllowedError (DOMException) if you use "beforebegin" or "afterend" on an element that has no parent, for example a freshly created element or the document's root element.

Usage notes

  • Positions in one picture. Think of the element as <!-- beforebegin --><div><!-- afterbegin -->...children...<!-- beforeend --></div><!-- afterend -->.
  • Existing nodes are untouched. References to old children stay valid, and their listeners and state survive. This is the main advantage over innerHTML +=.
  • Never pass untrusted text. The string is parsed as markup, so something like <img src="x" onerror="..."> from a user would run code. For plain text use textContent, or build nodes with createElement() and append(). Scripts written as <script> elements in the string do not execute, but event-handler attributes do.
  • Context matters for parsing. The HTML is parsed in the context of the element (or its parent for the outer positions), so inserting <tr> into a <tbody> works, while the same string inserted into a <div> is dropped by the parser.
  • Siblings for text and elements. Two related methods insert a node or plain text instead of HTML: insertAdjacentElement() (returns the inserted element, or null if it could not be inserted) and insertAdjacentText().
  • Performance. One call with a large string is faster than many small calls in a loop, because parsing and layout work are batched.

Browser support

Supported in all browsers for a very long time.