JavaScript insertAdjacentHTML() Method

The JavaScript insertAdjacentHTML() method inserts HTML text into the DOM at a specific position relative to an existing element. It lets you add new HTML without replacing the element’s existing content, making it useful for dynamic interface updates and DOM manipulation.

JavaScript insertAdjacentHTML() Method Syntax

The syntax of the insertAdjacentHTML() method is:

element.insertAdjacentHTML(position, htmlText);

Parameters:

• position: A string that specifies where the HTML should be inserted relative to the element.
• htmlText: A string containing the HTML markup to parse and insert.

Return value: The method returns undefined.

Four Positions of insertAdjacentHTML()

The first argument accepts one of four position values:

The following diagram-like example shows the positions in relation to a selected element:

<!-- beforebegin -->
<div id="box">
    <!-- afterbegin -->
    Existing content
    <!-- beforeend -->
</div>
<!-- afterend -->

JavaScript insertAdjacentHTML() with beforebegin

The beforebegin position inserts the supplied HTML immediately before the selected element, as a sibling.

<div id="box">Main content</div>

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

box.insertAdjacentHTML(
    "beforebegin",
    "<p>This paragraph is before the box.</p>"
);
</script>

Resulting HTML:

<p>This paragraph is before the box.</p>
<div id="box">Main content</div>

JavaScript insertAdjacentHTML() with afterbegin

The afterbegin position inserts HTML as the first child inside the selected element.

<div id="box">
    <p>Existing paragraph</p>
</div>

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

box.insertAdjacentHTML(
    "afterbegin",
    "<h2>New heading</h2>"
);
</script>

The new heading appears before the existing paragraph inside the box element.

JavaScript insertAdjacentHTML() with beforeend

The beforeend position inserts HTML as the last child inside the selected element. It is commonly used to add content to the end of a list or container.

<ul id="items">
    <li>First item</li>
</ul>

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

items.insertAdjacentHTML(
    "beforeend",
    "<li>Second item</li>"
);
</script>

The new list item is added after the existing item.

JavaScript insertAdjacentHTML() with afterend

The afterend position inserts HTML immediately after the selected element, as a sibling.

<div id="box">Main content</div>

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

box.insertAdjacentHTML(
    "afterend",
    "<p>This paragraph is after the box.</p>"
);
</script>

The paragraph is placed outside the box element, immediately after it.

JavaScript insertAdjacentHTML() Example with a Dynamic List

You can use insertAdjacentHTML() to add list items dynamically when a user performs an action.

<ul id="todoList">
    <li>Learn HTML</li>
</ul>

<button id="addButton">Add Task</button>

<script>
const todoList = document.getElementById("todoList");
const addButton = document.getElementById("addButton");

addButton.addEventListener("click", function () {
    todoList.insertAdjacentHTML(
        "beforeend",
        "<li>Learn JavaScript</li>"
    );
});
</script>

Each time the button is clicked, a new list item is appended to the end of the list.

JavaScript insertAdjacentHTML() vs innerHTML

Both insertAdjacentHTML() and innerHTML can parse HTML strings, but they behave differently.

When you only need to insert markup without rebuilding an element’s existing children, insertAdjacentHTML() is often a more suitable choice.

Security Considerations When Using insertAdjacentHTML()

The insertAdjacentHTML() method parses the supplied string as HTML. If that string contains untrusted user input, an attacker may be able to inject harmful markup or script-capable content. This can lead to cross-site scripting (XSS) vulnerabilities.

Do not concatenate raw user input into an HTML string. Prefer creating elements with document.createElement() and assigning untrusted text through textContent.

const message = document.createElement("p");
message.textContent = userProvidedText;

document.getElementById("output").append(message);

For applications that must insert HTML from untrusted sources, use a well-maintained HTML sanitizer and consider Trusted Types where supported. Only insert HTML that your application has safely validated.

Browser Support for JavaScript insertAdjacentHTML()

The insertAdjacentHTML() method is supported by modern major browsers. It is part of the DOM API and is widely available in current versions of Chrome, Firefox, Safari, and Edge.

For compatibility with older environments, check the target browser requirements before relying on newer security features such as Trusted Types.