Skip to content

How to find elements by CSS selector in Puppeteer

Puppeteer gives you two direct methods for CSS-based element lookup.

OUTPUT FORMATSHTMLJSONMarkdown

Use page.$() when you need the first matching element, and page.$$() when you need every match on the page. The difference matters when you extract text or count results.

Choose the lookup method by the result you need

page.$() returns the first occurrence of the CSS selector you pass. page.$() returns all elements on the page that match that selector. If your task is to read a single heading, page.$() is the natural choice. If you need to count paragraphs or process a list, page.$() is the right method.

A useful decision checklist:

  • Need one element and its text? Use page.$() and extract textContent.
  • Need every match? Use page.$() and read the returned collection.
  • Need a count? Use page.$() and check the length of the result.
  • Need to handle a missing match? Check for null from page.$() or an empty collection from page.$().

What each method returns and how to read it

The two methods return different shapes, so the extraction step differs.

  • page.$("h1") returns the first matching element handle, or null when nothing matches. Pass that handle to page.evaluate() to read el.textContent.
  • page.$("p") returns a collection of matching element handles. To count matches, read the length of that returned collection (for example, the length of the array of handles) rather than the length of a single element.

This field/control map keeps the distinction clear: page.$() is a single-result lookup; page.$() is a multi-result lookup. The extraction callback receives the element or collection, not the selector string.

A worked pattern with an h1 and a paragraph count

A common pattern is to open a page, select the first h1 with page.$("h1"), and select all p elements with page.$("p"). You then read the h1 text through el.textContent and the paragraph total from the length of the returned collection. Log both values to the console before closing the browser.

Use this pattern when you want a single headline plus a count of body paragraphs. If the page has no h1, the first lookup returns null and the text extraction needs a guard. If the page has no p elements, the collection is empty and the count is zero.

Missing element versus empty result

A null return from page.$() means the selector found no element. An empty collection from page.$() means the selector found no matches across the page. These are different failure shapes: null is a single missing handle, while an empty collection is a zero-length result set. Check the shape before extracting text or counting, so a missing selector does not become a runtime error.

Frequently asked questions

What is the difference between page.$() and page.$$() in Puppeteer?

page.$() returns the first occurrence of the CSS selector, while page.$$() returns all elements that match the selector. Use the first for a single element and the second for a collection or count.

How do I get the text of an element found by a CSS selector?

Pass the element handle to page.evaluate() and read el.textContent. The example uses this approach for the first h1 element.

How do I count all matching elements?

Use page.$$() to collect all matches, then pass the collection to page.evaluate() and read its length. The example counts all p elements this way.

What happens when no element matches the selector?

page.$() returns null for a missing single element. page.$$() returns an empty collection when no elements match. Check for these shapes before extracting text or counting.