Anatomy of the DOM

The DOM represents an XML or HTML document as a tree. This page introduces the basic structure of the DOM tree and the various properties and methods used to navigate it.

To begin with, we need to introduce some concepts related to trees. A tree is a data structure made up of nodes. Each node holds some data. The nodes are organized in a hierarchical way—every node has a single parent node (except for the root node, which has no parent), and an ordered list of zero or more child nodes. Now we can define the following:

And here are a few important properties of trees:

The Node interface and its subclasses

All nodes in the DOM are represented by objects that implement the Node interface. The Node interface embodies many of the previously defined concepts:

You rarely work with plain Node objects—instead, all objects in the DOM implement one of the interfaces that inherit from Node, which represent additional semantics in the document. The node types restrict what data they contain, and what children types are valid. Consider how the following HTML document is represented in the DOM:

html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
  </head>
  <body>
    <h1>Hello, world!</h1>
    <p>This is a paragraph.</p>
  </body>
</html>

It produces the following DOM tree:

The DOM tree of the previous HTML document

The root of this DOM tree is a Document node, which represents the entire document. This node is exposed globally as the document variable. This node has two important child nodes:

The DocumentType node is always a leaf node. The Element node is where most of the document content is represented. Each element under it, such as <head>, <body>, and <p>, is also represented by an Element node. In fact, each is a subclass of Element specific to that tag name, defined in the HTML specification, such as HTMLHeadElement and HTMLBodyElement, with additional properties and methods to represent the semantics of that element, but here we focus on the common behaviors of the DOM. The Element nodes can have other Element nodes as children, representing nested elements. For example, the <head> element has three children: two <meta> elements and a <title> element. Additionally, elements can also have Text nodes and CDATASection nodes as children, representing text content. For example, the <p> element has a single child, a Text node containing the string "This is a paragraph.". Text nodes and CDATASection nodes are always leaf nodes.

All nodes that can have children (Document, DocumentFragment, and Element) allow two types of children: Comment and ProcessingInstruction nodes. These nodes are always leaf nodes.

Each element, in addition to having child nodes, can also have attributes, represented as Attr nodes. Attr extend the Node interface, but they are not part of the main tree structure, because they are not the child of any node and their parent node is null. Instead, they are stored in a separate named node map, accessible via the attributes property of the Element node.

The Node interface defines a nodeType property that indicates the type of the node. To summarize, we introduced the following node types:

Node typenodeType valueValid children (besides Comment and ProcessingInstruction)
DocumentNode.DOCUMENT_NODE (9)DocumentType, Element
DocumentTypeNode.DOCUMENT_TYPE_NODE (10)None
ElementNode.ELEMENT_NODE (1)Element, Text, CDATASection
TextNode.TEXT_NODE (3)None
CDATASectionNode.CDATA_SECTION_NODE (4)None
CommentNode.COMMENT_NODE (8)None
ProcessingInstructionNode.PROCESSING_INSTRUCTION_NODE (7)None
AttrNode.ATTRIBUTE_NODE (2)None

Note: You may notice we skipped some node types here. The Node.ENTITY_REFERENCE_NODE (5), Node.ENTITY_NODE (6), and Node.NOTATION_NODE (12) values are no longer used, while the Node.DOCUMENT_FRAGMENT_NODE (11) value will be introduced in Building and updating the DOM tree.

Data of each node

Each node type has its own way of representing the data it holds. The Node interface itself defines three properties related to data, summarized in the following table:

Node typenodeNamenodeValuetextContent
Document"#document"nullnull
DocumentTypeIts name (e.g., "html")nullnull
ElementIts tagName (e.g., "HTML", "BODY")nullConcatenation of all its text node descendants in tree order
Text"#text"Its dataIts data
CDATASection"#cdata-section"Its dataIts data
Comment"#comment"Its dataIts data
ProcessingInstructionIts targetIts dataIts data
AttrIts nameIts valueIts value

Document

The Document node does not hold any data itself, so its nodeValue and textContent are always null. Its nodeName is always "#document".

The Document does define some metadata about the document, coming from the environment (for example, the HTTP response that served the document):

DocumentType

A DocumentType in the document looks like this:

xml
<!doctype name PUBLIC "publicId" "systemId">

There are three parts you can specify, which correspond to the three properties of the DocumentType node: name, publicId, and systemId. For HTML documents, the doctype is always <!doctype html>, so the name is "html" and both publicId and systemId are empty strings.

Element

An Element in the document looks like this:

html
<p class="note" id="intro">This is a paragraph.</p>

In addition to the contents, there are two parts you can specify: the tag name and the attributes. The tag name corresponds to the tagName property of the Element node, which is "P" in this case (note that it is always in uppercase for HTML elements). The attributes correspond to the Attr nodes stored in the attributes property of the Element node. We will discuss attributes in more detail in the Element and its attributes section.

The Element node does not hold any data itself, so its nodeValue is always null. Its textContent is the concatenation of all its text node descendants in tree order, which is "This is a paragraph." in this case. For the following element:

html
<div>Hello, <span>world</span>!</div>

The textContent is "Hello, world!", concatenating the text node "Hello, ", the text node "world" inside the <span> element, and the text node "!".

CharacterData

Text, CDATASection, Comment, and ProcessingInstruction all inherit from the CharacterData interface, which is a subclass of Node. The CharacterData interface defines a single property, data, which holds the text content of the node. The data property is also used to implement the nodeValue and textContent properties of these nodes.

For Text and CDATASection, the data property holds the text content of the node. In the following document (note that we use an SVG document, because HTML does not allow CDATA sections):

svg
<text>Some text</text>
<style><![CDATA[h1 { color: red; }]]></style>

The text node inside the <text> element has "Some text" as data, and the CDATA section inside the <style> element has "h1 { color: red; }" as data.

For Comment, the data property holds the content of the comment, starting after the <!-- and ending before the -->. For example, in the following document:

html
<!-- This is a comment -->

The comment node has " This is a comment " as data.

For ProcessingInstruction, the data property holds the content of the processing instruction, starting after the target and ending before the ?>. For example, in the following document:

xml
<?xml-stylesheet type="text/xsl" href="style.xsl"?>

The processing instruction node has 'type="text/xsl" href="style.xsl"' as data, and "xml-stylesheet" as its target.

In addition, the CharacterData interface defines the length property, which returns the length of the data string, and the substringData() method, which returns a substring of the data.

Attr

For the following element:

html
<p class="note" id="intro">This is a paragraph.</p>

The <p> element has two attributes, represented by two Attr nodes. Each attribute consists of a name and a value, corresponding to the name and value properties. The first attribute has "class" as name and "note" as value, while the second attribute has "id" as name and "intro" as value.

Element and its attributes

As previously mentioned, the attributes of an Element node are represented by Attr nodes, which are stored in a separate named node map, accessible via the attributes property of the Element node. This NamedNodeMap interface defines three important properties:

The Element interface also defines several methods to work with attributes directly, without needing to access the named node map:

You can also access the owner element of an attribute via the ownerElement property of the Attr node.

There are two special attributes, id and class, which have their own properties on the Element interface: id and className, that reflect the value of the corresponding attribute. In addition, the classList property returns a DOMTokenList representing the list of classes in the class attribute.

Working with the element tree

Because Element nodes form the backbone of the document structure, you can specifically traverse the element nodes, skipping other nodes (such as Text and Comment).

Comparing nodes

There are three important methods that compare nodes: isEqualNode(), isSameNode(), compareDocumentPosition().

The isSameNode() method is legacy. Now, it behaves like the strict equality operator (===), returning true if and only if the two nodes are the same object.

The isEqualNode() method compares two nodes structurally. Two nodes are considered equal if they have the same type, the same data, and their child nodes are also equal at each index. In the Data of each node section, we already defined the data relevant for each node type:

The a.compareDocumentPosition(b) method compares two nodes by tree order. It returns a bitmask indicating their relative positions. The possible cases are:

Bitmask values are used, so you can use a bitwise AND operation to check for specific relationships. For example, to check if a precedes b, you can do:

js
if (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_PRECEDING) {
  // a precedes b
}

Which accounts for the cases of a and b being attributes of the same element, a being an ancestor of b, and a preceding b in tree order.

Summary

Here are all the features we've introduced so far. There are a lot, but they are all useful in different scenarios.