JavaScript Document evaluate() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method
Decorative image with the word EVALUATE

Definition

document.evaluate() runs an XPath expression against a context node and returns an XPathResult. It works on both HTML and XML documents.

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call document.evaluate. Start with this line.

JavaScript
document.evaluate(xpath, context, resolver, type, result)
CallWhat it does
document.evaluate(xpath, context, resolver, type, result)Primary signature.
document.evaluate(...)Call with the arguments your case needs.

Built into the browser. Call evaluate(...) on document — no import required.

Library declarations
JavaScript
document.evaluate(xpath, context, resolver, type, result)

Parameters

ParameterDescription
xpathExpressionRequired. XPath string to evaluate
contextNodeRequired. Where the query starts (often document)
namespaceResolverOptional. Prefix → URI function; null for HTML
resultTypeOptional. Defaults to ANY_TYPE (0)
resultOptional. Reuse an XPathResult, or pass null

Return Value

Return ValueDescription
*The value returned by document.evaluate().

JavaScript Examples

Example 1 — Iterate Matching Nodes

Find all h2 elements under a context node and walk them with iterateNext().

JavaScript
const root = document.createElement("div");
root.innerHTML = "<h2>Alpha</h2><h2>Beta</h2>";

const result = document.evaluate(
  ".//h2",
  root,
  null,
  XPathResult.ORDERED_NODE_ITERATOR_TYPE,
  null
);

const texts = [];
let node = result.iterateNext();
while (node) {
  texts.push(node.textContent);
  node = result.iterateNext();
}
console.log(texts.join(", ")); // Alpha, Beta
Try It Yourself

How It Works

  1. Build a tiny tree. Two headings give a predictable XPath target.
  2. Evaluate. ".//h2" searches descendants of root.
  3. Use an iterator. ORDERED_NODE_ITERATOR_TYPE keeps document order.
  4. Walk results. Call iterateNext() until it returns null.

Example 2 — First Matching Node

Ask for a single node with FIRST_ORDERED_NODE_TYPE and read singleNodeValue.

JavaScript
const root = document.createElement("div");
root.innerHTML = "<p id='a'>First</p><p id='b'>Second</p>";

const result = document.evaluate(
  ".//p",
  root,
  null,
  XPathResult.FIRST_ORDERED_NODE_TYPE,
  null
);

console.log(result.singleNodeValue.id); // "a"
console.log(result.singleNodeValue.textContent); // "First"
Try It Yourself

How It Works

  1. Create sample markup. Two paragraphs in document order.
  2. Request one node. Type 9 means “first match only.”
  3. Read singleNodeValue. No loop needed.
  4. Order. “First” follows document order under the context.

Example 3 — count() Number Result

XPath can return a number — useful for counts without building a node list.

JavaScript
const root = document.createElement("ul");
root.innerHTML = "<li>One</li><li>Two</li><li>Three</li>";

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

console.log(result.numberValue); // 3
Try It Yourself

How It Works

  1. Build a list. Three li children are the count target.
  2. Use count(). XPath returns a number, not nodes.
  3. Ask for NUMBER_TYPE. That matches the expression result kind.
  4. Read numberValue. You get 3 without iterating.
Compatibility

Browser Support

Document.evaluate() is a browser DOM API marked Baseline Widely available on MDN (since July 2015).

✓ Baseline Widely available

Document.evaluate()

Supported in Chrome, Firefox, Safari, Edge, Opera, and Internet Explorer. Evaluates XPath on HTML and XML documents.

Baseline Widely available
Google Chrome All modern versions
Yes
Microsoft Edge All modern versions
Yes
Mozilla Firefox All modern versions
Yes
Apple Safari All modern versions
Yes
Opera All modern versions
Yes
Internet Explorer IE 9+
Yes
evaluate() Excellent in browsers

Bottom line: Safe for XPath queries in modern and legacy browsers. See the MDN evaluate() reference.

Frequently Asked Questions

It evaluates an XPath expression against a context node and returns an XPathResult. It works on both HTML and XML documents.
No. MDN marks Document.evaluate() as Baseline Widely available (since July 2015). It is not Deprecated, Experimental, or Non-standard.
Pass null for HTML documents or when the XPath has no namespace prefixes. If omitted, it defaults to null.
For iterator types, call iterateNext() until it returns null. For snapshot types, use snapshotLength and snapshotItem(i). For a single node, use FIRST_ORDERED_NODE_TYPE and singleNodeValue.
For simple CSS-style lookups, querySelector / querySelectorAll are usually clearer. Use evaluate() when you need XPath (axes, count(), complex predicates).
MDN notes that more specific paths and a tighter contextNode often perform better than a bare // shortcut on large documents.

Next: execCommand()

Learn document.execCommand() for rich-text editing commands (legacy API).

execCommand() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

11 people found this page helpful

JavaScript Document enableStyleSheetsForSet() Method JavaScript Document execCommand() Method