Appending and Inserting in Javascript

Sept 2021

This post also lives over at CSS Tricks

Let’s say we want to add something to a webpage after the initial load. JavaScript gives us a variety of tools. Perhaps you’ve used some of them, like append, appendChild, insertAdjacentHTML, or innerHTML.

The difficult thing about appending and inserting things with JavaScript isn’t so much about the tools it offers, but which one to use, when to use them, and understanding how each one works.

Let’s try to clear things up.

Quick Context

Your browser converts the HTML tags inside your HTML file into a bunch of objects that can be manipulated with JavaScript. These objects construct a Document Object Model (DOM) tree. This tree is a series of objects that are structured as parent-child relationships.

In DOM parlance, these objects are called nodes, or more specifically, HTML elements.

<!-- I'm the parent element -->
<div>
  <!-- I'm a child element -->
  <span>Hello</span>
</div>

In this example, the HTML span element is the child of the div element, which is the parent.

And I know that some of these terms are weird and possibly confusing. We say “node”, but other times we may say “element” or “object” instead. And, in some cases, they refer to the same thing, just depending on how specific we want to be .

For example, an “element” is a specific type of “node”, just like an apple is a specific type of fruit.

We can organize these terms from most general, to most specific: Object → Node → Element → HTML Element

Understanding these DOM items is important, as we’ll interact with them to add and append things with JavaScript after an initial page load. In fact, let’s start working on that.

Setup

These append and insert methods mostly follow this pattern:

Element.append_method_choice(stuff_to_append)

Again, an element is merely an object in the DOM Tree that represents some HTML. Earlier, we had mentioned that the purpose of the DOM tree is to give us a convenient way to interact with HTML using JavaScript.

So, how do we use JavaScript to grab an HTML element?

Querying the DOM

Let’s say we have the following tiny bit of HTML:

<div id="example" class="group">
  Hello World
</div>

There are a few common ways to query the DOM:

// Query a specific selector (could be class, ID, element type, or attribute):
const my_element1 = document.querySelector('#example')

// Query an element by its ID:
const my_element2 = document.getElementbyId('example')

// Query an element by its class:
const my_element3 = document.getElementbyClass('group')[0]

In this example, all three lines query the same thing, but look for it in different ways. One looks at any of the item’s CSS selectors; one looks at the item’s ID; and one looks at the item’s class.

Note that the getElementbyClass method returns an array. That’s because it’s capable of matching multiple elements in the DOM and storing those matches in an array makes sure all of them are accounted for.

What we can append and insert

// Append Something
const my_element1 = document.querySelector('#example')
my_element1.append(something)

In this example, something is a parameter that represents stuff we want to tack on to the end of (i.e. append to) the matched element.

We can’t just append any old thing to any old object. The append method only allows us to append either a node or plain text to an element in the DOM. But some other methods can append HTML to DOM elements as well.

1. Nodes are either created with document.createElement() in JavaScript, or they are selected with one of the query methods we looked at in the last section.

2. Plain text is, well, text. It’s plain text in that it does not carry any HTML tags or formatting with it. (e.g. Hello).

3. HTML is also text but, unlike plain text, it does indeed get parsed as markup when it’s added to the DOM (e.g. <div>Hello</div>).

It might help to map out exactly which parameters are supported by which methods:

How to choose which method to use

Well, it really depends on what you’re looking to append, not to mention certain browser quirks to work around.

• If you have existing HTML that gets sent to your JavaScript, it's probably easiest to work with methods that support HTML.
• If you're building some new HTML in JavasScript, creating a node with heavy markup can be cumbersome, whereas HTML is less verbose.
• If you want to attach event listeners right away, you'll want to work with nodes because we call addEventListener on nodes, not HTML.
• If all you need is text, any method supporting plain text parameters is fine.
• If your HTML is potentially untrustworthy (i.e. it comes from user input, say a comment on a blog post), then you’ll want to be careful when using HTML, unless it has been sanitized (i.e. the harmful code has been removed).
• If you need to support Internet Explorer, then using append is out of the question.

Example

Let’s say we have a chat application, and we want to append a user, Dale, to a buddy list when they log in.

<!-- HTML Buddy List -->
<ul id="buddies">
  <li><a>Alex</a></li>
  <li><a>Barry</a></li>
  <li><a>Clive</a></li>
  <!-- Append next user here -->
</ul>

Here’s how we’d accomplish this using each of the methods above.

append

We need to create a node object that translates to <li><a>Dale</a></li>.

const new_buddy = document.createElement('li')
const new_link = document.createElement('a')

const buddy_name = "Dale"

new_link.append(buddy_name) // Text param
new_buddy.append(new_link) // Node param

const list = document.querySelector('#buddies')
list.append(new_buddy) // Node param

Our final append places the new user at the end of the buddy list, just before the closing </ul> tag. If we’d prefer to place the user at the front of the list, we could use the prepend method instead.

You may have noticed that we were also able to use append to fill our <a> tag with text like this:

const buddy_name = "Dale"
new_link.append(buddy_name) // Text param

This highlights the versatility of append.

And just to call it out once more, append is unsupported in Internet Explorer.

appendChild

appendChild is another JavaScript method we have for appending stuff to DOM elements. It’s a little limited in that it only works with node objects, so we we’ll need some help from textContent (or innerText) for our plain text needs.

const new_buddy = document.createElement('li')
const new_link = document.createElement('a')

const buddy_name = "Dale"

new_link.textContent = buddy_name
new_buddy.appendChild(new_link) // Node param

const list = document.querySelector('#buddies')
list.appendChild(new_buddy) // Node param

Note that appendChild, unlike append, is supported in Internet Explorer.

Before moving on, let’s consider a similar example, but with heavier markup.

Let’s say the HTML we wanted to append didn’t look like <li><a>Dale</a></li>, but rather:

<li class="abc" data-tooltip="Click for Dale">
  <a id="user_123" class="def" data-user="dale">
    <img src="images/dale.jpg" alt="Profile Picture"/>
    <span>Dale</span>
  </a>
</li>

Our JavaScript would look something like:

const buddy_name = "Dale"

const new_buddy = document.createElement('li')
new_buddy.className = ('abc')
new_buddy.setAttribute('data-tooltip', `Click for ${buddy_name}`)

const new_link = document.createElement('a')
new_link.id = 'user_123'
new_link.className = ('def')
new_link.setAttribute('data-user', buddy_name)

const new_profile_img = document.createElement('img')
new_profile_img.src = 'images/dale.jpg'
new_profile_img.alt = 'Profile Picture'

const new_buddy_span = document.createElement('span')
new_buddy_span.textContent = buddy_name

new_link.appendChild(new_profile_img) // Node param
new_link.appendChild(new_buddy_span) // Node param
new_buddy.appendChild(new_link) // Node param

const list = document.querySelector('#buddies')
list.appendChild(new_buddy) // Node param

There’s no need to follow all of above JavaScript – the point is that creating large amounts of HTML in JavaScript can become quite cumbersome. And there’s no getting around this if we use append or appendChild.

In this heavy markup scenario, it might be nice to just write our HTML as a string, rather than using a bunch of JavaScript methods…

insertAdjacentHTML

insertAdjacentHTML is is like append in that it’s also capable of adding stuff to DOM elements. One difference, though, is that insertAdjacentHTML inserts that stuff at a specific position relative to the matched element.

And it just so happens to work with HTML. That means we can insert actual HTML to a DOM element, and pinpoint exactly where we want it with four different positions:

<!-- beforebegin -->
<div id="example" class="group">
  <!-- afterbegin -->
  Hello World
  <!-- beforeend -->
</div>
<!-- afterend -->

So, we can sorta replicate the same idea of “appending” our HTML by inserting it at the beforeend position of the #buddies selector:

const buddy_name = "Dale"

const new_buddy = `<li><a>${buddy_name}</a></li>`
const list = document.querySelector('#buddies')
list.insertAdjacentHTML('beforeend', new_buddy)

Remember the security concerns we mentioned earlier. We never want to insert HTML that’s been submitted by an end user, as we’d open ourselves up to cross-site scripting vulnerabilities.

innerHTML

innerHTML is another method for inserting stuff. That said, it’s not recommended for inserting, as we’ll see.

Here’s our query and the HTML we want to insert:

const buddy_name = "Dale"
const new_buddy = `<li><a>${buddy_name}</a></li>`
const list = document.querySelector('#buddies')  
list.innerHTML += new_buddy

Initially, this seems to work. Our updated buddy list looks like this in the DOM:

<ul id="buddies">
  <li><a>Alex</a></li>
  <li><a>Barry</a></li>
  <li><a>Clive</a></li>
  <li><a>Dale</a></li>
</ul>

That’s what we want! But there’s a constraint with using innerHTML that prevents us from using event listeners on any element inside of #buddies because of the nature of += in list.innerHTML += new_buddy.

You see, A += B behaves the same as A = A + B. In this case, A is our existing HTML and B is what we’re inserting to it. The problem is that this results in a copy of the existing HTML with the additional inserted HTML. And event listeners are unable to listen to copies. That means if we want to listen for a click event on any of the <a> tags in the buddy list, we’re going to lose that ability with innerHTML.

So, just a word of caution there.

Demo

Here’s a demo that pulls together all of the methods we’ve covered. Clicking the button of each method inserts “Dale” as an item in the buddies list.

Recap

Here’s a general overview of where we stand when we’re appending and inserting stuff into the DOM. Consider it a cheatsheet for when you need help figuring out which method to use.

If I had to condense all of that into a few recommendations:

• Using innerHTML for appending is not recommended as it removes event listeners.

• append works well if you like the flexibility of working with node elements or plain text, and don’t need to support Internet Explorer.

• appendChild works well if you like (or need) to work with node elements, and want full browser coverage.

• insertAdjacentHTML is nice if you need to generate HTML, and want to more specific control over where it is placed in the DOM.