HTML Node compareDocumentPosition() Method: Comparing Node Positions

HTML Node compareDocumentPosition() Method: Comparing Node Positions

The compareDocumentPosition() method is a powerful tool in the Document Object Model (DOM) that allows you to determine the relationship between two nodes in an HTML document. It returns a bitmask value indicating how the nodes are positioned relative to each other. This method is particularly useful for tasks such as validating document structure, implementing custom sorting algorithms, or handling dynamic content updates.

What is the compareDocumentPosition() Method?

The compareDocumentPosition() method is a function available on all Node objects in the DOM. It compares the position of the node on which it is called (the reference node) with another node (the argument node) and returns a numerical value that represents their relationship.

Purpose of the compareDocumentPosition() Method

The primary purpose of the compareDocumentPosition() method is to:

• Determine if one node is contained within another.
• Check if two nodes are in different documents.
• Ascertain if one node precedes or follows another in the document order.
• Verify if two nodes are identical.

Syntax

The syntax for using the compareDocumentPosition() method is straightforward:

node.compareDocumentPosition(otherNode);

• node: The reference node. This is the node from which the method is called.
• otherNode: The node to compare against the reference node.

Return Values

The compareDocumentPosition() method returns a bitmask representing the relationship between the two nodes. You can check for specific relationships using bitwise operators. The possible return values and their meanings are:

Constant	Value	Description
`Node.DOCUMENT_POSITION_DISCONNECTED`	1	The nodes are in different documents or are disconnected.
`Node.DOCUMENT_POSITION_PRECEDING`	2	The reference node precedes the other node.
`Node.DOCUMENT_POSITION_FOLLOWING`	4	The reference node follows the other node.
`Node.DOCUMENT_POSITION_CONTAINS`	8	The reference node contains the other node.
`Node.DOCUMENT_POSITION_CONTAINED_BY`	16	The reference node is contained by the other node.
`Node.DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC`	32	The result is implementation-specific.
`0`	0	The two nodes are the same.

To check for a specific relationship, use bitwise AND (&) to compare the return value with the constant. For example:

const result = nodeA.compareDocumentPosition(nodeB);

if (result & Node.DOCUMENT_POSITION_CONTAINS) {
  console.log("nodeA contains nodeB");
}

if (result & Node.DOCUMENT_POSITION_FOLLOWING) {
  console.log("nodeA follows nodeB");
}

Examples

Let’s explore some practical examples of using the compareDocumentPosition() method to understand how it works in different scenarios.

Basic Node Comparison

In this example, we compare the positions of two <div> elements within the same document.

<div id="container_1">
  <div id="nodeA_1">Node A</div>
  <div id="nodeB_1">Node B</div>
</div>

<script>
  const container_el_1 = document.getElementById("container_1");
  const nodeA_el_1 = document.getElementById("nodeA_1");
  const nodeB_el_1 = document.getElementById("nodeB_1");

  const comparisonResult_1 = nodeA_el_1.compareDocumentPosition(nodeB_el_1);

  if (comparisonResult_1 & Node.DOCUMENT_POSITION_FOLLOWING) {
    console.log("Node A follows Node B");
  }
  if (comparisonResult_1 & Node.DOCUMENT_POSITION_PRECEDING) {
    console.log("Node A precedes Node B");
  }
</script>

In this case, “Node A precedes Node B” will be printed to the console because nodeA_el_1 appears before nodeB_el_1 in the document order.

Checking Containment

Here, we check if one node contains another.

<div id="container_2">
  <div id="nodeA_2">
    Node A
    <div id="nodeB_2">Node B</div>
  </div>
</div>

<script>
  const container_el_2 = document.getElementById("container_2");
  const nodeA_el_2 = document.getElementById("nodeA_2");
  const nodeB_el_2 = document.getElementById("nodeB_2");

  const comparisonResult_2 = nodeA_el_2.compareDocumentPosition(nodeB_el_2);

  if (comparisonResult_2 & Node.DOCUMENT_POSITION_CONTAINS) {
    console.log("Node A contains Node B");
  }
  if (comparisonResult_2 & Node.DOCUMENT_POSITION_CONTAINED_BY) {
    console.log("Node A is contained by Node B");
  }
</script>

The output will be “Node A contains Node B” because nodeB_el_2 is a child of nodeA_el_2.

Disconnected Nodes

This example demonstrates comparing nodes that are not connected in the document.

<div id="nodeA_3">Node A</div>
<div id="nodeB_3">Node B</div>

<script>
  const nodeA_el_3 = document.getElementById("nodeA_3");
  const nodeB_el_3 = document.getElementById("nodeB_3");

  const comparisonResult_3 = nodeA_el_3.compareDocumentPosition(nodeB_el_3);

  if (comparisonResult_3 & Node.DOCUMENT_POSITION_DISCONNECTED) {
    console.log("Node A and Node B are disconnected");
  }
</script>

The console will display “Node A and Node B are disconnected” since the nodes are siblings but not contained within each other.

Comparing Nodes in Different Documents

This example shows how compareDocumentPosition() behaves when comparing nodes from different documents.

<iframe id="frame_1" src="about:blank"></iframe>

<script>
  const frame_el = document.getElementById("frame_1");
  const frameDocument = frame_el.contentDocument || frame_el.contentWindow.document;

  const nodeA_el_4 = document.createElement("div");
  nodeA_el_4.textContent = "Node A";
  document.body.appendChild(nodeA_el_4);

  const nodeB_el_4 = frameDocument.createElement("div");
  nodeB_el_4.textContent = "Node B";
  frameDocument.body.appendChild(nodeB_el_4);

  const comparisonResult_4 = nodeA_el_4.compareDocumentPosition(nodeB_el_4);

  if (comparisonResult_4 & Node.DOCUMENT_POSITION_DISCONNECTED) {
    console.log("Node A and Node B are in different documents");
  }
</script>

The output will be “Node A and Node B are in different documents” because the nodes belong to different DOM trees.

Use Case: Validating Document Structure

One practical application of compareDocumentPosition() is to validate the structure of an HTML document programmatically.

<div id="container_5">
  <header id="header_5">Header</header>
  <main id="main_5">Main Content</main>
  <footer id="footer_5">Footer</footer>
</div>

<script>
  const container_el_5 = document.getElementById("container_5");
  const header_el_5 = document.getElementById("header_5");
  const main_el_5 = document.getElementById("main_5");
  const footer_el_5 = document.getElementById("footer_5");

  function validateStructure(container, header, main, footer) {
    if (
      !(container.compareDocumentPosition(header) & Node.DOCUMENT_POSITION_CONTAINS) ||
      !(container.compareDocumentPosition(main) & Node.DOCUMENT_POSITION_CONTAINS) ||
      !(container.compareDocumentPosition(footer) & Node.DOCUMENT_POSITION_CONTAINS)
    ) {
      console.error("Structure Validation Failed: Elements are not within the container.");
      return false;
    }

    if (
      !(header.compareDocumentPosition(main) & Node.DOCUMENT_POSITION_PRECEDING) ||
      !(main.compareDocumentPosition(footer) & Node.DOCUMENT_POSITION_PRECEDING)
    ) {
      console.error("Structure Validation Failed: Incorrect element order.");
      return false;
    }

    console.log("Document structure is valid.");
    return true;
  }

  validateStructure(container_el_5, header_el_5, main_el_5, footer_el_5);
</script>

This code validates that the header, main, and footer elements are contained within the container and that they appear in the correct order.

Tips and Notes

• Always use bitwise operators (&) to check for specific relationships, as the return value can be a combination of multiple flags. 💡
• Be aware that the method returns 0 if the nodes are the same. ⚠️
• When comparing nodes in different documents or disconnected nodes, the DOCUMENT_POSITION_DISCONNECTED flag will always be present. 📝
• This method is particularly useful when working with dynamically generated or modified DOM structures. ✅

Browser Support

The compareDocumentPosition() method is widely supported across all modern browsers, including:

• Chrome
• Firefox
• Safari
• Edge
• Opera

This broad support ensures that you can rely on this method in virtually any web development project.

Conclusion

The compareDocumentPosition() method is an invaluable tool for understanding and manipulating the structure of an HTML document. By providing a way to determine the relationship between nodes, it enables developers to create more robust and reliable web applications. Whether you’re validating document structure, implementing custom sorting algorithms, or handling dynamic content updates, compareDocumentPosition() is a method you’ll find yourself reaching for time and time again.