JavaScript Document evaluate() Method

What You’ll Learn

document.evaluate() is an instance method that runs an XPath expression and returns an XPathResult (see MDN Document: evaluate()). Learn the five parameters, common result types, how to iterate matches, how context nodes improve performance, when to prefer createExpression() or CSS selectors, and five try-it labs.

Introduction

XPath is a query language for trees. With document.evaluate() you pass an XPath string plus a context node, and the browser returns an XPathResult — often a node iterator you walk with iterateNext().

MDN: XPath works on both HTML and XML documents. For everyday element picks, querySelector / querySelectorAll are usually clearer. Reach for evaluate() when you need XPath features (for example count(), axis-style paths, or XML-oriented queries).

Related tutorials: createExpression(), createNSResolver(), enableStyleSheetsForSet().

Understanding document.evaluate()

An instance method on the page’s document object (part of the XPathEvaluatorBase API on Document; MDN).

• xpathExpression — string; the XPath to evaluate (MDN).
• contextNode — node where the query is rooted; commonly document (MDN).
• namespaceResolver — optional function for prefixes; null is common on HTML (MDN).
• resultType — optional XPathResult type constant; default ANY_TYPE (0) (MDN).
• result — optional existing XPathResult to reuse, or null for a new one (MDN).
• Return value — an XPathResult linking to selected nodes or a scalar value (MDN).

📝 Syntax

General form of Document.evaluate (MDN):

evaluate(xpathExpression, contextNode, namespaceResolver, resultType, result)

Parameters

• xpathExpression — a string representing the XPath to evaluate (MDN).
• contextNode — the context node for the query. It is common to pass document (MDN).
• namespaceResolver (optional) — a function that receives a namespace prefix and returns its URI. Use null for HTML or when no prefixes appear. Defaults to null if omitted (MDN).
• resultType (optional) — integer for the XPathResult type. Defaults to ANY_TYPE (0) (MDN).
• result (optional) — an existing XPathResult to fill, or null / omitted to create a new one (MDN).

Return value

An XPathResult. If result was null (or omitted), it is a new object; otherwise it is the same object you passed in (MDN).

Common resultType values (MDN)

MDN notes for iterators: they hold live references. Modifying the document can invalidate the iterator — iterating afterward may throw. Snapshots are not invalidated by DOM changes, but they may no longer match the live tree.

MDN example (find all h2 headings)

const headings = document.evaluate(
  "/html/body//h2",
  document,
  null,
  XPathResult.ANY_TYPE,
  null,
);

let thisHeading = headings.iterateNext();
let alertText = "Level 2 headings in this document are:\n";
while (thisHeading) {
  alertText += `${thisHeading.textContent}\n`;
  thisHeading = headings.iterateNext();
}
alert(alertText);

⚖️ evaluate vs createExpression vs querySelector

Examples Gallery

Examples follow MDN Document: evaluate() and practical beginner-friendly XPath patterns.

const headings = document.evaluate(
  "/html/body//h2",
  document,
  null,
  XPathResult.ANY_TYPE,
  null,
);

const texts = [];
let node = headings.iterateNext();
while (node) {
  texts.push(node.textContent.trim());
  node = headings.iterateNext();
}
console.log(texts.join(" | "));

Intro | Details
(depends on the page h2 text)

const headings = document.evaluate(
  ".//h2",
  document.body,
  null,
  XPathResult.ORDERED_NODE_ITERATOR_TYPE,
  null,
);

const texts = [];
let node = headings.iterateNext();
while (node) {
  texts.push(node.textContent.trim());
  node = headings.iterateNext();
}
console.log(texts.join(", "));

Intro, Details

const result = document.evaluate(
  "count(//button)",
  document,
  null,
  XPathResult.NUMBER_TYPE,
  null,
);

console.log(result.numberValue);

1
(or however many button elements exist)

const result = document.evaluate(
  "//h2[@id='intro']",
  document,
  null,
  XPathResult.FIRST_ORDERED_NODE_TYPE,
  null,
);

const heading = result.singleNodeValue;
console.log(heading ? heading.textContent.trim() : "(not found)");

Intro

const result = document.evaluate(
  "//li",
  document,
  null,
  XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,
  null,
);

const texts = [];
for (let i = 0; i < result.snapshotLength; i++) {
  texts.push(result.snapshotItem(i).textContent.trim());
}
console.log(texts);

["Apple", "Banana", "Cherry"]

🚀 Common Use Cases

• One-off XPath queries — run a path without compiling an expression first.
• XML / mixed documents — namespace-aware selection with a resolver.
• Numeric / boolean XPath — count(), not(), and similar.
• Scoped searches — pass a panel or document.body as context.
• Legacy tooling — scripts and tests that already speak XPath.
• Not every UI query — prefer CSS selectors for simple HTML picks.

📝 Notes

• MDN: Baseline Widely available since July 2015.
• MDN: works on both HTML and XML documents.
• MDN: pass null for namespaceResolver on typical HTML pages.
• MDN: prefer specific paths and tight contexts over a bare // on large trees.
• Do not mutate the DOM while walking an iterator without understanding invalidation (MDN).
• Related: createExpression(), createNSResolver(), parseHTML().

💡 Best Practices