Cheerio allows users to select elements from an HTML document using CSS selectors. This allows you to select elements based on criteria such as their tag name, class name, and attribute values. This guide provides an overview of how to use CSS selectors to retrieve elements.
To select elements with Cheerio, you first need to import the library and load a document. For example:
import * as cheerio from 'cheerio';
// Load the document using any of the methods described in the "Loading Documents" section.
const $ = cheerio.load('<html>...</html>');
Once you have loaded the document, you can use the
$ function to select
$ function works just like the
$ function in jQuery, and
allows you to select elements based on their tag name, class name, and attribute
Here are some examples of how to use the
$ function to select elements:
- To select all the
<p>elements in the document:
const $p = $('p');
The convention in Cheerio is to prefix the variable name with a $ to indicate that it contains a Cheerio object. This is not required, but it is a good practice to follow.
- To select elements with a specific class name:
const $selected = $('.selected');
- To select elements with a specific attribute value:
const $selected = $('[data-selected=true]');
You can select with XML Namespaces but
due to the CSS specification,
the colon (
:) needs to be escaped for the selector to be valid.
- Selectors can be combined to select elements that match multiple criteria. For
example, to select all
<p>elements with the class
const $selected = $('p.selected');
- Further, you can use spaces (
<p>elements that are descendants of
const $p = $('div p');
- You can also use the
>character to select elements that are direct descendants of other elements. For example, to select all
<p>elements that are direct descendants of
const $p = $('div > p');
Please have a look at the documentation of Cheerio's underlying CSS selector
a list of all supported selectors.
For example, to select
<p> elements containing the word "hello":
const $p = $('p:contains("hello")');
Cheerio also supports several jQuery-specific extensions that allow you to
select elements based on their position in the document. For example, to select
<p> element in the document:
const $p = $('p:first');
Have a look at cheerio-select, the library that implements these extensions, to see what is available.
Finally, to add custom CSS pseudo-classes, have a look at the Extending Cheerio guide.