Cheerio for JavaScript (Node.js): Complete Guide with Examples

What is Cheerio and why is it needed?

\n\n

Cheerio is a fast, flexible, and lightweight library for parsing HTML and XML on the server side of Node.js. It provides developers with a powerful jQuery-like syntax for navigating, searching, and manipulating the DOM tree. If you have ever worked with jQuery in the browser, Cheerio will feel intuitive — Cheerio implements a subset of jQuery adapted for server-side use.

\n\n

Main use cases for Cheerio:

\n

\n
• Web Scraping: Extracting data from web pages (prices, news headlines, article content).
\n
• Testing: Checking the structure of HTML templates in unit tests without a real browser.
\n
• HTML Preprocessing: Cleaning, transforming, and extracting parts of HTML documents before sending them to the client.
\n
• Parsing RSS/XML feeds: Processing XML documents, although there are more specialized tools for XML.
\n

\n\n

Unlike a full browser engine (e.g., Puppeteer or Playwright), Cheerio does not render JavaScript, load CSS, images, or external resources. This makes it extremely fast and memory-efficient. Cheerio works with a ready HTML string that you obtain, for example, via an HTTP request (using axios, node-fetch, or the built-in http/https module).

\n\n

Installing Cheerio

\n\n

Installing Cheerio in a Node.js project is done via the npm (or yarn) package manager. Open a terminal in your project root and run:

\n\n

npm install cheerio

\n\n

If you use yarn:

\n\n

yarn add cheerio

\n\n

After installation, you can import the library into your code:

\n\n

const cheerio = require('cheerio');\n// or for ES modules:\n// import * as cheerio from 'cheerio';

\n\n

Note: Cheerio is a library for Node.js and is not intended for use in the browser. If you need to parse HTML on the client side, it is better to use the native DOMParser.

\n\n

Quick Start: First Example

\n\n

Let's write a simple script that loads an HTML string, finds all links in it, and prints their text and href attributes.

\n\n

const cheerio = require('cheerio');\n\n// Example HTML code (usually you get it via an HTTP request)\nconst html = `\n<html>\n<head><title>Example Page</title></head>\n<body>\n    <h1>Welcome!</h1>\n    <ul>\n        <li><a href="https://example.com">Link 1</a></li>\n        <li><a href="https://google.com">Link 2</a></li>\n        <li class="special"><a href="https://github.com">Link 3</a></li>\n    </ul>\n</body>\n</html>\n`;\n\n// Load HTML into Cheerio\nconst $ = cheerio.load(html);\n\n// Find all <a> tags and iterate over them\n$('a').each((index, element) => {\n    const text = $(element).text();       // Text inside the tag\n    const href = $(element).attr('href'); // Value of the href attribute\n    console.log(`${index + 1}. ${text} - ${href}`);\n});\n\n// Result:\n// 1. Link 1 - https://example.com\n// 2. Link 2 - https://google.com\n// 3. Link 3 - https://github.com

\n\n

As you can see, the syntax is very similar to jQuery: we use the $() function to select elements, and then apply methods like .text(), .attr(), .each() to work with them.

\n\n

Main Cheerio Methods and Functions

\n\n

Below is a detailed breakdown of 10 key Cheerio methods with descriptions, parameters, and examples.

\n\n

1. cheerio.load(html, options?)

\n

What it does: Loads an HTML string and returns the main $ function, through which