Loading Documents
Relevant source files
The following files were used as context for generating this wiki page:
Loading documents is the fundamental entry point for using Cheerio. Unlike browser-based jQuery, which operates on a pre-existing global DOM, Cheerio requires the developer to explicitly pass HTML or XML content into the library to create a queryable instance. This process transforms raw strings, buffers, or remote resources into a Document Object Model (DOM) tree that Cheerio can manipulate.
The loading system has been significantly revamped in version 1.0 to support a wider array of input types, including binary data and streams, while offering "batteries included" features like automatic encoding detection and direct URL fetching.
Primary Loading Methods
Cheerio provides several methods to ingest content, each optimized for different data sources and environments. The core utility is the load function, which returns a CheerioAPI instance (often denoted as $).
Summary of Loading APIs
| Method | Input Type | Description |
|---|---|---|
load | string, Buffer, AnyNode, AnyNode[] | The standard method for parsing HTML/XML strings or pre-parsed DOM nodes. |
loadBuffer | Buffer | Specifically for binary data; uses automatic encoding detection. |
fromURL | string (URL) | Fetches content via the network and parses the response. |
stringStream | WritableStream | Parses HTML directly from a string-based stream. |
decodeStream | WritableStream | Parses HTML from a binary stream with automatic decoding. |
Sources: website/src/content/blog/2024-08-07-version-1.md:23-28, src/index.spec.ts:38-42, src/index.spec.ts:114-118
The load Function
The load function is the most common way to initialize Cheerio. It accepts markup and an optional configuration object. By default, it parses content as HTML using the parse5 parser, but it can be configured to use htmlparser2 for XML processing.
import * as cheerio from 'cheerio';
const $ = cheerio.load('<ul id="fruits">...</ul>');
Sources: Readme.md:55-63, src/load.spec.ts:5-8
Loading Architecture and Flow
The loading process involves taking raw input, selecting the appropriate parser based on configuration, and wrapping the resulting DOM tree in the Cheerio API.
Input Processing Flow
The following diagram illustrates how Cheerio handles different input types during the loading phase.
This flowchart shows the progression from input to a functional Cheerio instance. Sources: src/parse.spec.ts:7-11, src/index.spec.ts:153-157, website/src/content/blog/2024-08-07-version-1.md:23-28
Configuration Options
When loading a document, various options can be passed to alter the behavior of the underlying parsers.
Common Configuration Parameters
| Option | Type | Default | Description |
|---|---|---|---|
xml | boolean | Object | false | Enables XML mode. If an object, specifies htmlparser2 options. |
baseURI | string | undefined | The base URL for resolving relative links within the document. |
scriptingEnabled | boolean | true | When false, content inside <noscript> tags is parsed. |
sourceCodeLocationInfo | boolean | false | Includes location data (line/col) in the generated nodes. |
lowerCaseTags | boolean | false | (XML only) Forces tags to be lowercased. |
Sources: src/load.spec.ts:12-25, src/index.spec.ts:209-215, src/cheerio.spec.ts:402-429, src/parse.spec.ts:285-288
XML vs. HTML Parsing
Cheerio distinguishes between standard HTML parsing and XML parsing. HTML parsing is forgiving and follows the HTML5 specification via parse5. XML parsing, enabled via the xml option, is stricter and preserves case sensitivity unless configured otherwise.
// XML Mode Example
const $ = cheerio.load('<media:thumbnail />', { xml: true });
$.xml(); // => '<media:thumbnail/>'
Sources: src/tests/xml.spec.ts:5-13, src/cheerio.spec.ts:384-390
Advanced Loading Scenarios
Remote Resource Loading (fromURL)
Cheerio 1.0 introduces fromURL, which utilizes the undici library to fetch content. It automatically handles Content-Type headers to decide whether to use HTML or XML parsing and sets the baseURI based on the final URL after redirects.
Loading Pre-parsed DOMs
Cheerio can also wrap existing DOM structures that have been generated by other libraries, such as htmlparser2 or domhandler. This is useful for performance optimization or when working with existing DOM pipelines.
Sources: src/cheerio.spec.ts:376-382, src/static.spec.ts:205-208
Conclusion
Loading documents is the bridge between raw data and Cheerio's powerful manipulation API. By providing specialized methods for strings, buffers, streams, and URLs, Cheerio ensures that developers can efficiently ingest data regardless of its source. The addition of automatic encoding detection and URL fetching in version 1.0 simplifies common scraping and parsing tasks, making the library more robust and user-friendly.