Skip to main content

Interface: CheerioAPI

A querying function, bound to a document created from the provided markup.

Also provides several helper methods for dealing with the document as a whole.

Hierarchy

  • StaticType

    CheerioAPI

Callable

CheerioAPI

CheerioAPI<T, S>(selector?, context?, root?, options?): Cheerio<S extends SelectorType ? Element : T>

This selector method is the starting point for traversing and manipulating the document. Like jQuery, it's the primary method for selecting elements in the document.

selector searches within the context scope, which searches within the root scope.

Type parameters

NameType
Textends AnyNode
Sextends string

Parameters

NameTypeDescription
selector?S | BasicAcceptedElems<T>Either a selector to look for within the document, or the contents of a new Cheerio instance.
context?null | BasicAcceptedElems<AnyNode>Either a selector to look for within the root, or the contents of the document to query.
root?BasicAcceptedElems<Document>Optional HTML document string.
options?CheerioOptions-

Returns

Cheerio<S extends SelectorType ? Element : T>

Example

$('ul .pear').attr('class');
//=> pear

$('li[class=orange]').html();
//=> Orange

$('.apple', '#fruits').text();
//=> Apple

Optionally, you can also load HTML by passing the string as the selector:

$('<ul id="fruits">...</ul>');

Or the context:

$('ul', '<ul id="fruits">...</ul>');

Or as the root:

$('li', 'ul', '<ul id="fruits">...</ul>');

Defined in

src/load.ts:66

Deprecated

load

load: (content: string | AnyNode | AnyNode[] | Buffer, options?: null | CheerioOptions, isDocument: boolean) => CheerioAPI

The .load static method defined on the "loaded" Cheerio factory function is deprecated. Users are encouraged to instead use the load function exported by the Cheerio module.

Deprecated

Use the load function exported by the Cheerio module.

Example

const $ = cheerio.load('<h1>Hello, <span>world</span>.</h1>');

Type declaration

▸ (content, options?, isDocument?): CheerioAPI

The .load static method defined on the "loaded" Cheerio factory function is deprecated. Users are encouraged to instead use the load function exported by the Cheerio module.

Parameters
NameTypeDefault value
contentstring | AnyNode | AnyNode[] | Bufferundefined
options?null | CheerioOptionsundefined
isDocumentbooleantrue
Returns

CheerioAPI

Deprecated

Use the load function exported by the Cheerio module.

Example

const $ = cheerio.load('<h1>Hello, <span>world</span>.</h1>');

Defined in

src/load.ts:103

Other

fn

fn: Cheerio<any>

Mimic jQuery's prototype alias for plugin authors.

Defined in

src/load.ts:88

Static

contains

contains(container, contained): boolean

Checks to see if the contained DOM element is a descendant of the container DOM element.

Parameters

NameTypeDescription
containerAnyNodePotential parent node.
containedAnyNodePotential child node.

Returns

boolean

Indicates if the nodes contain one another.

Alias

Cheerio.contains

See

https://api.jquery.com/jQuery.contains/

Inherited from

StaticType.contains

Defined in

src/static.ts:217


extract

extract<M>(this, map): ExtractedMap<M>

Extract multiple values from a document, and store them in an object.

Type parameters

NameType
Mextends ExtractMap

Parameters

NameTypeDescription
thisCheerioAPI-
mapMAn object containing key-value pairs. The keys are the names of the properties to be created on the object, and the values are the selectors to be used to extract the values.

Returns

ExtractedMap<M>

An object containing the extracted values.

Inherited from

StaticType.extract

Defined in

src/static.ts:247


html

html(this, options?): string

Renders the document.

Parameters

NameTypeDescription
thisCheerioAPI-
options?CheerioOptionsOptions for the renderer.

Returns

string

The rendered document.

Inherited from

StaticType.html

Defined in

src/static.ts:57

html(this, dom?, options?): string

Renders the document.

Parameters

NameTypeDescription
thisCheerioAPI-
dom?BasicAcceptedElems<AnyNode>Element to render.
options?CheerioOptionsOptions for the renderer.

Returns

string

The rendered document.

Inherited from

StaticType.html

Defined in

src/static.ts:66


merge

merge<T>(arr1, arr2): ArrayLike<T> | undefined

$.merge().

Type parameters

Name
T

Parameters

NameTypeDescription
arr1Writable<ArrayLike<T>>First array.
arr2ArrayLike<T>Second array.

Returns

ArrayLike<T> | undefined

arr1, with elements of arr2 inserted.

Alias

Cheerio.merge

See

https://api.jquery.com/jQuery.merge/

Inherited from

StaticType.merge

Defined in

src/static.ts:266


parseHTML

parseHTML(this, data, context?, keepScripts?): AnyNode[]

Parses a string into an array of DOM nodes. The context argument has no meaning for Cheerio, but it is maintained for API compatibility with jQuery.

Parameters

NameTypeDescription
thisCheerioAPI-
datastringMarkup that will be parsed.
context?unknownWill be ignored. If it is a boolean it will be used as the value of keepScripts.
keepScripts?booleanIf false all scripts will be removed.

Returns

AnyNode[]

The parsed DOM.

Alias

Cheerio.parseHTML

See

https://api.jquery.com/jQuery.parseHTML/

Inherited from

StaticType.parseHTML

Defined in

src/static.ts:151

parseHTML(this, data?): null

Parameters

NameType
thisCheerioAPI
data?null | ""

Returns

null

Inherited from

StaticType.parseHTML

Defined in

src/static.ts:157


root

root(this): Cheerio<Document>

Sometimes you need to work with the top-level root element. To query it, you can use $.root().

Parameters

NameType
thisCheerioAPI

Returns

Cheerio<Document>

Cheerio instance wrapping the root node.

Example

$.root().append('<ul id="vegetables"></ul>').html();
//=> <ul id="fruits">...</ul><ul id="vegetables"></ul>

Alias

Cheerio.root

Inherited from

StaticType.root

Defined in

src/static.ts:202


text

text(this, elements?): string

Render the document as text.

This returns the textContent of the passed elements. The result will include the contents of <script> and <style> elements. To avoid this, use .prop('innerText') instead.

Parameters

NameTypeDescription
thisvoid | CheerioAPI-
elements?ArrayLike<AnyNode>Elements to render.

Returns

string

The rendered document.

Inherited from

StaticType.text

Defined in

src/static.ts:123


xml

xml(this, dom?): string

Render the document as XML.

Parameters

NameTypeDescription
thisCheerioAPI-
dom?BasicAcceptedElems<AnyNode>Element to render.

Returns

string

THe rendered document.

Inherited from

StaticType.xml

Defined in

src/static.ts:103