The getElementsByClassName() Method

One of HTML5's most popular additions is getElementsByClassName(), which is available on the document object and on all HTML elements. This method evolved out of JavaScript libraries that implemented it using existing DOM features and is provided as a native implementation for performance reasons.

The getElementsByClassName() method accepts a single argument, which is a string containing one or more class names, and returns a NodeList containing all elements that have all of the specified classes applied. If multiple class names are specified, then the order is considered unimportant. Here are some examples:

// Get all elements with a class containing "username" and "current"
// It does not matter if one is declared before the other
let allCurrentUsernames = document.getElementsByClassName("username current");
          
// Get all elements with a class of "selected" that exist in myDiv's subtree
let selected = document.getElementById("myDiv").getElementsByClassName("selected");

When this method is called, it will return only elements in the subtree of the root from which it was called. Calling getElementsByClassName() on document always returns all elements with matching class names, whereas calling it on an element will return only descendant elements.

This method is useful for attaching events to classes of elements rather than using IDs or tag names. Keep in mind that since the returned value is a NodeList, there are the same performance issues as when you're using getElementsByTagName() and other DOM methods that return NodeList objects.

The getElementsByClassName() method is implemented in Internet Explorer 9+ and all modern browsers.

The classList Property

In class name manipulation, the className property is used to add, remove, and replace class names. Because className contains a single string, it's necessary to set its value every time a change needs to take place, even if there are parts of the string that should be unaffected. For example, consider the following HTML code:

<div class="bd user disabled">…</div>

This <div> element has three classes assigned. To remove one of these classes, you need to split the class attribute into individual classes, remove the unwanted class, and then create a string containing the remaining classes. Here is an example:

// Remove the "user" class
let targetClass = "user";
          
// First, get list of class names
let classNames = div.className.split(/s+/);
          
// Find the class name to remove
let idx = classNames.indexOf(targetClass);
          
// Remove the class name if found
if (idx> -1) { 
 classNames.splice(i,1);
}
          
// Set back the class name
div.className = classNames.join(" ");

All of this code is necessary to remove the "user" class from the <div> element's class attribute. A similar algorithm must be used for replacing class names and detecting if a class name is applied to an element. Adding class names can be done by using string concatenation, but checks must be done to ensure that you're not applying the same class more than one time. Many JavaScript libraries implement methods to aid in these behaviors.

HTML5 introduces a way to manipulate class names in a much simpler and safer manner through the addition of the classList property for all elements. The classList property is an instance of a new type of collection named DOMTokenList. As with other DOM collections, DOMTokenList has a length property to indicate how many items it contains, and individual items may be retrieved via the item() method or using bracket notation. It also has the following additional methods:

6. add(value )—Adds the given string value to the list. If the value already exists, it will not be added.
7. contains(value )—Indicates if the given value exists in the list (true if so; false if not).
8. remove(value )—Removes the given string value from the list.
9. toggle(value)—If the value already exists in the list, it is removed. If the value doesn't exist, then it's added.

The entire block of code in the previous example can quite simply be replaced with the following:

div.classList.remove("user");

Using this code ensures that the rest of the class names will be unaffected by the change. The other methods also greatly reduce the complexity of the basic operations, as shown in these examples:

// Remove the "disabled" class
div.classList.remove("disabled");
          
// Add the "current" class
div.classList.add("current");
          
// Toggle the "user" class
div.classList.toggle("user");
          
// Figure out what's on the element now
if (div.classList.contains("bd") && !div.classList.contains("disabled")){
 // Do stuff 
)
          
// Iterate over the class names
for (let class of div.classList){
 doStuff(class);
}

The addition of the classList property makes it unnecessary to access the className property unless you intend to completely remove or completely overwrite the element's class attribute. The classList property is implemented partially in Internet Explorer 10+ and fully in all other major browsers.

The readyState Property

Internet Explorer 4 was the first to introduce a readyState property on the document object, and it is supported by all modern browsers. Other browsers then followed suit and this property was eventually formalized in HTML5. The readyState property for document has two possible values:

10. loading—The document is loading.
11. complete—The document is completely loaded.

The best way to use the document.readyState property is as an indicator that the document has loaded. Before this property was widely available, you would need to add an onload event handler to set a flag indicating that the document was loaded. Basic usage:

if (document.readyState == "complete"){
 // Do stuff
}

Compatibility Mode

With the introduction of Internet Explorer 6 and the ability to render a document in either standards or quirks mode, it became necessary to determine in which mode the browser was rendering the page. Internet Explorer added a property on the document named compatMode whose sole job is to indicate what rendering mode the browser is in. As shown in the following example, when in standards mode, document.compatMode is equal to "CSS1Compat"; when in quirks mode, document.compatMode is "BackCompat":

if (document.compatMode == "CSS1Compat"){
  console.log("Standards mode");
} else {
  console.log("Quirks mode");
}

The compatMode property was added to HTML5 to formalize its implementation.

The head Property

HTML5 introduces document.head to point to the <head> element of a document to complement document.body, which points to the <body> element of the document. You can retrieve a reference to the <head> element using this property:

let head = document.head;

The innerHTML Property

When used in read mode, innerHTML returns the HTML representing all of the child nodes, including elements, comments, and text nodes. When used in write mode, innerHTML completely replaces all of the child nodes in the element with a new DOM subtree based on the specified value. Consider the following HTML code:

<div id="content">
 <p>This is a <strong>paragraph</strong> with a list following it.</p>
 <ul>
  <li>Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
 </ul>
</div>

For the <div> element in this example, the innerHTML property returns the following string:

<p>This is a <strong>paragraph</strong> with a list following it.</p>
<ul>
 <li>Item 1</li>
 <li>Item 2</li>
 <li>Item 3</li>
</ul>

The exact text returned from innerHTML differs from browser to browser. Internet Explorer and Opera tend to convert all tags to uppercase, whereas Safari, Chrome, and Firefox return HTML in the way it is specified in the document, including white space and indentation. You cannot depend on the returned value of innerHTML being exactly the same from browser to browser.

When used in write mode, innerHTML parses the given string into a DOM subtree and replaces all of the existing child nodes with it. Because the string is considered to be HTML, all tags are converted into elements in the standard way that the browser handles HTML (again, this differs from browser to browser). Setting simple text without any HTML tags, as shown here, sets the plain text:

div.innerHTML = "Hello world!"; 

Setting innerHTML to a string containing HTML behaves quite differently as innerHTML parses them. Consider the following example:

div.innerHTML = "Hello & welcome, <b>"reader"!</b>";

The result of this operation is as follows:

<div id="content">Hello & welcome, <b>"reader"!</b></div>

After setting innerHTML, you can access the newly created nodes as you would any other nodes in the document.

Using innerHTML in Legacy Internet Explorer

<script> elements cannot be executed when inserted via innerHTML in all modern browsers. Internet Explorer 8 and earlier, is the only browser that allows this but only as long as the defer attribute is specified and the <script> element is preceded by what Microsoft calls a scoped element. The <script> element is considered a NoScope element, which effectively means that it has no visual representation on the page, like a <style> element or a comment. Internet Explorer strips out all NoScope elements from the beginning of strings inserted via innerHTML, which means the following won't work:

// Won't work
div.innerHTML = "<script defer>console.log('hi');</script>";

In this case, the innerHTML string begins with a NoScope element, so the entire string becomes empty. To allow this script to work appropriately, you must precede it with a scoped element, such as a text node or an element without a closing tag such as <input>. The following lines will all work:

// All these will work
div.innerHTML = "_<script defer>console.log('hi');</script>";
div.innerHTML = "<div> </div><script defer>console.log('hi');</script>";
div.innerHTML = "<input type="hidden"><script defer>console.log('hi');</script>";

The first line results in a text node being inserted immediately before the <script> element. You may need to remove this after the fact so as not to disrupt the flow of the page. The second line has a similar approach, using a <div> element with a nonbreaking space. An empty <div> alone won't do the trick; it must contain some content that will force a text node to be created. Once again, the first node may need to be removed to avoid layout issues. The third line uses a hidden <input> field to accomplish the same thing. Because it doesn't affect the layout of the page, this may be the optimal case for most situations.

In most browsers, the <style> element causes similar problems with innerHTML. Most browsers support the insertion of <style> elements using innerHTML in the exact way you'd expect, as shown here:

div.innerHTML = "<style type="text/css">body {background-color: red; }</style>";

In Internet Explorer 8 and earlier, <style> is yet another NoScope element, so it must be preceded by a scoped element such as this:

div.innerHTML = "_<style type="text/css">body {background-color: red; }</style>";
div.removeChild(div.firstChild);

The outerHTML Property

When outerHTML is called in read mode, it returns the HTML of the element on which it is called, as well as its child nodes. When called in write mode, outerHTML replaces the node on which it is called with the DOM subtree created from parsing the given HTML string. Consider the following HTML code:

<div id="content">
 <p>This is a <strong>paragraph</strong> with a list following it.</p>
 <ul>
  <li>Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
 </ul>
</div>

When outerHTML is called on the <div> in this example, the same code is returned, including the code for the <div>. Note that there may be differences based on how the browser parses and interprets the HTML code. (These are the same types of differences you'll notice when using innerHTML.)

Use outerHTML to set a value in the following manner:

div.outerHTML = "<p>This is a paragraph.</p>";

This code performs the same operation as the following DOM code:

let p = document.createElement("p");
p.appendChild(document.createTextNode("This is a paragraph."));
div.parentNode.replaceChild(p, div);

The new <p> element replaces the original <div> element in the DOM tree.

The insertAdjacentHTML() and insertAdjacentText() Methods

The last addition for markup insertion is the insertAdjacentHTML() and insertAdjacentText() methods. These methods also originated in Internet Explorer and accept two arguments: the position in which to insert and the HTML or text to insert. The first argument must be one of the following values:

12. "beforebegin"—Insert just before the element as a previous sibling.
13. "afterbegin"—Insert just inside of the element as a new child or series of children before the first child.
14. "beforeend"—Insert just inside of the element as a new child or series of children after the last child.
15. "afterend"—Insert just after the element as a next sibling.

Note that each of these values is case insensitive. The second argument is parsed as an HTML string (the same as with innerHTML/outerHTML) or as a raw string (the same as with innerText/outerText) and in the case of HTML, will throw an error if the value cannot be properly parsed. Basic usage is as follows:

// Insert as previous sibling
element.insertAdjacentHTML("beforebegin", "<p>Hello world!</p>");
element.insertAdjacentText("beforebegin", "Hello world!");

// Insert as first child
element.insertAdjacentHTML("afterbegin", "<p>Hello world!</p>");
element.insertAdjacentText("afterbegin", "Hello world!");

// Insert as last child
element.insertAdjacentHTML("beforeend", "<p>Hello world!</p>");
element.insertAdjacentText("beforeend", "Hello world!");

// Insert as next sibling
element.insertAdjacentHTML("afterend", "<p>Hello world!</p>"); element.insertAdjacentText("afterend", "Hello world!");

Memory and Performance Issues

Replacing child nodes using the methods in this section may cause memory problems in browsers, especially Internet Explorer. The problem occurs when event handlers or other JavaScript objects are assigned to subtree elements that are removed. If an element has an event handler (or a JavaScript object as a property), and one of these properties is used in such a way that the element is removed from the document tree, the binding between the element and the event handler remains in memory. If this is repeated frequently, memory usage increases for the page. When using innerHTML, outerHTML, and insertAdjacentHTML(), it's best to manually remove all event handlers and JavaScript object properties on elements that are going to be removed.

Using these properties does have an upside, especially when using innerHTML. Generally speaking, inserting a large amount of new HTML is more efficient through innerHTML than through multiple DOM operations to create nodes and assign relationships between them. This is because an HTML parser is created whenever a value is set to innerHTML (or outerHTML). This parser runs in browser-level code (often written in C++), which is must faster than JavaScript. That being said, the creation and destruction of the HTML parser does have some overhead, so it's best to limit the number of times you set innerHTML or outerHTML. For example, the following creates a number of list items using innerHTML:

for (let value of values){
 ul.innerHTML += '<li>${value}</li>'; // avoid!!
} 

This code is inefficient because it sets innerHTML once each time through the loop. Furthermore, this code is reading innerHTML each time through the loop, meaning that innerHTML is being accessed twice each time through the loop. It's best to build up the string separately and assign it using innerHTML just once at the end, like this:

let itemsHtml = "";
for (let value of values){
 itemsHtml += '<li>${value}</li>';
} 
ul.innerHTML = itemsHtml;

This example is more efficient, limiting the use of innerHTML to one assignment. Of course, if you wanted to condense it to a single line:

ul.innerHTML = values.map(value => '<li>${value}</li>').join('');

Cross-Site Scripting Considerations

Although innerHTML does not execute script tags that it creates, it still provides an extremely broad attack surface for malicious actors looking to compromise a web page because it so readily creates elements and executable attributes such as onclick.

Anywhere you are interpolating user-provided information into the page, it is nearly always inadvisable to do so using innerHTML. The headaches of preventing XSS vulnerabilities far outweigh any convenience benefits gained from using innerHTML. Compartmentalize interpolated data, and don't hesitate to use libraries that escape interpolated data before inserting them into the page.

The innerText Property

The innerText property works with all text content contained within an element, regardless of how deep in the subtree the text exists. When used to read the value, innerText concatenates the values of all text nodes in the subtree in depth-first order. When used to write the value, innerText removes all children of the element and inserts a text node containing the given value. Consider the following HTML code:

<div id="content">
 <p>This is a <strong>paragraph</strong> with a list following it.</p>
 <ul>
  <li>Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
 </ul>
</div>

For the <div> element in this example, the innerText property returns the following string:

This is a paragraph with a list following it.
Item 1
Item 2
Item 3

Note that different browsers treat white space in different ways, so the formatting may or may not include the indentation in the original HTML code.

Using the innerText property to set the contents of the <div> element is as simple as this single line of code:

div.innerText = "Hello world!"; 

After executing this line of code, the HTML of the page is effectively changed to the following:

<div id="content">Hello world!</div>

Setting innerText removes all of the child nodes that existed before, completely changing the DOM subtree. Additionally, setting innerText encodes all HTML syntax characters (less-than, greater-than, quotation marks, and ampersands) that may appear in the text. Here is an example:

div.innerText = "Hello & welcome, <b>"reader"!</b>";

The result of this operation is as follows:

<div id="content">Hello & welcome, <b>"reader"!</b></div>

Setting innerText can never result in anything other than a single text node as the child of the container, so the HTML-encoding of the text must take place in order to keep to that single text node. The innerText property is also useful for stripping out HTML tags. By setting the innerText equal to the innerText, as shown here, all HTML tags are removed:

div.innerText = div.innerText;

Executing this code replaces the contents of the container with just the text that exists already.

The outerText Property

The outerText property works in the same way as innerText except that it includes the node on which it's called. For reading text values, outerText and innerText essentially behave in the exact same way. In writing mode, however, outerText behaves very differently. Instead of replacing just the child nodes of the element on which it's used, outerText actually replaces the entire element, including its child nodes. Consider the following:

div.outerText = "Hello world!";

This single line of code is equivalent to the following two lines:

let text = document.createTextNode("Hello world!");
div.parentNode.replaceChild(text, div);

Essentially, the new text node completely replaces the element on which outerText was set. After that point in time, the element is no longer in the document and cannot be accessed.

The outerText property is nonstandard, and not on a standards track. It is not recommended that you rely on it for important behavior. It is supported in all modern browsers except for Firefox.