Skip to main content

Class: Cheerio<T>

The cheerio class is the central class of the library. It wraps a set of elements and provides an API for traversing, modifying, and interacting with the set.

Loading a document will return the Cheerio class bound to the root element of the document. The class will be instantiated when querying the document (when calling $('selector')).

Example

<ul id="fruits">
<li class="apple">Apple</li>
<li class="orange">Orange</li>
<li class="pear">Pear</li>
</ul>

Type parameters

Name
T

Hierarchy

  • MethodsType

  • Iterable<T>

    Cheerio

Implements

  • ArrayLike<T>

Indexable

▪ [index: number]: T

Attributes

addClass

addClass<T, R>(this, value?): R

Adds class(es) to all of the matched elements. Also accepts a function.

Type parameters

NameType
Textends AnyNode
Rextends ArrayLike<T>

Parameters

NameTypeDescription
thisR-
value?string | (this: Element, i: number, className: string) => undefined | stringName of new class.

Returns

R

The instance itself.

Example

$('.pear').addClass('fruit').html();
//=> <li class="pear fruit">Pear</li>

$('.apple').addClass('fruit red').html();
//=> <li class="apple fruit red">Apple</li>

See

https://api.jquery.com/addClass/

Defined in

src/api/attributes.ts:935


attr

attr<T>(this, name): string | undefined

Method for getting attributes. Gets the attribute value for only the first element in the matched set.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
namestringName of the attribute.

Returns

string | undefined

The attribute's value.

Example

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

See

https://api.jquery.com/attr/

Defined in

src/api/attributes.ts:114

attr<T>(this): Record<string, string> | undefined

Method for getting all attributes and their values of the first element in the matched set.

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>

Returns

Record<string, string> | undefined

The attribute's values.

Example

$('ul').attr();
//=> { id: 'fruits' }

See

https://api.jquery.com/attr/

Defined in

src/api/attributes.ts:133

attr<T>(this, name, value?): Cheerio<T>

Method for setting attributes. Sets the attribute value for only the first element in the matched set. If you set an attribute's value to null, you remove that attribute. You may also pass a map and function.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
namestringName of the attribute.
value?null | string | (this: Element, i: number, attrib: string) => null | stringThe new value of the attribute.

Returns

Cheerio<T>

The instance itself.

Example

$('.apple').attr('id', 'favorite').html();
//=> <li class="apple" id="favorite">Apple</li>

See

https://api.jquery.com/attr/

Defined in

src/api/attributes.ts:154

attr<T>(this, values): Cheerio<T>

Method for setting multiple attributes at once. Sets the attribute value for only the first element in the matched set. If you set an attribute's value to null, you remove that attribute.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
valuesRecord<string, null | string>Map of attribute names and values.

Returns

Cheerio<T>

The instance itself.

Example

$('.apple').attr({ id: 'favorite' }).html();
//=> <li class="apple" id="favorite">Apple</li>

See

https://api.jquery.com/attr/

Defined in

src/api/attributes.ts:179


data

data<T>(this, name): unknown | undefined

Method for getting data attributes, for only the first element in the matched set.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
namestringName of the data attribute.

Returns

unknown | undefined

The data attribute's value, or undefined if the attribute does not exist.

Example

$('<div data-apple-color="red"></div>').data('apple-color');
//=> 'red'

See

https://api.jquery.com/data/

Defined in

src/api/attributes.ts:631

data<T>(this): Record<string, unknown>

Method for getting all of an element's data attributes, for only the first element in the matched set.

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>

Returns

Record<string, unknown>

A map with all of the data attributes.

Example

$('<div data-apple-color="red"></div>').data();
//=> { appleColor: 'red' }

See

https://api.jquery.com/data/

Defined in

src/api/attributes.ts:650

data<T>(this, name, value): Cheerio<T>

Method for setting data attributes, for only the first element in the matched set.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
namestringName of the data attribute.
valueunknownThe new value.

Returns

Cheerio<T>

The instance itself.

Example

const apple = $('.apple').data('kind', 'mac');

apple.data('kind');
//=> 'mac'

See

https://api.jquery.com/data/

Defined in

src/api/attributes.ts:672

data<T>(this, values): Cheerio<T>

Method for setting multiple data attributes at once, for only the first element in the matched set.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
valuesRecord<string, unknown>Map of names to values.

Returns

Cheerio<T>

The instance itself.

Example

const apple = $('.apple').data({ kind: 'mac' });

apple.data('kind');
//=> 'mac'

See

https://api.jquery.com/data/

Defined in

src/api/attributes.ts:695


hasClass

hasClass<T>(this, className): boolean

Check to see if any of the matched elements have the given className.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
classNamestringName of the class.

Returns

boolean

Indicates if an element has the given className.

Example

$('.pear').hasClass('pear');
//=> true

$('apple').hasClass('fruit');
//=> false

$('li').hasClass('pear');
//=> true

See

https://api.jquery.com/hasClass/

Defined in

src/api/attributes.ts:892


prop

prop<T>(this, name): string | undefined

Method for getting and setting properties. Gets the property value for only the first element in the matched set.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
name"tagName" | "nodeName"Name of the property.

Returns

string | undefined

If value is specified the instance itself, otherwise the prop's value.

Example

$('input[type="checkbox"]').prop('checked');
//=> false

$('input[type="checkbox"]').prop('checked', true).val();
//=> ok

See

https://api.jquery.com/prop/

Defined in

src/api/attributes.ts:293

prop<T>(this, name): string | null

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>
name"innerText" | "outerHTML" | "textContent" | "innerHTML"

Returns

string | null

Defined in

src/api/attributes.ts:297

prop<T>(this, name): StyleProp | undefined

Get a parsed CSS style object.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
name"style"Name of the property.

Returns

StyleProp | undefined

The style object, or undefined if the element has no style attribute.

Defined in

src/api/attributes.ts:308

prop<T>(this, name): string | undefined

Resolve href or src of supported elements. Requires the baseURI option to be set, and a global URL object to be part of the environment.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
name"href" | "src"Name of the property.

Returns

string | undefined

The resolved URL, or undefined if the element is not supported.

Example

$('<img src="image.png">').prop('src');
//=> 'https://example.com/image.png'

Defined in

src/api/attributes.ts:326

prop<T, K>(this, name): Element[K]

Get a property of an element.

Type parameters

NameType
Textends AnyNode
Kextends keyof Element

Parameters

NameTypeDescription
thisCheerio<T>-
nameKName of the property.

Returns

Element[K]

The property's value.

Defined in

src/api/attributes.ts:336

prop<T, K>(this, name, value): Cheerio<T>

Set a property of an element.

Type parameters

NameType
Textends AnyNode
Kextends keyof Element

Parameters

NameTypeDescription
thisCheerio<T>-
nameKName of the property.
valueElement[K] | (this: Element, i: number, prop: K) => undefined | null | string | number | Record<string, string> | TagSourceCodeLocation | Document | Element | CDATA | Text | Comment | ProcessingInstruction | ChildNode[] | { [name: string]: string; } | Attribute[] | <T>(this: T, recursive?: boolean) => TValue to set the property to.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/attributes.ts:347

prop<T>(this, map): Cheerio<T>

Set multiple properties of an element.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
mapRecord<string, undefined | null | string | number | boolean | Record<string, string> | TagSourceCodeLocation | Document | Element | CDATA | Text | Comment | ProcessingInstruction | ChildNode[] | { [name: string]: string; } | Attribute[] | <T>(this: T, recursive?: boolean) => T>Object of properties to set.

Returns

Cheerio<T>

The instance itself.

Example

$('input[type="checkbox"]').prop({
checked: true,
disabled: false,
});

Defined in

src/api/attributes.ts:369

prop<T>(this, name, value): Cheerio<T>

Set a property of an element.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
namestringName of the property.
valuenull | string | boolean | (this: Element, i: number, prop: string) => string | booleanValue to set the property to.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/attributes.ts:380

prop<T>(this, name): string

Get a property of an element.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
namestringThe property's name.

Returns

string

The property's value.

Defined in

src/api/attributes.ts:395


removeAttr

removeAttr<T>(this, name): Cheerio<T>

Method for removing attributes by name.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
namestringName of the attribute.

Returns

Cheerio<T>

The instance itself.

Example

$('.pear').removeAttr('class').html();
//=> <li>Pear</li>

$('.apple').attr('id', 'favorite');
$('.apple').removeAttr('id class').html();
//=> <li>Apple</li>

See

https://api.jquery.com/removeAttr/

Defined in

src/api/attributes.ts:856


removeClass

removeClass<T, R>(this, name?): R

Removes one or more space-separated classes from the selected elements. If no className is defined, all classes will be removed. Also accepts a function.

Type parameters

NameType
Textends AnyNode
Rextends ArrayLike<T>

Parameters

NameTypeDescription
thisR-
name?string | (this: Element, i: number, className: string) => undefined | stringName of the class. If not specified, removes all elements.

Returns

R

The instance itself.

Example

$('.pear').removeClass('pear').html();
//=> <li class="">Pear</li>

$('.apple').addClass('red').removeClass().html();
//=> <li class="">Apple</li>

See

https://api.jquery.com/removeClass/

Defined in

src/api/attributes.ts:1003


toggleClass

toggleClass<T, R>(this, value?, stateVal?): R

Add or remove class(es) from the matched elements, depending on either the class's presence or the value of the switch argument. Also accepts a function.

Type parameters

NameType
Textends AnyNode
Rextends ArrayLike<T>

Parameters

NameTypeDescription
thisR-
value?string | (this: Element, i: number, className: string, stateVal?: boolean) => stringName of the class. Can also be a function.
stateVal?booleanIf specified the state of the class.

Returns

R

The instance itself.

Example

$('.apple.green').toggleClass('fruit green red').html();
//=> <li class="apple fruit red">Apple</li>

$('.apple.green').toggleClass('fruit green red', true).html();
//=> <li class="apple green fruit red">Apple</li>

See

https://api.jquery.com/toggleClass/

Defined in

src/api/attributes.ts:1074


val

val<T>(this): string | undefined | string[]

Method for getting the value of input, select, and textarea. Note: Support for map, and function has not been added yet.

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>

Returns

string | undefined | string[]

The value.

Example

$('input[type="text"]').val();
//=> input_text

See

https://api.jquery.com/val/

Defined in

src/api/attributes.ts:745

val<T>(this, value): Cheerio<T>

Method for setting the value of input, select, and textarea. Note: Support for map, and function has not been added yet.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
valuestring | string[]The new value.

Returns

Cheerio<T>

The instance itself.

Example

$('input[type="text"]').val('test').html();
//=> <input type="text" value="test"/>

See

https://api.jquery.com/val/

Defined in

src/api/attributes.ts:764

CSS

css

css<T>(this, names?): Record<string, string> | undefined

Get the value of a style property for the first element in the set of matched elements.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
names?string[]Optionally the names of the properties of interest.

Returns

Record<string, string> | undefined

A map of all of the style properties.

See

https://api.jquery.com/css/

Defined in

src/api/css.ts:14

css<T>(this, name): string | undefined

Get the value of a style property for the first element in the set of matched elements.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
namestringThe name of the property.

Returns

string | undefined

The property value for the given name.

See

https://api.jquery.com/css/

Defined in

src/api/css.ts:27

css<T>(this, prop, val): Cheerio<T>

Set one CSS property for every matched element.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
propstringThe name of the property.
valstring | (this: Element, i: number, style: string) => undefined | stringThe new value.

Returns

Cheerio<T>

The instance itself.

See

https://api.jquery.com/css/

Defined in

src/api/css.ts:40

css<T>(this, map): Cheerio<T>

Set multiple CSS properties for every matched element.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
mapRecord<string, string>A map of property names and values.

Returns

Cheerio<T>

The instance itself.

See

https://api.jquery.com/css/

Defined in

src/api/css.ts:55

Forms

serialize

serialize<T>(this): string

Encode a set of form elements as a string for submission.

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>

Returns

string

The serialized form.

Example

$('<form><input name="foo" value="bar" /></form>').serialize();
//=> 'foo=bar'

See

https://api.jquery.com/serialize/

Defined in

src/api/forms.ts:26


serializeArray

serializeArray<T>(this): { name: string ; value: string }[]

Encode a set of form elements as an array of names and values.

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>

Returns

{ name: string ; value: string }[]

The serialized form.

Example

$('<form><input name="foo" value="bar" /></form>').serializeArray();
//=> [ { name: 'foo', value: 'bar' } ]

See

https://api.jquery.com/serializeArray/

Defined in

src/api/forms.ts:54

Manipulation

after

after<T>(this, ...elems): Cheerio<T>

Insert content next to each element in the set of matched elements.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
...elemsBasicAcceptedElems<AnyNode>[] | [(this: AnyNode, i: number, html: string) => BasicAcceptedElems<AnyNode>]HTML string, DOM element, array of DOM elements or Cheerio to insert after each element in the set of matched elements.

Returns

Cheerio<T>

The instance itself.

Example

$('.apple').after('<li class="plum">Plum</li>');
$.html();
//=> <ul id="fruits">
// <li class="apple">Apple</li>
// <li class="plum">Plum</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>

See

https://api.jquery.com/after/

Defined in

src/api/manipulation.ts:621


appendTo

appendTo<T>(this, target): Cheerio<T>

Insert every element in the set of matched elements to the end of the target.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
targetBasicAcceptedElems<AnyNode>Element to append elements to.

Returns

Cheerio<T>

The instance itself.

Example

$('<li class="plum">Plum</li>').appendTo('#fruits');
$.html();
//=> <ul id="fruits">
// <li class="apple">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// <li class="plum">Plum</li>
// </ul>

See

https://api.jquery.com/appendTo/

Defined in

src/api/manipulation.ts:207


before

before<T>(this, ...elems): Cheerio<T>

Insert content previous to each element in the set of matched elements.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
...elemsBasicAcceptedElems<AnyNode>[] | [(this: AnyNode, i: number, html: string) => BasicAcceptedElems<AnyNode>]HTML string, DOM element, array of DOM elements or Cheerio to insert before each element in the set of matched elements.

Returns

Cheerio<T>

The instance itself.

Example

$('.apple').before('<li class="plum">Plum</li>');
$.html();
//=> <ul id="fruits">
// <li class="plum">Plum</li>
// <li class="apple">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>

See

https://api.jquery.com/before/

Defined in

src/api/manipulation.ts:730


clone

clone<T>(this): Cheerio<T>

Clone the cheerio object.

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>

Returns

Cheerio<T>

The cloned object.

Example

const moreFruit = $('#fruits').clone();

See

https://api.jquery.com/clone/

Defined in

src/api/manipulation.ts:1083


empty

empty<T>(this): Cheerio<T>

Removes all children from each item in the selection. Text nodes and comment nodes are left as is.

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>

Returns

Cheerio<T>

The instance itself.

Example

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

See

https://api.jquery.com/empty/

Defined in

src/api/manipulation.ts:919


html

html<T>(this): string | null

Gets an HTML content string from the first selected element.

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>

Returns

string | null

The HTML content string.

Example

$('.orange').html();
//=> Orange

$('#fruits').html('<li class="mango">Mango</li>').html();
//=> <li class="mango">Mango</li>

See

https://api.jquery.com/html/

Defined in

src/api/manipulation.ts:947

html<T>(this, str): Cheerio<T>

Replaces each selected element's content with the specified content.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
strstring | Cheerio<T>The content to replace selection's contents with.

Returns

Cheerio<T>

The instance itself.

Example

$('.orange').html('<li class="mango">Mango</li>').html();
//=> <li class="mango">Mango</li>

See

https://api.jquery.com/html/

Defined in

src/api/manipulation.ts:963


insertAfter

insertAfter<T>(this, target): Cheerio<T>

Insert every element in the set of matched elements after the target.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
targetBasicAcceptedElems<AnyNode>Element to insert elements after.

Returns

Cheerio<T>

The set of newly inserted elements.

Example

$('<li class="plum">Plum</li>').insertAfter('.apple');
$.html();
//=> <ul id="fruits">
// <li class="apple">Apple</li>
// <li class="plum">Plum</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>

See

https://api.jquery.com/insertAfter/

Defined in

src/api/manipulation.ts:674


insertBefore

insertBefore<T>(this, target): Cheerio<T>

Insert every element in the set of matched elements before the target.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
targetBasicAcceptedElems<AnyNode>Element to insert elements before.

Returns

Cheerio<T>

The set of newly inserted elements.

Example

$('<li class="plum">Plum</li>').insertBefore('.apple');
$.html();
//=> <ul id="fruits">
// <li class="plum">Plum</li>
// <li class="apple">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>

See

https://api.jquery.com/insertBefore/

Defined in

src/api/manipulation.ts:783


prependTo

prependTo<T>(this, target): Cheerio<T>

Insert every element in the set of matched elements to the beginning of the target.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
targetBasicAcceptedElems<AnyNode>Element to prepend elements to.

Returns

Cheerio<T>

The instance itself.

Example

$('<li class="plum">Plum</li>').prependTo('#fruits');
$.html();
//=> <ul id="fruits">
// <li class="plum">Plum</li>
// <li class="apple">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>

See

https://api.jquery.com/prependTo/

Defined in

src/api/manipulation.ts:240


remove

remove<T>(this, selector?): Cheerio<T>

Removes the set of matched elements from the DOM and all their children. selector filters the set of matched elements to be removed.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
selector?stringOptional selector for elements to remove.

Returns

Cheerio<T>

The instance itself.

Example

$('.pear').remove();
$.html();
//=> <ul id="fruits">
// <li class="apple">Apple</li>
// <li class="orange">Orange</li>
// </ul>

See

https://api.jquery.com/remove/

Defined in

src/api/manipulation.ts:835


replaceWith

replaceWith<T>(this, content): Cheerio<T>

Replaces matched elements with content.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
contentAcceptedElems<AnyNode>Replacement for matched elements.

Returns

Cheerio<T>

The instance itself.

Example

const plum = $('<li class="plum">Plum</li>');
$('.pear').replaceWith(plum);
$.html();
//=> <ul id="fruits">
// <li class="apple">Apple</li>
// <li class="orange">Orange</li>
// <li class="plum">Plum</li>
// </ul>

See

https://api.jquery.com/replaceWith/

Defined in

src/api/manipulation.ts:871


text

text<T>(this): string

Get the combined text contents of each element in the set of matched elements, including their descendants.

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>

Returns

string

The text contents of the collection.

Example

$('.orange').text();
//=> Orange

$('ul').text();
//=> Apple
// Orange
// Pear

See

https://api.jquery.com/text/

Defined in

src/api/manipulation.ts:1021

text<T>(this, str): Cheerio<T>

Set the content of each element in the set of matched elements to the specified text.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
strstring | (this: AnyNode, i: number, text: string) => stringThe text to set as the content of each matched element.

Returns

Cheerio<T>

The instance itself.

Example

$('.orange').text('Orange');
//=> <div class="orange">Orange</div>

See

https://api.jquery.com/text/

Defined in

src/api/manipulation.ts:1038


unwrap

unwrap<T>(this, selector?): Cheerio<T>

The .unwrap() function, removes the parents of the set of matched elements from the DOM, leaving the matched elements in their place.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
selector?stringA selector to check the parent element against. If an element's parent does not match the selector, the element won't be unwrapped.

Returns

Cheerio<T>

The instance itself, for chaining.

Example

const $ = cheerio.load(
'<div id=test>\n <div><p>Hello</p></div>\n <div><p>World</p></div>\n</div>',
);
$('#test p').unwrap();

//=> <div id=test>
// <p>Hello</p>
// <p>World</p>
// </div>

Example

const $ = cheerio.load(
'<div id=test>\n <p>Hello</p>\n <b><p>World</p></b>\n</div>',
);
$('#test p').unwrap('b');

//=> <div id=test>
// <p>Hello</p>
// <p>World</p>
// </div>

See

https://api.jquery.com/unwrap/

Defined in

src/api/manipulation.ts:498


wrapAll

wrapAll<T>(this, wrapper): Cheerio<T>

The .wrapAll() function can take any string or object that could be passed to the $() function to specify a DOM structure. This structure may be nested several levels deep, but should contain only one inmost element. The structure will be wrapped around all of the elements in the set of matched elements, as a single group.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
wrapperAcceptedElems<T>The DOM structure to wrap around all matched elements in the selection.

Returns

Cheerio<T>

The instance itself.

Example

const $ = cheerio.load(
'<div class="container"><div class="inner">First</div><div class="inner">Second</div></div>',
);
$('.inner').wrapAll("<div class='new'></div>");

//=> <div class="container">
// <div class='new'>
// <div class="inner">First</div>
// <div class="inner">Second</div>
// </div>
// </div>

Example

const $ = cheerio.load(
'<span>Span 1</span><strong>Strong</strong><span>Span 2</span>',
);
const wrap = $('<div><p><em><b></b></em></p></div>');
$('span').wrapAll(wrap);

//=> <div>
// <p>
// <em>
// <b>
// <span>Span 1</span>
// <span>Span 2</span>
// </b>
// </em>
// </p>
// </div>
// <strong>Strong</strong>

See

https://api.jquery.com/wrapAll/

Defined in

src/api/manipulation.ts:561

Other

cheerio

cheerio: "[cheerio object]"

Defined in

src/cheerio.ts:118


length

length: number = 0

Implementation of

ArrayLike.length

Defined in

src/cheerio.ts:40


options

options: InternalOptions

Defined in

src/cheerio.ts:43


prevObject

prevObject: undefined | Cheerio<any>

Defined in

src/cheerio.ts:77


splice

splice: (start: number, deleteCount?: number) => any[](start: number, deleteCount: number, ...items: any[]) => any[]

Type declaration

▸ (start, deleteCount?): any[]

Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.

Parameters
NameTypeDescription
startnumberThe zero-based location in the array from which to start removing elements.
deleteCount?numberThe number of elements to remove.
Returns

any[]

An array containing the elements that were deleted.

▸ (start, deleteCount, ...items): any[]

Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.

Parameters
NameTypeDescription
startnumberThe zero-based location in the array from which to start removing elements.
deleteCountnumberThe number of elements to remove.
...itemsany[]Elements to insert into the array in place of the deleted elements.
Returns

any[]

An array containing the elements that were deleted.

Defined in

src/cheerio.ts:120


toString

toString: () => string & <T>(this: Cheerio<T>) => string

Defined in

website/node_modules/typescript/lib/lib.es5.d.ts:128

src/api/manipulation.ts:997


[iterator]

[iterator](): Iterator<T, any, undefined>

Returns

Iterator<T, any, undefined>

Defined in

website/node_modules/typescript/lib/lib.es2015.iterable.d.ts:49


append

append<T>(this, ...elems): Cheerio<T>

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>
...elemsBasicAcceptedElems<AnyNode>[] | [(this: AnyNode, i: number, html: string) => BasicAcceptedElems<AnyNode>]

Returns

Cheerio<T>

Defined in

src/api/manipulation.ts:270


children

children<T>(this, selector?): Cheerio<Element>

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>
selector?AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:548


extract

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

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

Type parameters

NameType
Mextends ExtractMap
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
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.

Defined in

src/api/extract.ts:62


filterArray

filterArray<T>(nodes, match, xmlMode?, root?): Element[] | T[]

Type parameters

Name
T

Parameters

NameType
nodesT[]
matchAcceptedFilters<T>
xmlMode?boolean
root?Document

Returns

Element[] | T[]

Defined in

src/api/traversing.ts:751


next

next<T>(this, selector?): Cheerio<Element>

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>
selector?AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:386


nextAll

nextAll<T>(this, selector?): Cheerio<Element>

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>
selector?AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:406


nextUntil

nextUntil<T>(this, selector?, filterSelector?): Cheerio<Element>

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>
selector?null | AcceptedFilters<Element>
filterSelector?AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:432


parent

parent<T>(this, selector?): Cheerio<Element>

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>
selector?AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:245


parents

parents<T>(this, selector?): Cheerio<Element>

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>
selector?AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:268


parentsUntil

parentsUntil<T>(this, selector?, filterSelector?): Cheerio<Element>

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>
selector?null | AcceptedFilters<Element>
filterSelector?AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:299


prepend

prepend<T>(this, ...elems): Cheerio<T>

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>
...elemsBasicAcceptedElems<AnyNode>[] | [(this: AnyNode, i: number, html: string) => BasicAcceptedElems<AnyNode>]

Returns

Cheerio<T>

Defined in

src/api/manipulation.ts:293


prev

prev<T>(this, selector?): Cheerio<Element>

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>
selector?AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:453


prevAll

prevAll<T>(this, selector?): Cheerio<Element>

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>
selector?AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:474


prevUntil

prevUntil<T>(this, selector?, filterSelector?): Cheerio<Element>

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>
selector?null | AcceptedFilters<Element>
filterSelector?AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:500


siblings

siblings<T>(this, selector?): Cheerio<Element>

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>
selector?AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:524


toArray

toArray<T>(this): T[]

Retrieve all the DOM elements contained in the jQuery set as an array.

Type parameters

Name
T

Parameters

NameType
thisCheerio<T>

Returns

T[]

The contained items.

Example

$('li').toArray();
//=> [ {...}, {...}, {...} ]

Defined in

src/api/traversing.ts:991


wrap

wrap<T>(this, wrapper): Cheerio<T>

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>
wrapperAcceptedElems<AnyNode>

Returns

Cheerio<T>

Defined in

src/api/manipulation.ts:393


wrapInner

wrapInner<T>(this, wrapper): Cheerio<T>

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>
wrapperAcceptedElems<AnyNode>

Returns

Cheerio<T>

Defined in

src/api/manipulation.ts:453

Traversing

add

add<S, T>(this, other, context?): Cheerio<S | T>

Add elements to the set of matched elements.

Type parameters

NameType
Sextends AnyNode
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
otherstring | S | Cheerio<S> | S[]Elements to add.
context?string | Cheerio<S>Optionally the context of the new selection.

Returns

Cheerio<S | T>

The combined set.

Example

$('.apple').add('.orange').length;
//=> 2

See

https://api.jquery.com/add/

Defined in

src/api/traversing.ts:1102


addBack

addBack<T>(this, selector?): Cheerio<AnyNode>

Add the previous set of elements on the stack to the current set, optionally filtered by a selector.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
selector?stringSelector for the elements to add.

Returns

Cheerio<AnyNode>

The combined set.

Example

$('li').eq(0).addBack('.orange').length;
//=> 2

See

https://api.jquery.com/addBack/

Defined in

src/api/traversing.ts:1128


closest

closest<T>(this, selector?): Cheerio<AnyNode>

For each element in the set, get the first element that matches the selector by testing the element itself and traversing up through its ancestors in the DOM tree.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
selector?AcceptedFilters<Element>Selector for the element to find.

Returns

Cheerio<AnyNode>

The closest nodes.

Example

$('.orange').closest();
//=> []

$('.orange').closest('.apple');
// => []

$('.orange').closest('li');
//=> [<li class="orange">Orange</li>]

$('.orange').closest('#fruits');
//=> [<ul id="fruits"> ... </ul>]

See

https://api.jquery.com/closest/

Defined in

src/api/traversing.ts:331


contents

contents<T>(this): Cheerio<AnyNode>

Gets the children of each element in the set of matched elements, including text and comment nodes.

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>

Returns

Cheerio<AnyNode>

The children.

Example

$('#fruits').contents().length;
//=> 3

See

https://api.jquery.com/contents/

Defined in

src/api/traversing.ts:568


each

each<T>(this, fn): Cheerio<T>

Iterates over a cheerio object, executing a function for each matched element. When the callback is fired, the function is fired in the context of the DOM element, so this refers to the current element, which is equivalent to the function parameter element. To break out of the each loop early, return with false.

Type parameters

Name
T

Parameters

NameTypeDescription
thisCheerio<T>-
fn(this: T, i: number, el: T) => boolean | voidFunction to execute.

Returns

Cheerio<T>

The instance itself, useful for chaining.

Example

const fruits = [];

$('li').each(function (i, elem) {
fruits[i] = $(this).text();
});

fruits.join(', ');
//=> Apple, Orange, Pear

See

https://api.jquery.com/each/

Defined in

src/api/traversing.ts:604


end

end<T>(this): Cheerio<AnyNode>

End the most recent filtering operation in the current chain and return the set of matched elements to its previous state.

Type parameters

Name
T

Parameters

NameType
thisCheerio<T>

Returns

Cheerio<AnyNode>

The previous state of the set of matched elements.

Example

$('li').eq(0).end().length;
//=> 3

See

https://api.jquery.com/end/

Defined in

src/api/traversing.ts:1082


eq

eq<T>(this, i): Cheerio<T>

Reduce the set of matched elements to the one at the specified index. Use .eq(-i) to count backwards from the last selected element.

Type parameters

Name
T

Parameters

NameTypeDescription
thisCheerio<T>-
inumberIndex of the element to select.

Returns

Cheerio<T>

The element at the ith position.

Example

$('li').eq(0).text();
//=> Apple

$('li').eq(-1).text();
//=> Pear

See

https://api.jquery.com/eq/

Defined in

src/api/traversing.ts:930


filter

filter<T, S>(this, match): Cheerio<S>

Iterates over a cheerio object, reducing the set of selector elements to those that match the selector or pass the function's test.

This is the definition for using type guards; have a look below for other ways to invoke this method. The function is executed in the context of the selected element, so this refers to the current element.

Type parameters

Name
T
S

Parameters

NameTypeDescription
thisCheerio<T>-
match(this: T, index: number, value: T) => value is SValue to look for, following the rules above.

Returns

Cheerio<S>

The filtered collection.

Example

$('li')
.filter(function (i, el) {
// this === el
return $(this).attr('class') === 'orange';
})
.attr('class'); //=> orange

See

https://api.jquery.com/filter/

Defined in

src/api/traversing.ts:699

filter<T, S>(this, match): Cheerio<S extends string ? Element : T>

Iterates over a cheerio object, reducing the set of selector elements to those that match the selector or pass the function's test.

  • When a Cheerio selection is specified, return only the elements contained in that selection.
  • When an element is specified, return only that element (if it is contained in the original selection).
  • If using the function method, the function is executed in the context of the selected element, so this refers to the current element.

Type parameters

Name
T
S

Parameters

NameTypeDescription
thisCheerio<T>-
matchSValue to look for, following the rules above. See AcceptedFilters.

Returns

Cheerio<S extends string ? Element : T>

The filtered collection.

Example

$('li').filter('.orange').attr('class');
//=> orange

Example

$('li')
.filter(function (i, el) {
// this === el
return $(this).attr('class') === 'orange';
})
.attr('class'); //=> orange

See

https://api.jquery.com/filter/

Defined in

src/api/traversing.ts:738


find

find<T>(this, selectorOrHaystack?): Cheerio<Element>

Get the descendants of each element in the current set of matched elements, filtered by a selector, jQuery object, or element.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
selectorOrHaystack?string | Element | Cheerio<Element>Element to look for.

Returns

Cheerio<Element>

The found elements.

Example

$('#fruits').find('li').length;
//=> 3
$('#fruits').find($('.apple')).length;
//=> 1

See

https://api.jquery.com/find/

Defined in

src/api/traversing.ts:47


first

first<T>(this): Cheerio<T>

Will select the first element of a cheerio object.

Type parameters

NameType
Textends AnyNode

Parameters

NameType
thisCheerio<T>

Returns

Cheerio<T>

The first element.

Example

$('#fruits').children().first().text();
//=> Apple

See

https://api.jquery.com/first/

Defined in

src/api/traversing.ts:889


get

get<T>(this, i): T | undefined

Retrieve one of the elements matched by the Cheerio object, at the ith position.

Type parameters

Name
T

Parameters

NameTypeDescription
thisCheerio<T>-
inumberElement to retrieve.

Returns

T | undefined

The element at the ith position.

Example

$('li').get(0).tagName;
//=> li

See

https://api.jquery.com/get/

Defined in

src/api/traversing.ts:956

get<T>(this): T[]

Retrieve all elements matched by the Cheerio object, as an array.

Type parameters

Name
T

Parameters

NameType
thisCheerio<T>

Returns

T[]

All elements matched by the Cheerio object.

Example

$('li').get().length;
//=> 3

See

https://api.jquery.com/get/

Defined in

src/api/traversing.ts:971


has

has(this, selectorOrHaystack): Cheerio<AnyNode | Element>

Filters the set of matched elements to only those which have the given DOM element as a descendant or which have a descendant that matches the given selector. Equivalent to .filter(':has(selector)').

Parameters

NameTypeDescription
thisCheerio<AnyNode>-
selectorOrHaystackstring | Element | Cheerio<Element>Element to look for.

Returns

Cheerio<AnyNode | Element>

The filtered collection.

Example

$('ul').has('.pear').attr('id');
//=> fruits

Example

$('ul').has($('.pear')[0]).attr('id');
//=> fruits

See

https://api.jquery.com/has/

Defined in

src/api/traversing.ts:863


index

index<T>(this, selectorOrNeedle?): number

Search for a given element from among the matched elements.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
selectorOrNeedle?string | AnyNode | Cheerio<AnyNode>Element to look for.

Returns

number

The index of the element.

Example

$('.pear').index();
//=> 2 $('.orange').index('li');
//=> 1
$('.apple').index($('#fruit, li'));
//=> 1

See

https://api.jquery.com/index/

Defined in

src/api/traversing.ts:1013


is

is<T>(this, selector?): boolean

Checks the current list of elements and returns true if any of the elements match the selector. If using an element or Cheerio selection, returns true if any of the elements match. If using a predicate function, the function is executed in the context of the selected element, so this refers to the current element.

Type parameters

Name
T

Parameters

NameTypeDescription
thisCheerio<T>-
selector?AcceptedFilters<T>Selector for the selection.

Returns

boolean

Whether or not the selector matches an element of the instance.

See

https://api.jquery.com/is/

Defined in

src/api/traversing.ts:774


last

last<T>(this): Cheerio<T>

Will select the last element of a cheerio object.

Type parameters

Name
T

Parameters

NameType
thisCheerio<T>

Returns

Cheerio<T>

The last element.

Example

$('#fruits').children().last().text();
//=> Pear

See

https://api.jquery.com/last/

Defined in

src/api/traversing.ts:907


map

map<T, M>(this, fn): Cheerio<M>

Pass each element in the current matched set through a function, producing a new Cheerio object containing the return values. The function can return an individual data item or an array of data items to be inserted into the resulting set. If an array is returned, the elements inside the array are inserted into the set. If the function returns null or undefined, no element will be inserted.

Type parameters

Name
T
M

Parameters

NameTypeDescription
thisCheerio<T>-
fn(this: T, i: number, el: T) => undefined | null | M | M[]Function to execute.

Returns

Cheerio<M>

The mapped elements, wrapped in a Cheerio collection.

Example

$('li')
.map(function (i, el) {
// this === el
return $(this).text();
})
.toArray()
.join(' ');
//=> "apple orange pear"

See

https://api.jquery.com/map/

Defined in

src/api/traversing.ts:640


not

not<T>(this, match): Cheerio<T>

Remove elements from the set of matched elements. Given a Cheerio object that represents a set of DOM elements, the .not() method constructs a new Cheerio object from a subset of the matching elements. The supplied selector is tested against each element; the elements that don't match the selector will be included in the result.

The .not() method can take a function as its argument in the same way that .filter() does. Elements for which the function returns true are excluded from the filtered set; all other elements are included.

Type parameters

NameType
Textends AnyNode

Parameters

NameTypeDescription
thisCheerio<T>-
matchAcceptedFilters<T>Value to look for, following the rules above.

Returns

Cheerio<T>

The filtered collection.

Example

$('li').not('.apple').length;
//=> 2

Example

$('li').not(function (i, el) {
// this === el
return $(this).attr('class') === 'orange';
}).length; //=> 2

See

https://api.jquery.com/not/

Defined in

src/api/traversing.ts:822


slice

slice<T>(this, start?, end?): Cheerio<T>

Gets the elements matching the specified range (0-based position).

Type parameters

Name
T

Parameters

NameTypeDescription
thisCheerio<T>-
start?numberA position at which the elements begin to be selected. If negative, it indicates an offset from the end of the set.
end?numberA position at which the elements stop being selected. If negative, it indicates an offset from the end of the set. If omitted, the range continues until the end of the set.

Returns

Cheerio<T>

The elements matching the specified range.

Example

$('li').slice(1).eq(0).text();
//=> 'Orange'

$('li').slice(1, 2).length;
//=> 1

See

https://api.jquery.com/slice/

Defined in

src/api/traversing.ts:1059