Cheerio

You can refine or expand your selections using these patterns:

• Combining (AND logic): Write selectors next to each other to require an element to match all of them (e.g., $('p.selected') matches <p> elements that also have the class selected).
• Grouping (OR logic): Separate selectors with a comma to match any of them (e.g., $('h1, h2') matches all <h1> and <h2> elements).

// <p> elements that also have the class `selected`
const $selected = $('p.selected');

// All <h1> and <h2> elements
const $headings = $('h1, h2');

Cheerio uses two different parsers depending on the options provided to .load():

• parse5: The default for HTML. It rigorously follows the HTML standard to produce a tree identical to what a web browser would generate.
• htmlparser2: The default for XML. It is faster, more memory-efficient, and more forgiving of malformed markup than parse5.

To switch between these behaviors, you configure the options object passed to .load().

Choose a loading method based on your data source and encoding knowledge:

Browser Compatibility: Only load is available in the browser. All other methods require Node.js APIs.

Cheerio allows you to navigate the DOM tree starting from an initial selector. Traversal methods move between nodes (up, down, or sideways) and always return a new selection, leaving the original selection untouched. This allows for method chaining.

Traversal Categories:

• Down the tree: find, children, contents
• Up the tree: parent, parents, parentsUntil, closest
• Sideways (Siblings): next, prev, nextAll, prevAll, siblings, nextUntil, prevUntil
• Filtering: eq, filter, not, has, first, last

To scrape structured data (like a list of products or articles), pass an object as the value within a list descriptor.

When you provide a value object, the selectors inside it are evaluated relative to the outer selection. This allows you to pick a repeating container (like a section or div) and then describe the internal structure of one record.

Pattern for Scraping

1. Use an array in the map to define the repeating element.
2. Use selector to pick the container.
3. Use value as an object to define the fields within that container.

$.extract({
  lists: [
    {
      selector: 'ul',
      value: {
        red: ['.red'],
        selected: '.sel',
      },
    },
  ],
});
//=> { lists: [{ red: ['Four'], selected: 'Three' }, { red: ['Six'], selected: 'Five' }] }

Cheerio collections consist of objects that behave similarly to browser-based DOM nodes. Each node provides access to standard properties for traversal and inspection:

• tagName: The name of the tag.
• parentNode: The parent node.
• previousSibling: The preceding sibling node.
• nextSibling: The following sibling node.
• nodeValue: The value of the node.
• firstChild: The first child node.
• childNodes: A list of child nodes.
• lastChild: The last child node.

Cheerio is a parser, not a security tool. It parses markup, allows querying/changing the tree, and serializes it back to markup.

Key Security Behaviors:

• No Execution: Cheerio never executes scripts, evaluates expressions, or touches the network (with the sole exception of fromURL, which performs the network request you requested).
• No Sanitization: Cheerio's output is raw markup. If the input contains <script> tags or event handlers like onerror, they will survive parsing and serialization intact. The output of $.html() is exactly as trustworthy as the input.
• Recommendation: If you intend to render scraped markup in a browser, you must run it through a dedicated sanitizer like sanitize-html or DOMPurify first.

Cheerio supports standard CSS pseudo-classes via css-select, plus specialized extensions via cheerio-select that are useful for scraping but not valid in standard browsers:

• :contains("text"): Matches elements containing the specified text.
• :first: Matches the first element in the set.
• :last: Matches the last element in the set.
• :eq(n): Matches the $n^{th}$ element (zero-based index).

const $ = cheerio.load(`
  <ul>
    <li>Apple</li>
    <li>Banana</li>
    <li>Cherry</li>
  </ul>
`);

console.log(':contains:', $('li:contains("an")').text());
console.log(':first:', $('li:first').text());
console.log(':last:', $('li:last').text());
console.log(':eq(1):', $('li:eq(1)').text()); // zero-based

Cheerio is a parser, not a web browser. It is designed for speed and does not perform the following actions:

• Visual rendering
• CSS application
• Loading of external resources
• JavaScript execution

If your task requires rendering content generated by a Single Page Application (SPA) or executing client-side scripts, use browser automation tools like Puppeteer or Playwright, or a DOM emulation library like jsdom.

Cheerio's primary purpose is to parse and manipulate markup, not to ensure that markup is safe for browser rendering.

Important: Cheerio's output is markup, not 'safe' HTML. If you are taking input from an untrusted source, manipulating it with Cheerio, and then sending it to a client-side browser, you must sanitize the output using a dedicated sanitization library to prevent XSS attacks.

Recommended Workflow:

1. Receive untrusted HTML/XML.
2. Load and manipulate with Cheerio.
3. Serialize to string.
4. Sanitize the string using a library like sanitize-html.
5. Render the sanitized string in the browser.

Use these methods to select ancestors of the current selection:

• parent(): Selects the immediate parent element of the current selection.
• parents(): Selects all ancestor elements up to the root element.
• parentsUntil(selector): Selects all ancestor elements up to (but not including) the specified ancestor.
• closest(selector): Selects the nearest ancestor that matches the provided selector. Returns an empty selection if no match is found.

// parent: get the <ul> of an <li>
const list = $('li').parent();

// parents: get all ancestors
const ancestors = $('li').parents();

// parentsUntil: get ancestors up to a specific element
const ancestorsUntil = $('li').parentsUntil('div');

// closest: get the nearest <ul> ancestor
const list = $('li').closest('ul');