JavaScript Document createExpression() Method

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

Definition

document.createExpression(xpathText, namespaceURLMapper) compiles an XPath string into an XPathExpression you can evaluate once or many times (MDN). Call it on the same document you will query.

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

Syntax

Call document.createExpression. Start with this line.

JavaScript
document.createExpression(xpath, mapper)
CallWhat it does
document.createExpression(xpath, mapper)Primary signature.
document.createExpression(...)Call with the arguments your case needs.

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

Library declarations
JavaScript
document.createExpression(xpath, mapper)

Parameters

ParameterDescription
xpathTextRequired. XPath expression string to compile
namespaceURLMapperOptional. Prefix → namespace URI function, or null

Return Value

Return ValueDescription
*XPathExpression

JavaScript Examples

Example 1 — Compile //div and Count

Build an XPathExpression, evaluate on document, read a snapshot count.

JavaScript
const expr = document.createExpression("//div");
const result = expr.evaluate(
  document,
  XPathResult.ORDERED_NODE_SNAPSHOT_TYPE
);

console.log(expr.constructor.name); // "XPathExpression"
console.log(result.snapshotLength); // number of <div> nodes
Try It Yourself

How It Works

  1. Compile. createExpression("//div") returns an XPathExpression.
  2. Evaluate. Pass document as the context node.
  3. Choose a result type. Snapshot mode exposes snapshotLength.
  4. Read the count. No need to iterate for a simple length check.

Example 2 — Reuse on a Scoped Context

Same compiled expression, evaluated on the whole document and on a <nav>.

JavaScript
const expr = document.createExpression("//div");
const nav = document.querySelector("nav");

const all = expr.evaluate(document, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE);
const scoped = expr.evaluate(nav, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE);

console.log(all.snapshotLength);    // all divs
console.log(scoped.snapshotLength); // divs under nav only
Try It Yourself

How It Works

  1. Compile once. One XPathExpression object.
  2. Evaluate on document. Context is the whole tree.
  3. Evaluate on nav. Context limits the search to that subtree.
  4. Compare counts. Same XPath, different roots — MDN’s reuse pattern.

Example 3 — vs document.evaluate()

One-shot evaluate versus compile-then-evaluate for the same XPath.

JavaScript
const xpath = "//button";

const oneShot = document.evaluate(
  xpath,
  document,
  null,
  XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,
  null
);

const expr = document.createExpression(xpath, null);
const reused = expr.evaluate(document, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE);

console.log(oneShot.snapshotLength === reused.snapshotLength); // true
Try It Yourself

How It Works

  1. One-shot path. document.evaluate takes the string every time.
  2. Compile path. createExpression stores a reusable object.
  3. Same result type. Snapshot counts match for the same XPath and context.
  4. Choose by need. Repeat often → compile; once → evaluate.
Compatibility

Browser Support

Document.createExpression() is a long-standing DOM XPath API. MDN lists it as Baseline Widely available (since July 2015).

✓ Baseline · XPath

Document.createExpression()

Supported in Chrome, Firefox, Safari, Edge, and other evergreen browsers. Safe for compiling reusable XPathExpression objects.

99% Universal API
Google Chrome All versions · Desktop & Mobile
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Internet Explorer IE 6+ · Legacy environments
Full support
Opera All modern versions
Full support
createExpression() Excellent

Bottom line: Safe to use when you need reusable XPath. For one-offs, document.evaluate is fine. See the MDN createExpression() reference.

Frequently Asked Questions

It compiles an XPath string into an XPathExpression. You then call evaluate() on that object — including repeatedly against different context nodes.
No. MDN marks Document.createExpression() as Baseline Widely available (since July 2015). It is not Deprecated, Experimental, or Non-standard.
An XPathExpression. Call xpathExpr.evaluate(contextNode) (optionally with a result type) to get an XPathResult.
Yes. MDN: you must call createExpression on the same document that you run the expression against.
Use createExpression when you will run the same XPath many times. For a one-off query, document.evaluate(xpath, context, ...) is often enough.
A function that maps a namespace prefix to a namespace URI, or null if none is needed. Use it when your XPath uses prefixes (XML/SVG).

Next: createNodeIterator()

Learn how document.createNodeIterator() walks a node subtree with filters.

createNodeIterator() 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 createEvent() Method JavaScript Document createNodeIterator() Method