Skip to content

How to Find HTML Elements by Class with Cheerio

Cheerio lets you target HTML elements by their CSS class with the same selector syntax you would use in a browser.

OUTPUT FORMATSHTMLJSONMarkdown

The pattern is a tag name, a dot, and the class value — for example div.example — passed to the loaded Cheerio instance. This guide shows the full selector-to-text workflow and explains when a class lookup returns nothing.

The class selector in Cheerio

A class selector combines an element name with a dot and the class value. div.example matches every <div> whose class attribute includes example. Omitting the tag ('.example') matches any element carrying that class. The selector is passed to the $ function returned by cheerio.load(), which returns a Cheerio collection you can iterate, filter, or read from.

Worked example: select, iterate, extract

The sample below loads a small HTML string, selects all divs with class example, and prints each element's text. The protected code module code0001 accompanies this page with the exact runnable script. The three steps are: load the markup with cheerio.load(html), run $('div.example') to get the matched set, then call .each((i, div) => ...) and read $(div).text() inside the callback. The third div in the sample has no class, so it is excluded from the output.

Choosing the right selector

Use this checklist before writing the selector:

  • Class only, any tag: '.example'
  • Class on a specific tag: 'div.example'
  • Multiple classes on one element: '.example.active'
  • Attribute instead of class: '[data-role="example"]'
  • Multiple tags at once: 'div, span'

Pick the narrowest selector that still matches every element you need. A selector that is too broad forces extra filtering in the .each() callback; one that is too narrow silently returns an empty collection.

Why a class selector returns nothing

An empty result from $('div.example') usually means one of three things. First, the class value is misspelled or the element uses a different class. Second, the tag in the selector does not match the actual element — a span.example will not be found by div.example. Third, the class is added by client-side JavaScript after the initial HTML is parsed; Cheerio only sees the markup you pass to cheerio.load(), so dynamically injected classes are not present unless the HTML you load already contains them. Check the raw HTML string first, then adjust the selector.

Frequently asked questions

Can I select by class and ID together in Cheerio?

Yes. Combine them in one selector, for example 'div.example#main'. The element must match both the class and the ID for the selector to return it.

How do I match an element that has more than one class?

Chain the class names with dots, such as '.example.active'. The order of the classes in the selector does not need to match the order in the HTML attribute.

Should I use .text() or .html() to read the matched element?

Use $(div).text() when you want the visible text content only. Use $(div).html() when you need the inner markup, including any child tags. The sample script uses .text() because it extracts readable strings.