Skip to content

Find Elements by XPath in Puppeteer

When a page is easier to describe with XPath than with CSS selectors, Puppeteer can still locate the nodes you need.

OUTPUT FORMATSHTMLJSONMarkdown

The page.$x() method accepts an XPath expression and returns the matching elements as handles that you can inspect in the browser context.

Why use XPath with page.$x()

XPath is a useful alternative when the structure you care about is easier to express as a path through the document tree than as a CSS selector. In Puppeteer, page.$x() is the entry point for that style of lookup: pass it an XPath string and it resolves to an array of element handles for every match.

That array shape matters. Even when you expect only one node, the result is still a list. Treat the first match as item zero, and use the list length when you need a total count. This keeps single-element and multi-element cases consistent.

Workflow: select, read, count, close

Start the browser and open a page, then run two XPath lookups. The first targets a specific heading by its position in the page structure. The second uses a broad tag expression to collect every paragraph element. Together they show the two common patterns: pinpoint one node, or gather a whole set.

After selection, move the work into the page with page.evaluate(). Pass the first heading handle and read its textContent to get the visible heading text. Pass the paragraph handles and read their length to get the total number of matches. Print both results, then close the browser to finish cleanly.

The complete JavaScript implementation is provided as protected module code0001.

Practical checks

Checklist before you run the workflow:

  • Confirm the XPath matches the rendered page you actually load, not a different layout.
  • Remember that page.$x() returns an array, so index the first result rather than treating the return value as a single element.
  • Guard against an empty result before reading text from index zero.
  • Use page.evaluate() for in-page properties such as textContent and length, rather than expecting plain values directly from the handles.
  • Close the browser at the end, including when you adapt the example into a longer script.

XPath versus CSS selectors

XPath and CSS selectors solve the same selection problem in different syntaxes. Choose XPath when the path-based expression is clearer for the structure you need; choose a CSS selector when that syntax expresses the target more directly. The selection method changes, but the follow-up pattern is similar: obtain handles, evaluate properties in the page, and act on the values you need.

Frequently asked questions

How do I select elements with XPath in Puppeteer?

Use page.$x() with an XPath string instead of a CSS selector. It returns an array of matching element handles, so a single match is read from index 0 and a count comes from the array length.

Can one approach handle both a single element and many elements?

Yes. The example uses one XPath for a specific heading and a second XPath, //p, to collect every paragraph element on the page.

How do I read text or count matches after selection?

The returned handles are passed to page.evaluate(). There, textContent gives the heading text and length gives the number of paragraph matches.