Navigating and Searching HTML with Cheerio

Aug 11, 2023

Cheerio is a powerful and lightweight library that allows you to parse and manipulate HTML using a syntax similar to jQuery. It provides an easy way to navigate and search HTML documents, making it an excellent tool for web scraping and data extraction. In this article, we will explore how to use Cheerio to navigate and search HTML effectively.

Loading HTML into Cheerio

To get started with Cheerio, you need to load the HTML content into a Cheerio object. You can do this by passing the HTML string to the cheerio.load() function:

const cheerio = require('cheerio');

const $ = cheerio.load('<html><body><h1>Hello, World!</h1></body></html>');

The $ variable now represents the root of the loaded HTML document, and you can use it to navigate and search the DOM.

Navigating the DOM

Cheerio provides various methods to navigate the DOM tree and find specific elements. Here are some commonly used navigation methods:

  • find(selector): Finds all the elements that match the given CSS selector within the current context.

  • parent(): Gets the parent of the current element.

  • children(): Gets the children of the current element.

  • siblings(): Gets the siblings of the current element.

  • next() and prev(): Gets the next or previous sibling of the current element.

For example, to find all the <a> elements within a <div> with a specific class:

const links = $('div.container').find('a');

Searching Elements

Cheerio offers powerful methods to search for elements based on various criteria. Here are some commonly used search methods:

  • $(selector): Searches for elements that match the given CSS selector.

  • $('.class'): Searches for elements with a specific class.

  • $('#id'): Searches for an element with a specific ID.

  • $('tag'): Searches for elements with a specific tag name.

  • $('[attribute]'): Searches for elements with a specific attribute.

For example, to find all the <img> elements with the "alt" attribute:

const images = $('img[alt]');

Filtering Elements

Cheerio also provides methods to filter elements based on certain conditions. Here are some useful filtering methods:

  • filter(selector): Filters the elements that match the given selector.

  • not(selector): Filters out the elements that match the given selector.

  • has(selector): Filters the elements that have a descendant matching the given selector.

  • first() and last(): Gets the first or last element from the matched set.

  • eq(index): Gets the element at the specified index.

For example, to filter the <li> elements that have the class "active":

const activeItems = $('li').filter('.active');

Extracting Data

Once you have navigated to the desired elements, you can extract data from them using various methods provided by Cheerio. Here are some commonly used data extraction methods:

  • text(): Gets the combined text contents of the element and its descendants.

  • html(): Gets the inner HTML of the element.

  • attr(name): Gets the value of the specified attribute.

  • data(name): Gets the value of a data attribute.

  • val(): Gets the value of an input, select, or textarea element.

For example, to extract the text content of all the <p> elements:

const paragraphs = $('p').map((i, el) => $(el).text()).get();

Handling Dynamic Content

If the website you are scraping uses dynamic content that is loaded via JavaScript, you may need to use additional tools like Puppeteer or Playwright to render the page and then pass the HTML to Cheerio for parsing.

Here's an example of using Puppeteer with Cheerio:

const puppeteer = require('puppeteer');

const cheerio = require('cheerio');

(async () => {

const browser = await puppeteer.launch();

const page = await browser.newPage();

await page.goto('');

const html = await page.content();

const $ = cheerio.load(html);

// Use Cheerio to navigate and search the HTML

await browser.close();



Cheerio is a powerful library for navigating and searching HTML documents. It provides a simple and intuitive API similar to jQuery, making it easy to extract data from web pages. With Cheerio, you can:

  • Load HTML content into a Cheerio object.

  • Navigate the DOM tree using methods like find(), parent(), children(), and more.

  • Search for elements using CSS selectors, classes, IDs, tags, and attributes.

  • Filter elements based on various conditions.

  • Extract data from elements using methods like text(), html(), attr(), and more.

  • Handle dynamic content by integrating with tools like Puppeteer or Playwright.

By mastering the navigation and searching capabilities of Cheerio, you can effectively scrape and extract data from HTML documents, making it a valuable tool in your web scraping arsenal.

Let's get scraping 🚀

Ready to start?

Get scraping now with a free account and $25 in free credits when you sign up.