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.
element.insertAdjacentHTML("beforeend", "<li>New item</li>");
Try it
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
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) ifpositionis 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 usetextContent, or build nodes withcreateElement()andappend(). 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, ornullif it could not be inserted) andinsertAdjacentText(). - 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.
Related
Element.innerHTMLโ replace all children from a stringElement.append()andprepend()โ insert nodes inside an elementElement.before()andafter()โ insert nodes beside an elementdocument.createElement()โ build elements safely- Lesson: Creating and changing elements