HTML Node insertAdjacentText() Method: Inserting Adjacent Text

The insertAdjacentText() method in the HTML DOM is a powerful tool for inserting text content relative to a specified element. Unlike methods that directly modify the inner HTML of an element, insertAdjacentText() allows you to insert text before or after an element, or as the first or last child of an element, without re-parsing the existing HTML structure. This makes it more efficient and less prone to causing unintended side effects. This comprehensive guide will cover the syntax, usage, and practical examples of the insertAdjacentText() method.

What is insertAdjacentText()?

The insertAdjacentText() method inserts a text node into the DOM tree at a specified position relative to a given element. It’s particularly useful when you need to add text content without disrupting the existing HTML structure or incurring the performance overhead of re-parsing HTML.

Purpose of insertAdjacentText()

The primary purpose of insertAdjacentText() is to provide a way to insert plain text into the DOM, offering precise control over the insertion point. This is particularly valuable in scenarios such as:

• Adding informational messages before or after specific elements.
• Appending log entries or status updates to a designated container.
• Injecting text-based annotations or comments into a document.

Syntax of insertAdjacentText()

The insertAdjacentText() method accepts two arguments: the position where the text should be inserted and the text string itself.

element.insertAdjacentText(position, text);

Parameters

Parameter	Type	Description
`position`	String	A string representing the position relative to the element where the text should be inserted. Possible values are: `’beforebegin’`: Before the element itself. `’afterbegin’`: Inside the element, before its first child. `’beforeend’`: Inside the element, after its last child. `’afterend’`: After the element itself.
`text`	String	The text string to be inserted.

Note: The position string must be one of the four valid options ('beforebegin', 'afterbegin', 'beforeend', 'afterend'). Using an invalid position will cause an INVALID_STATE_ERR exception. ⚠️

Examples of Using insertAdjacentText()

Let’s explore some examples of how to use the insertAdjacentText() method to insert text in different positions relative to an element.

Inserting Text Before an Element

The 'beforebegin' position inserts the text immediately before the element.

<div id="targetElementBefore">This is the target element.</div>

<script>
  const targetElementBefore_script = document.getElementById("targetElementBefore");
  targetElementBefore_script.insertAdjacentText("beforebegin", "Text inserted before. ");
</script>

Output:

Text inserted before. <div id="targetElementBefore">This is the target element.</div>

Inserting Text After an Element

The 'afterend' position inserts the text immediately after the element.

<div id="targetElementAfter">This is the target element.</div>

<script>
  const targetElementAfter_script = document.getElementById("targetElementAfter");
  targetElementAfter_script.insertAdjacentText("afterend", " Text inserted after.");
</script>

Output:

<div id="targetElementAfter">This is the target element.</div> Text inserted after.

Inserting Text as the First Child

The 'afterbegin' position inserts the text as the first child of the element.

<div id="targetElementFirstChild">This is the target element.</div>

<script>
  const targetElementFirstChild_script = document.getElementById("targetElementFirstChild");
  targetElementFirstChild_script.insertAdjacentText("afterbegin", "Text inserted as the first child. ");
</script>

Output:

<div id="targetElementFirstChild">Text inserted as the first child. This is the target element.</div>

Inserting Text as the Last Child

The 'beforeend' position inserts the text as the last child of the element.

<div id="targetElementLastChild">This is the target element.</div>

<script>
  const targetElementLastChild_script = document.getElementById("targetElementLastChild");
  targetElementLastChild_script.insertAdjacentText("beforeend", " Text inserted as the last child.");
</script>

Output:

<div id="targetElementLastChild">This is the target element. Text inserted as the last child.</div>

Example: Adding Log Entries to a Container

This example demonstrates how to use insertAdjacentText() to add log entries to a container element.

<div id="logContainer">
  <h3>Log:</h3>
</div>

<button id="addLogButton">Add Log Entry</button>

<script>
  const logContainer_script = document.getElementById("logContainer");
  const addLogButton_script = document.getElementById("addLogButton");

  addLogButton_script.addEventListener("click", () => {
    const newLogEntry = `Log entry added at ${new Date().toLocaleTimeString()}`;
    logContainer_script.insertAdjacentText("beforeend", newLogEntry + "\n");
  });
</script>

In this example, clicking the “Add Log Entry” button appends a new log entry, including the current time, to the logContainer element. The \n adds a newline character, ensuring each log entry appears on a new line.

Example: Displaying Notifications

This example demonstrates how to display notifications using insertAdjacentText().

<div id="notificationContainer">
  <h3>Notifications:</h3>
</div>

<button id="addNotificationButton">Add Notification</button>

<script>
  const notificationContainer_script = document.getElementById("notificationContainer");
  const addNotificationButton_script = document.getElementById("addNotificationButton");

  addNotificationButton_script.addEventListener("click", () => {
    const newNotification = `New notification at ${new Date().toLocaleTimeString()}`;
    notificationContainer_script.insertAdjacentText("afterbegin", newNotification + "<br>");
  });
</script>

In this case, clicking the “Add Notification” button inserts a new notification at the top of the notificationContainer element. The <br> tag ensures each notification appears on a new line within the HTML structure. Note that we are inserting plain text, so any HTML needs to be represented as text. If we wanted to inject valid HTML, then we could use insertAdjacentHTML() method.

Real-World Applications of insertAdjacentText()

The insertAdjacentText() method is particularly useful in scenarios such as:

• Dynamic Content Updates: Updating sections of a webpage with new information without disrupting the existing HTML structure.
• Logging and Debugging: Displaying log messages or debugging information in a designated area of the page.
• User Interface Enhancements: Adding tooltips, hints, or other contextual information to elements.
• Accessibility: Providing alternative text descriptions for elements, improving accessibility for users with disabilities.

Best Practices

• Use Valid Positions: Ensure that the position string is always one of the four valid options: 'beforebegin', 'afterbegin', 'beforeend', or 'afterend'.
• Sanitize Input: If the text being inserted comes from user input or an external source, sanitize it to prevent cross-site scripting (XSS) vulnerabilities.
• Consider Performance: While insertAdjacentText() is generally efficient, avoid excessive use in performance-critical sections of your code.

Browser Support

The insertAdjacentText() method enjoys excellent support across all modern web browsers, ensuring consistent behavior across different platforms.

Conclusion

The insertAdjacentText() method is a valuable tool for inserting text content into the DOM with precision and efficiency. By understanding its syntax, usage, and practical applications, you can effectively leverage this method to enhance the functionality and user experience of your web applications.