Class: abstract 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>
Extends
MethodsType.Iterable<T>
Type Parameters
• T
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
• T extends AnyNode
• R extends ArrayLike<T>
Parameters
• this: R
• value?: string | (this, i, className) => undefined | string
Name 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
attr()
attr(this, name)
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
• T extends AnyNode
Parameters
• this: Cheerio<T>
• name: string
Name of the attribute.
Returns
string | undefined
The attribute's value.
Example
$('ul').attr('id');
//=> fruits
See
Defined in
attr(this)
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
• T extends AnyNode
Parameters
• this: Cheerio<T>
Returns
Record<string, string> | undefined
The attribute's values.
Example
$('ul').attr();
//=> { id: 'fruits' }
See
Defined in
attr(this, name, value)
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
• T extends AnyNode
Parameters
• this: Cheerio<T>
• name: string
Name of the attribute.
• value?: null | string | (this, i, attrib) => null | string
The 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
Defined in
attr(this, values)
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
• T extends AnyNode
Parameters
• this: Cheerio<T>
• values: Record<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
Defined in
data()
data(this, name)
data<
T>(this,name):unknown|undefined
Method for getting data attributes, for only the first element in the matched set.
Type Parameters
• T extends AnyNode
Parameters
• 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.
Example
$('<div data-apple-color="red"></div>').data('apple-color');
//=> 'red'
See
Defined in
data(this)
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
• T extends AnyNode
Parameters
• this: Cheerio<T>
Returns
Record<string, unknown>
A map with all of the data attributes.
Example
$('<div data-apple-color="red"></div>').data();
//=> { appleColor: 'red' }
See
Defined in
data(this, name, value)
data<
T>(this,name,value):Cheerio<T>
Method for setting data attributes, for only the first element in the matched set.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• name: string
Name of the data attribute.
• value: unknown
The new value.
Returns
Cheerio<T>
The instance itself.
Example
const apple = $('.apple').data('kind', 'mac');
apple.data('kind');
//=> 'mac'
See
Defined in
data(this, values)
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
• T extends AnyNode
Parameters
• this: Cheerio<T>
• values: Record<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
Defined in
hasClass()
hasClass<
T>(this,className):boolean
Check to see if any of the matched elements have the given className.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• className: string
Name 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
prop()
prop(this, name)
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
• T extends AnyNode
Parameters
• 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.
Example
$('input[type="checkbox"]').prop('checked');
//=> false
$('input[type="checkbox"]').prop('checked', true).val();
//=> ok
See
Defined in
prop(this, name)
prop<
T>(this,name):string|null
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• name: "innerText" | "outerHTML" | "textContent" | "innerHTML"
Returns
string | null
Defined in
prop(this, name)
prop<
T>(this,name):StyleProp|undefined
Get a parsed CSS style object.
Type Parameters
• T extends AnyNode
Parameters
• 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
prop(this, name)
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
• T extends AnyNode
Parameters
• this: Cheerio<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
prop(this, name)
prop<
T,K>(this,name):Element[K]
Get a property of an element.
Type Parameters
• T extends AnyNode
• K extends keyof Element
Parameters
• this: Cheerio<T>
• name: K
Name of the property.
Returns
Element[K]
The property's value.
Defined in
prop(this, name, value)
prop<
T,K>(this,name,value):Cheerio<T>
Set a property of an element.
Type Parameters
• T extends AnyNode
• K extends keyof Element
Parameters
• this: Cheerio<T>
• name: K
Name of the property.
• value: Element[K] | (this, i, prop) => undefined | null | string | number | Record<string, string> | TagSourceCodeLocation | Document | Element | CDATA | Text | Comment | ProcessingInstruction | ChildNode[] | object | Attribute[] | <T>(this, recursive?) => T
Value to set the property to.
Returns
Cheerio<T>
The instance itself.
Defined in
prop(this, map)
prop<
T>(this,map):Cheerio<T>
Set multiple properties of an element.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• map: Record<string, undefined | null | string | number | boolean | Record<string, string> | TagSourceCodeLocation | Document | Element | CDATA | Text | Comment | ProcessingInstruction | ChildNode[] | object | Attribute[] | <T>(this, recursive?) => T>
Object of properties to set.
Returns
Cheerio<T>
The instance itself.
Example
$('input[type="checkbox"]').prop({
checked: true,
disabled: false,
});
Defined in
prop(this, name, value)
prop<
T>(this,name,value):Cheerio<T>
Set a property of an element.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• name: string
Name of the property.
• value: null | string | boolean | (this, i, prop) => string | boolean
Value to set the property to.
Returns
Cheerio<T>
The instance itself.
Defined in
prop(this, name)
prop<
T>(this,name):string
Get a property of an element.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• name: string
The property's name.
Returns
string
The property's value.
Defined in
removeAttr()
removeAttr<
T>(this,name):Cheerio<T>
Method for removing attributes by name.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• name: string
Name 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
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
• T extends AnyNode
• R extends ArrayLike<T>
Parameters
• this: R
• name?: string | (this, i, className) => undefined | string
Name 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
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
• T extends AnyNode
• R extends ArrayLike<T>
Parameters
• this: R
• value?: string | (this, i, className, stateVal?) => string
Name of the class. Can also be a function.
• stateVal?: boolean
If 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
val()
val(this)
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
• T extends AnyNode
Parameters
• this: Cheerio<T>
Returns
string | undefined | string[]
The value.
Example
$('input[type="text"]').val();
//=> input_text
See
Defined in
val(this, value)
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
• T extends AnyNode
Parameters
• this: Cheerio<T>
• value: string | string[]
The new value.
Returns
Cheerio<T>
The instance itself.
Example
$('input[type="text"]').val('test').html();
//=> <input type="text" value="test"/>
See
Defined in
CSS
css()
Set multiple CSS properties for every matched element.
Param
The names of the properties.
Param
The new values.
See
css(this, names)
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
• T extends AnyNode
Parameters
• 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.
See
Defined in
css(this, name)
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
• T extends AnyNode
Parameters
• this: Cheerio<T>
• name: string
The name of the property.
Returns
string | undefined
The property value for the given name.
See
Defined in
css(this, prop, val)
css<
T>(this,prop,val):Cheerio<T>
Set one CSS property for every matched element.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• prop: string
The name of the property.
• val: string | (this, i, style) => undefined | string
The new value.
Returns
Cheerio<T>
The instance itself.
See
Defined in
css(this, map)
css<
T>(this,map):Cheerio<T>
Set multiple CSS properties for every matched element.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• map: Record<string, string>
A map of property names and values.
Returns
Cheerio<T>
The instance itself.
See
Defined in
Forms
serialize()
serialize<
T>(this):string
Encode a set of form elements as a string for submission.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<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
serializeArray()
serializeArray<
T>(this):object[]
Encode a set of form elements as an array of names and values.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
Returns
object[]
The serialized form.
Example
$('<form><input name="foo" value="bar" /></form>').serializeArray();
//=> [ { name: 'foo', value: 'bar' } ]
See
https://api.jquery.com/serializeArray/
Defined in
Manipulation
after()
after<
T>(this, ...elems):Cheerio<T>
Insert content next to each element in the set of matched elements.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• ...elems: BasicAcceptedElems<AnyNode>[] | [(this, i, html) => 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
Defined in
append()
append<
T>(this, ...elems):Cheerio<T>
Inserts content as the last child of each of the selected elements.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• ...elems: BasicAcceptedElems<AnyNode>[] | [(this, i, html) => BasicAcceptedElems<AnyNode>]
Returns
Cheerio<T>
Example
$('ul').append('<li class="plum">Plum</li>');
$.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/append/
Defined in
appendTo()
appendTo<
T>(this,target):Cheerio<T>
Insert every element in the set of matched elements to the end of the target.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• target: BasicAcceptedElems<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
before()
before<
T>(this, ...elems):Cheerio<T>
Insert content previous to each element in the set of matched elements.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• ...elems: BasicAcceptedElems<AnyNode>[] | [(this, i, html) => 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
clone()
clone<
T>(this):Cheerio<T>
Clone the cheerio object.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
Returns
Cheerio<T>
The cloned object.
Example
const moreFruit = $('#fruits').clone();
See
Defined in
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
• T extends AnyNode
Parameters
• this: Cheerio<T>
Returns
Cheerio<T>
The instance itself.
Example
$('ul').empty();
$.html();
//=> <ul id="fruits"></ul>
See
Defined in
html()
html(this)
html<
T>(this):string|null
Gets an HTML content string from the first selected element.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<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
Defined in
html(this, str)
html<
T>(this,str):Cheerio<T>
Replaces each selected element's content with the specified content.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• str: string | 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
Defined in
insertAfter()
insertAfter<
T>(this,target):Cheerio<T>
Insert every element in the set of matched elements after the target.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• target: BasicAcceptedElems<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
insertBefore()
insertBefore<
T>(this,target):Cheerio<T>
Insert every element in the set of matched elements before the target.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• target: BasicAcceptedElems<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
prepend()
prepend<
T>(this, ...elems):Cheerio<T>
Inserts content as the first child of each of the selected elements.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• ...elems: BasicAcceptedElems<AnyNode>[] | [(this, i, html) => BasicAcceptedElems<AnyNode>]
Returns
Cheerio<T>
Example
$('ul').prepend('<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/prepend/
Defined in
prependTo()
prependTo<
T>(this,target):Cheerio<T>
Insert every element in the set of matched elements to the beginning of the target.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• target: BasicAcceptedElems<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
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
• T extends AnyNode
Parameters
• this: Cheerio<T>
• selector?: string
Optional 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
replaceWith()
replaceWith<
T>(this,content):Cheerio<T>
Replaces matched elements with content.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• content: AcceptedElems<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
text()
text(this)
text<
T>(this):string
Get the combined text contents of each element in the set of matched elements, including their descendants.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
Returns
string
The text contents of the collection.
Example
$('.orange').text();
//=> Orange
$('ul').text();
//=> Apple
// Orange
// Pear
See
Defined in
text(this, str)
text<
T>(this,str):Cheerio<T>
Set the content of each element in the set of matched elements to the specified text.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• str: string | (this, i, text) => string
The 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
Defined in
toString()
toString<
T>(this):string
Turns the collection to a string. Alias for .html().
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
Returns
string
The rendered document.
Defined in
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
• T extends AnyNode
Parameters
• 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.
Examples
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>
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
wrap()
wrap<
T>(this,wrapper):Cheerio<T>
The .wrap() function can take any string or object that could be passed to the $() factory function to specify a DOM structure. This structure may be nested several levels deep, but should contain only one inmost element. A copy of this structure will be wrapped around each of the elements in the set of matched elements. This method returns the original set of elements for chaining purposes.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• wrapper: AcceptedElems<AnyNode>
The DOM structure to wrap around each element in the selection.
Returns
Cheerio<T>
Example
const redFruit = $('<div class="red-fruit"></div>');
$('.apple').wrap(redFruit);
//=> <ul id="fruits">
// <div class="red-fruit">
// <li class="apple">Apple</li>
// </div>
// <li class="orange">Orange</li>
// <li class="plum">Plum</li>
// </ul>
const healthy = $('<div class="healthy"></div>');
$('li').wrap(healthy);
//=> <ul id="fruits">
// <div class="healthy">
// <li class="apple">Apple</li>
// </div>
// <div class="healthy">
// <li class="orange">Orange</li>
// </div>
// <div class="healthy">
// <li class="plum">Plum</li>
// </div>
// </ul>
See
Defined in
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
• T extends AnyNode
Parameters
• this: Cheerio<T>
• wrapper: AcceptedElems<T>
The DOM structure to wrap around all matched elements in the selection.
Returns
Cheerio<T>
The instance itself.
Examples
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>
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
wrapInner()
wrapInner<
T>(this,wrapper):Cheerio<T>
The .wrapInner() function can take any string or object that could be passed to the $() factory 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 the content of each of the elements in the set of matched elements.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• wrapper: AcceptedElems<AnyNode>
The DOM structure to wrap around the content of each element in the selection.
Returns
Cheerio<T>
The instance itself, for chaining.
Example
const redFruit = $('<div class="red-fruit"></div>');
$('.apple').wrapInner(redFruit);
//=> <ul id="fruits">
// <li class="apple">
// <div class="red-fruit">Apple</div>
// </li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
const healthy = $('<div class="healthy"></div>');
$('li').wrapInner(healthy);
//=> <ul id="fruits">
// <li class="apple">
// <div class="healthy">Apple</div>
// </li>
// <li class="orange">
// <div class="healthy">Orange</div>
// </li>
// <li class="pear">
// <div class="healthy">Pear</div>
// </li>
// </ul>
See
https://api.jquery.com/wrapInner/
Defined in
Other
cheerio
cheerio:
"[cheerio object]"
Defined in
length
length:
number=0
Implementation of
ArrayLike.length
Defined in
options
options:
InternalOptions
Defined in
prevObject
prevObject:
undefined|Cheerio<any>
Defined in
splice()
splice: (
start,deleteCount?) =>any[](start,deleteCount, ...items) =>any[]
Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.
Parameters
• 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.
Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.
Parameters
• 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
[iterator]()
[iterator]():
Iterator<T,any,undefined>
Returns
Iterator<T, any, undefined>
Defined in
website/node_modules/typescript/lib/lib.es2015.iterable.d.ts:49
extract()
extract<
M,T>(this,map):ExtractedMap<M>
Extract multiple values from a document, and store them in an object.
Type Parameters
• M extends ExtractMap
• T extends AnyNode
Parameters
• 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
filterArray()
filterArray<
T>(nodes,match,xmlMode?,root?):Element[] |T[]
Type Parameters
• T
Parameters
• nodes: T[]
• match: AcceptedFilters<T>
• xmlMode?: boolean
• root?: Document
Returns
Element[] | T[]
Defined in
toArray()
toArray<
T>(this):T[]
Retrieve all the DOM elements contained in the jQuery set as an array.
Type Parameters
• T
Parameters
• this: Cheerio<T>
Returns
T[]
The contained items.
Example
$('li').toArray();
//=> [ {...}, {...}, {...} ]
Defined in
Traversing
add()
add<
S,T>(this,other,context?):Cheerio<S|T>
Add elements to the set of matched elements.
Type Parameters
• S extends AnyNode
• T extends AnyNode
Parameters
• 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.
Example
$('.apple').add('.orange').length;
//=> 2
See
Defined in
addBack()
Add the previous set of elements on the stack to the current set, optionally filtered by a selector.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• selector?: string
Selector for the elements to add.
Returns
The combined set.
Example
$('li').eq(0).addBack('.orange').length;
//=> 2
See
https://api.jquery.com/addBack/
Defined in
children()
Gets the element children of each element in the set of matched elements.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• selector?: AcceptedFilters<Element>
If specified filter for children.
Returns
The children.
Example
$('#fruits').children().length;
//=> 3
$('#fruits').children('.pear').text();
//=> Pear
See
https://api.jquery.com/children/
Defined in
closest()
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
• T extends AnyNode
Parameters
• this: Cheerio<T>
• selector?: AcceptedFilters<Element>
Selector for the element to find.
Returns
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
contents()
Gets the children of each element in the set of matched elements, including text and comment nodes.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
Returns
The children.
Example
$('#fruits').contents().length;
//=> 3
See
https://api.jquery.com/contents/
Defined in
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
• T
Parameters
• this: Cheerio<T>
• fn
Function 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
Defined in
end()
End the most recent filtering operation in the current chain and return the set of matched elements to its previous state.
Type Parameters
• T
Parameters
• this: Cheerio<T>
Returns
The previous state of the set of matched elements.
Example
$('li').eq(0).end().length;
//=> 3
See
Defined in
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
• T
Parameters
• this: Cheerio<T>
• i: number
Index 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
Defined in
filter()
filter(this, match)
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
• T
• S
Parameters
• this: Cheerio<T>
• match
Value 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
filter(this, match)
filter<
T,S>(this,match):Cheerio<Sextendsstring?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
thisrefers to the current element.
Type Parameters
• T
• S
Parameters
• 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.
Examples
$('li').filter('.orange').attr('class');
//=> orange
$('li')
.filter(function (i, el) {
// this === el
return $(this).attr('class') === 'orange';
})
.attr('class'); //=> orange
See
https://api.jquery.com/filter/
Defined in
find()
Get the descendants of each element in the current set of matched elements, filtered by a selector, jQuery object, or element.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• selectorOrHaystack?: string | Element | Cheerio<Element>
Element to look for.
Returns
The found elements.
Example
$('#fruits').find('li').length;
//=> 3
$('#fruits').find($('.apple')).length;
//=> 1
See
Defined in
first()
first<
T>(this):Cheerio<T>
Will select the first element of a cheerio object.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
Returns
Cheerio<T>
The first element.
Example
$('#fruits').children().first().text();
//=> Apple
See
Defined in
get()
get(this, i)
get<
T>(this,i):T|undefined
Retrieve one of the elements matched by the Cheerio object, at the ith
position.
Type Parameters
• T
Parameters
• this: Cheerio<T>
• i: number
Element to retrieve.
Returns
T | undefined
The element at the ith position.
Example
$('li').get(0).tagName;
//=> li
See
Defined in
get(this)
get<
T>(this):T[]
Retrieve all elements matched by the Cheerio object, as an array.
Type Parameters
• T
Parameters
• this: Cheerio<T>
Returns
T[]
All elements matched by the Cheerio object.
Example
$('li').get().length;
//=> 3
See
Defined in
has()
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
• selectorOrHaystack: string | Element | Cheerio<Element>
Element to look for.
Returns
The filtered collection.
Examples
$('ul').has('.pear').attr('id');
//=> fruits
$('ul').has($('.pear')[0]).attr('id');
//=> fruits
See
Defined in
index()
index<
T>(this,selectorOrNeedle?):number
Search for a given element from among the matched elements.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<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
Defined in
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
• T
Parameters
• this: Cheerio<T>
• selector?: AcceptedFilters<T>
Selector for the selection.
Returns
boolean
Whether or not the selector matches an element of the instance.
See
Defined in
last()
last<
T>(this):Cheerio<T>
Will select the last element of a cheerio object.
Type Parameters
• T
Parameters
• this: Cheerio<T>
Returns
Cheerio<T>
The last element.
Example
$('#fruits').children().last().text();
//=> Pear
See
Defined in
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
• T
• M
Parameters
• this: Cheerio<T>
• fn
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
Defined in
next()
Gets the next sibling of each selected element, optionally filtered by a selector.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• selector?: AcceptedFilters<Element>
If specified filter for sibling.
Returns
The next nodes.
Example
$('.apple').next().hasClass('orange');
//=> true
See
Defined in
nextAll()
Gets all the following siblings of the each selected element, optionally filtered by a selector.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• selector?: AcceptedFilters<Element>
If specified filter for siblings.
Returns
The next nodes.
Example
$('.apple').nextAll();
//=> [<li class="orange">Orange</li>, <li class="pear">Pear</li>]
$('.apple').nextAll('.orange');
//=> [<li class="orange">Orange</li>]
See
https://api.jquery.com/nextAll/
Defined in
nextUntil()
nextUntil<
T>(this,selector?,filterSelector?):Cheerio<Element>
Gets all the following siblings up to but not including the element matched by the selector, optionally filtered by another selector.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• selector?: null | AcceptedFilters<Element>
Selector for element to stop at.
• filterSelector?: AcceptedFilters<Element>
If specified filter for siblings.
Returns
The next nodes.
Example
$('.apple').nextUntil('.pear');
//=> [<li class="orange">Orange</li>]
See
https://api.jquery.com/nextUntil/
Defined in
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
• T extends AnyNode
Parameters
• this: Cheerio<T>
• match: AcceptedFilters<T>
Value to look for, following the rules above.
Returns
Cheerio<T>
The filtered collection.
Examples
$('li').not('.apple').length;
//=> 2
$('li').not(function (i, el) {
// this === el
return $(this).attr('class') === 'orange';
}).length; //=> 2
See
Defined in
parent()
Get the parent of each element in the current set of matched elements, optionally filtered by a selector.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• selector?: AcceptedFilters<Element>
If specified filter for parent.
Returns
The parents.
Example
$('.pear').parent().attr('id');
//=> fruits
See
https://api.jquery.com/parent/
Defined in
parents()
Get a set of parents filtered by selector of each element in the current
set of match elements.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• selector?: AcceptedFilters<Element>
If specified filter for parents.
Returns
The parents.
Example
$('.orange').parents().length;
//=> 2
$('.orange').parents('#fruits').length;
//=> 1
See
https://api.jquery.com/parents/
Defined in
parentsUntil()
parentsUntil<
T>(this,selector?,filterSelector?):Cheerio<Element>
Get the ancestors of each element in the current set of matched elements, up to but not including the element matched by the selector, DOM node, or cheerio object.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• selector?: null | AcceptedFilters<Element>
Selector for element to stop at.
• filterSelector?: AcceptedFilters<Element>
Optional filter for parents.
Returns
The parents.
Example
$('.orange').parentsUntil('#food').length;
//=> 1
See
https://api.jquery.com/parentsUntil/
Defined in
prev()
Gets the previous sibling of each selected element optionally filtered by a selector.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• selector?: AcceptedFilters<Element>
If specified filter for siblings.
Returns
The previous nodes.
Example
$('.orange').prev().hasClass('apple');
//=> true
See
Defined in
prevAll()
Gets all the preceding siblings of each selected element, optionally filtered by a selector.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• selector?: AcceptedFilters<Element>
If specified filter for siblings.
Returns
The previous nodes.
Example
$('.pear').prevAll();
//=> [<li class="orange">Orange</li>, <li class="apple">Apple</li>]
$('.pear').prevAll('.orange');
//=> [<li class="orange">Orange</li>]
See
https://api.jquery.com/prevAll/
Defined in
prevUntil()
prevUntil<
T>(this,selector?,filterSelector?):Cheerio<Element>
Gets all the preceding siblings up to but not including the element matched by the selector, optionally filtered by another selector.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• selector?: null | AcceptedFilters<Element>
Selector for element to stop at.
• filterSelector?: AcceptedFilters<Element>
If specified filter for siblings.
Returns
The previous nodes.
Example
$('.pear').prevUntil('.apple');
//=> [<li class="orange">Orange</li>]
See
https://api.jquery.com/prevUntil/
Defined in
siblings()
Get the siblings of each element (excluding the element) in the set of matched elements, optionally filtered by a selector.
Type Parameters
• T extends AnyNode
Parameters
• this: Cheerio<T>
• selector?: AcceptedFilters<Element>
If specified filter for siblings.
Returns
The siblings.
Example
$('.pear').siblings().length;
//=> 2
$('.pear').siblings('.orange').length;
//=> 1
See
https://api.jquery.com/siblings/
Defined in
slice()
slice<
T>(this,start?,end?):Cheerio<T>
Gets the elements matching the specified range (0-based position).
Type Parameters
• T
Parameters
• 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.
Example
$('li').slice(1).eq(0).text();
//=> 'Orange'
$('li').slice(1, 2).length;
//=> 1