JavaScript Document createExpression() Method

What You’ll Learn

document.createExpression() is an instance method that compiles an XPath string into an XPathExpression you can evaluate again and again (see MDN Document: createExpression()). Learn how it differs from a one-shot document.evaluate(), how to reuse expressions on different contexts, optional namespace mapping, and five try-it labs.

Introduction

XPath is a query language for selecting nodes in an XML/HTML tree — similar in spirit to CSS selectors, but with a different syntax and more power for some document shapes.

document.createExpression(xpathText) does not run the query yet. It compiles the path into an XPathExpression. Then you call xpathExpr.evaluate(contextNode) to get an XPathResult. MDN highlights that the compiled expression can be reused for repeated evaluations.

MDN also requires: call createExpression on the same document you will evaluate against.

Related tutorials: createElement(), createEvent().

Understanding document.createExpression()

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

• xpathText — string containing the XPath expression to compile (MDN).
• namespaceURLMapper — optional function mapping a prefix to a namespace URL, or null (MDN).
• Return value — a compiled XPathExpression.
• Evaluate — xpathExpr.evaluate(context) returns an XPathResult (MDN).
• Same document — create and run against the same document (MDN).
• Reuse — keep the expression object and evaluate it on different contexts.

📝 Syntax

General form of Document.createExpression (MDN):

createExpression(xpathText, namespaceURLMapper)

Parameters

• xpathText — string; the XPath expression to compile (MDN).
• namespaceURLMapper — function that maps a namespace prefix to a namespace URL, or null if none is needed (MDN). Typical signature: (prefix) => namespaceURI | null.

Return value

An XPathExpression ready for evaluate().

MDN basic pattern

const xpathExpr = document.createExpression("//div");
const xpathResult = xpathExpr.evaluate(document); // XPathResult
const nodeContext = document.querySelector("nav");
// Re-using the XPathExpression "xpathExpr"
const otherResult = xpathExpr.evaluate(nodeContext); // XPathResult

🔍 Tiny XPath cheat sheet for beginners

Enough XPath to understand the examples on this page:

⚖️ createExpression vs document.evaluate

Examples Gallery

Examples follow MDN Document: createExpression() and practical reuse patterns for beginners.

const xpathExpr = document.createExpression("//div");
const xpathResult = xpathExpr.evaluate(document); // XPathResult
const nodeContext = document.querySelector("nav");
const otherResult = xpathExpr.evaluate(nodeContext); // XPathResult

console.log(xpathExpr instanceof XPathExpression); // true
console.log(xpathResult.resultType); // number (result type constant)

true
(resultType is a numeric XPathResult type constant)

const expr = document.createExpression("//li");
const result = expr.evaluate(
  document,
  XPathResult.ORDERED_NODE_ITERATOR_TYPE
);

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

["Apple", "Banana", "Cherry"]
(depends on the page list items)

const section = document.getElementById("panel");
const expr = document.createExpression(".//span");
const result = expr.evaluate(
  section,
  XPathResult.ORDERED_NODE_SNAPSHOT_TYPE
);

console.log(result.snapshotLength);
for (let i = 0; i < result.snapshotLength; i++) {
  console.log(result.snapshotItem(i).textContent);
}

2
Alpha
Beta

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

console.log(result.numberValue);

1
(or however many button elements exist)

const svgNS = "http://www.w3.org/2000/svg";

function nsResolver(prefix) {
  const map = { svg: svgNS };
  return map[prefix] || null;
}

// Example: count svg:circle elements when prefixes are used in the XPath
const expr = document.createExpression("count(//svg:circle)", nsResolver);
const result = expr.evaluate(document, XPathResult.NUMBER_TYPE);
console.log(result.numberValue);

1
(if one svg:circle exists in the demo markup)

🚀 Common Use Cases

• Repeated XPath scans — compile once, evaluate in a loop (MDN).
• Scoped searches — same expression against different panels or list roots.
• XML / mixed documents — query with namespace-aware paths.
• Complex node tests — when CSS selectors are awkward or incomplete.
• Not every UI query — prefer querySelector for simple HTML selection.
• One-off lookups — document.evaluate may be simpler.

📝 Notes

• MDN: Baseline Widely available since July 2015.
• MDN: call createExpression on the same document you evaluate against.
• Compilation alone does not select nodes — you must call evaluate.
• Pass null for namespaceURLMapper when prefixes are not used (MDN).
• For everyday HTML, CSS selectors are often clearer than XPath.
• Related: createElement(), createEvent(), createDocumentFragment().

💡 Best Practices