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

This is the HTML markup we will be using in all of the API examples:

<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

Properties

cheerio

• cheerio: "[cheerio object]"

Defined in

src/cheerio.ts:117

---

length

• length: number = 0

Implementation of

ArrayLike.length

Defined in

src/cheerio.ts:39

---

options

• options: InternalOptions

Defined in

src/cheerio.ts:42

---

prevObject

• prevObject: undefined | Cheerio<any>

Defined in

src/cheerio.ts:76

---

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

Name	Type	Description
start	number	The zero-based location in the array from which to start removing elements.
deleteCount?	number	The 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

Name	Type	Description
start	number	The zero-based location in the array from which to start removing elements.
deleteCount	number	The number of elements to remove.
...items	any[]	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:119

---

toString

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

Defined in

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

src/api/manipulation.ts:978

Attributes Methods

addClass

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

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

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/

Type parameters

Name	Type
T	extends AnyNode
R	extends ArrayLike<T, R>

Parameters

Name	Type	Description
this	R	-
value?	string | (this: Element, i: number, className: string) => undefined | string	Name of new class.

Returns

R

The instance itself.

Defined in

src/api/attributes.ts:919

---

attr

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

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

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
name	string	Name of the attribute.

Returns

string | undefined

The attribute's value.

Defined in

src/api/attributes.ts:113

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

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

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>

Returns

Record<string, string> | undefined

The attribute's values.

Defined in

src/api/attributes.ts:131

▸ 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.

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
name	string	Name of the attribute.
value?	null | string | (this: Element, i: number, attrib: string) => null | string	The new value of the attribute.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/attributes.ts:151

▸ 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.

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
values	Record<string, null | string>	Map of attribute names and values.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/attributes.ts:175

---

data

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

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

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
name	string	Name of the data attribute.

Returns

unknown | undefined

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

Defined in

src/api/attributes.ts:623

▸ 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.

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>

Returns

Record<string, unknown>

A map with all of the data attributes.

Defined in

src/api/attributes.ts:641

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

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

Example

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

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
name	string	Name of the data attribute.
value	unknown	The new value.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/attributes.ts:662

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

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

Example

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

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
values	Record<string, unknown>	Map of names to values.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/attributes.ts:684

---

hasClass

▸ hasClass<T>(this, className): boolean

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

Example

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

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

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
className	string	Name of the class.

Returns

boolean

Indicates if an element has the given className.

Defined in

src/api/attributes.ts:877

---

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.

Example

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

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
name	"tagName" | "nodeName"	Name of the property.

Returns

string | undefined

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

Defined in

src/api/attributes.ts:288

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>
name	"innerText" | "outerHTML" | "textContent" | "innerHTML"

Returns

string | null

Defined in

src/api/attributes.ts:292

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

Get a parsed CSS style object.

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<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:303

▸ 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.

Example

With baseURI set to 'https://example.com':

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
name	"href" | "src"	Name of the property.

Returns

string | undefined

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

Defined in

src/api/attributes.ts:320

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

Get a property of an element.

Type parameters

Name	Type
T	extends AnyNode
K	extends keyof Element

Parameters

Name	Type	Description
this	Cheerio<T>	-
name	K	Name of the property.

Returns

Element[K]

The property's value.

Defined in

src/api/attributes.ts:330

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

Set a property of an element.

Type parameters

Name	Type
T	extends AnyNode
K	extends keyof Element

Parameters

Name	Type	Description
this	Cheerio<T>	-
name	K	Name of the property.
value	Element[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) => T	Value to set the property to.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/attributes.ts:341

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

Set multiple properties of an element.

Example

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
map	Record<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.

Defined in

src/api/attributes.ts:362

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

Set a property of an element.

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
name	string	Name of the property.
value	null | string | boolean | (this: Element, i: number, prop: string) => string | boolean	Value to set the property to.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/attributes.ts:373

▸ prop<T>(this, name): string

Get a property of an element.

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
name	string	The property's name.

Returns

string

The property's value.

Defined in

src/api/attributes.ts:388

---

removeAttr

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

Method for removing attributes by name.

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/

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
name	string	Name of the attribute.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/attributes.ts:842

---

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.

Example

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

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

See

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

Type parameters

Name	Type
T	extends AnyNode
R	extends ArrayLike<T, R>

Parameters

Name	Type	Description
this	R	-
name?	string | (this: Element, i: number, className: string) => undefined | string	Name of the class. If not specified, removes all elements.

Returns

R

The instance itself.

Defined in

src/api/attributes.ts:986

---

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.

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/

Type parameters

Name	Type
T	extends AnyNode
R	extends ArrayLike<T, R>

Parameters

Name	Type	Description
this	R	-
value?	string | (this: Element, i: number, className: string, stateVal?: boolean) => string	Name of the class. Can also be a function.
stateVal?	boolean	If specified the state of the class.

Returns

R

The instance itself.

Defined in

src/api/attributes.ts:1056

---

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.

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>

Returns

string | undefined | string[]

The value.

Defined in

src/api/attributes.ts:733

▸ 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.

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
value	string | string[]	The new value.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/attributes.ts:751

---

CSS Methods

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.

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
names?	string[]	Optionally the names of the properties of interest.

Returns

Record<string, string> | undefined

A map of all of the style properties.

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.

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
name	string	The name of the property.

Returns

string | undefined

The property value for the given name.

Defined in

src/api/css.ts:27

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

Set one CSS property for every matched element.

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
prop	string	The name of the property.
val	string | (this: Element, i: number, style: string) => undefined | string	The new value.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/css.ts:40

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

Set multiple CSS properties for every matched element.

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
map	Record<string, string>	A map of property names and values.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/css.ts:55

---

Forms Methods

serialize

▸ serialize<T>(this): string

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

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>

Returns

string

The serialized form.

Defined in

src/api/forms.ts:25

---

serializeArray

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

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

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>

Returns

{ name: string ; value: string }[]

The serialized form.

Defined in

src/api/forms.ts:52

---

Manipulation Methods

after

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

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

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/

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
...elems	BasicAcceptedElems<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.

Defined in

src/api/manipulation.ts:610

---

appendTo

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

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

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/

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
target	BasicAcceptedElems<AnyNode>	Element to append elements to.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/manipulation.ts:206

---

before

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

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

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/

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
...elems	BasicAcceptedElems<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.

Defined in

src/api/manipulation.ts:717

---

clone

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

Clone the cheerio object.

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>

Returns

Cheerio<T>

The cloned object.

Defined in

src/api/manipulation.ts:1061

---

empty

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

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

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/manipulation.ts:902

---

html

▸ html<T>(this): string | null

Gets an HTML content string from the first selected element.

Example

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

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>

Returns

string | null

The HTML content string.

Defined in

src/api/manipulation.ts:929

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

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

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
str	string | Cheerio<T>	The content to replace selection's contents with.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/manipulation.ts:944

---

insertAfter

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

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

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/

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
target	BasicAcceptedElems<AnyNode>	Element to insert elements after.

Returns

Cheerio<T>

The set of newly inserted elements.

Defined in

src/api/manipulation.ts:662

---

insertBefore

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

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

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/

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
target	BasicAcceptedElems<AnyNode>	Element to insert elements before.

Returns

Cheerio<T>

The set of newly inserted elements.

Defined in

src/api/manipulation.ts:769

---

prependTo

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

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

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/

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
target	BasicAcceptedElems<AnyNode>	Element to prepend elements to.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/manipulation.ts:238

---

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.

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
selector?	string	Optional selector for elements to remove.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/manipulation.ts:820

---

replaceWith

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

Replaces matched elements with content.

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/

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
content	AcceptedElems<AnyNode>	Replacement for matched elements.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/manipulation.ts:855

---

text

▸ text<T>(this): string

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

Example

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

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>

Returns

string

The text contents of the collection.

Defined in

src/api/manipulation.ts:1001

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

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

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
str	string | (this: AnyNode, i: number, text: string) => string	The text to set as the content of each matched element.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/manipulation.ts:1017

---

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.

Example

without selector

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

with selector

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/

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
selector?	string	A 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.

Defined in

src/api/manipulation.ts:490

---

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.

Example

With markup passed to `wrapAll`

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

With an existing cheerio instance

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/

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
wrapper	AcceptedElems<T>	The DOM structure to wrap around all matched elements in the selection.

Returns

Cheerio<T>

The instance itself.

Defined in

src/api/manipulation.ts:551

---

Other Methods

[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

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>
...elems	BasicAcceptedElems<AnyNode>[] | [(this: AnyNode, i: number, html: string) => BasicAcceptedElems<AnyNode>]

Returns

Cheerio<T>

Defined in

src/api/manipulation.ts:84

---

children

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>
selector?	AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:120

---

extract

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

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

Type parameters

Name	Type
M	extends ExtractMap
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
map	M	An 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

Name	Type
nodes	T[]
match	AcceptedFilters<T>
xmlMode?	boolean
root?	Document

Returns

Element[] | T[]

Defined in

src/api/traversing.ts:732

---

next

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>
selector?	AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:120

---

nextAll

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>
selector?	AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:120

---

nextUntil

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>
selector?	null | AcceptedFilters<Element>
filterSelector?	AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:202

---

parent

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>
selector?	AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:120

---

parents

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>
selector?	AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:120

---

parentsUntil

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>
selector?	null | AcceptedFilters<Element>
filterSelector?	AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:202

---

prepend

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>
...elems	BasicAcceptedElems<AnyNode>[] | [(this: AnyNode, i: number, html: string) => BasicAcceptedElems<AnyNode>]

Returns

Cheerio<T>

Defined in

src/api/manipulation.ts:84

---

prev

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>
selector?	AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:120

---

prevAll

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>
selector?	AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:120

---

prevUntil

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>
selector?	null | AcceptedFilters<Element>
filterSelector?	AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:202

---

siblings

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>
selector?	AcceptedFilters<Element>

Returns

Cheerio<Element>

Defined in

src/api/traversing.ts:120

---

toArray

▸ toArray<T>(this): T[]

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

Example

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

Type parameters

Name
T

Parameters

Name	Type
this	Cheerio<T>

Returns

T[]

The contained items.

Defined in

src/api/traversing.ts:962

---

wrap

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>
wrapper	AcceptedElems<AnyNode>

Returns

Cheerio<T>

Defined in

src/api/manipulation.ts:300

---

wrapInner

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>
wrapper	AcceptedElems<AnyNode>

Returns

Cheerio<T>

Defined in

src/api/manipulation.ts:300

---

Traversing Methods

add

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

Add elements to the set of matched elements.

Example

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

See

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

Type parameters

Name	Type
S	extends AnyNode
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
other	string | 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.

Defined in

src/api/traversing.ts:1069

---

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.

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
selector?	string	Selector for the elements to add.

Returns

Cheerio<AnyNode>

The combined set.

Defined in

src/api/traversing.ts:1094

---

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.

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/

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
selector?	AcceptedFilters<Element>	Selector for the element to find.

Returns

Cheerio<AnyNode>

The closest nodes.

Defined in

src/api/traversing.ts:326

---

contents

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

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

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>

Returns

Cheerio<AnyNode>

The children.

Defined in

src/api/traversing.ts:554

---

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.

Example

const fruits = [];

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

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

See

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

Type parameters

Name
T

Parameters

Name	Type	Description
this	Cheerio<T>	-
fn	(this: T, i: number, el: T) => boolean | void	Function to execute.

Returns

Cheerio<T>

The instance itself, useful for chaining.

Defined in

src/api/traversing.ts:589

---

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.

Example

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

See

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

Type parameters

Name
T

Parameters

Name	Type
this	Cheerio<T>

Returns

Cheerio<AnyNode>

The previous state of the set of matched elements.

Defined in

src/api/traversing.ts:1050

---

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.

Example

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

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

See

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

Type parameters

Name
T

Parameters

Name	Type	Description
this	Cheerio<T>	-
i	number	Index of the element to select.

Returns

Cheerio<T>

The element at the ith position.

Defined in

src/api/traversing.ts:904

---

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.

Example

Function

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

See

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

Type parameters

Name
T
S

Parameters

Name	Type	Description
this	Cheerio<T>	-
match	(this: T, index: number, value: T) => value is S	Value to look for, following the rules above.

Returns

Cheerio<S>

The filtered collection.

Defined in

src/api/traversing.ts:682

▸ 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.

Example

Selector

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

Example

Function

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

See

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

Type parameters

Name
T
S

Parameters

Name	Type	Description
this	Cheerio<T>	-
match	S	Value to look for, following the rules above. See AcceptedFilters.

Returns

Cheerio<S extends string ? Element : T>

The filtered collection.

Defined in

src/api/traversing.ts:719

---

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.

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
selectorOrHaystack?	string | Element | Cheerio<Element>	Element to look for.

Returns

Cheerio<Element>

The found elements.

Defined in

src/api/traversing.ts:46

---

first

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

Will select the first element of a cheerio object.

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type
this	Cheerio<T>

Returns

Cheerio<T>

The first element.

Defined in

src/api/traversing.ts:865

---

get

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

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

Example

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

See

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

Type parameters

Name
T

Parameters

Name	Type	Description
this	Cheerio<T>	-
i	number	Element to retrieve.

Returns

T | undefined

The element at the ith position.

Defined in

src/api/traversing.ts:929

▸ get<T>(this): T[]

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

Example

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

See

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

Type parameters

Name
T

Parameters

Name	Type
this	Cheerio<T>

Returns

T[]

All elements matched by the Cheerio object.

Defined in

src/api/traversing.ts:943

---

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)').

Example

Selector

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

Example

Element

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

See

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

Parameters

Name	Type	Description
this	Cheerio<AnyNode>	-
selectorOrHaystack	string | Element | Cheerio<Element>	Element to look for.

Returns

Cheerio<AnyNode | Element>

The filtered collection.

Defined in

src/api/traversing.ts:840

---

index

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

Search for a given element from among the matched elements.

Example

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
selectorOrNeedle?	string | AnyNode | Cheerio<AnyNode>	Element to look for.

Returns

number

The index of the element.

Defined in

src/api/traversing.ts:983

---

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.

See

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

Type parameters

Name
T

Parameters

Name	Type	Description
this	Cheerio<T>	-
selector?	AcceptedFilters<T>	Selector for the selection.

Returns

boolean

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

Defined in

src/api/traversing.ts:755

---

last

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

Will select the last element of a cheerio object.

Example

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

See

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

Type parameters

Name
T

Parameters

Name	Type
this	Cheerio<T>

Returns

Cheerio<T>

The last element.

Defined in

src/api/traversing.ts:882

---

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.

Example

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

See

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

Type parameters

Name
T
M

Parameters

Name	Type	Description
this	Cheerio<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.

Defined in

src/api/traversing.ts:624

---

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.

Example

Selector

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

Example

Function

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

See

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

Type parameters

Name	Type
T	extends AnyNode

Parameters

Name	Type	Description
this	Cheerio<T>	-
match	AcceptedFilters<T>	Value to look for, following the rules above.

Returns

Cheerio<T>

The filtered collection.

Defined in

src/api/traversing.ts:801

---

slice

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

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

Example

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

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

See

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

Type parameters

Name
T

Parameters

Name	Type	Description
this	Cheerio<T>	-
start?	number	A position at which the elements begin to be selected. If negative, it indicates an offset from the end of the set.
end?	number	A 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.

Defined in

src/api/traversing.ts:1028