Abstract
Private
constructorPrivate
_rootThe root of the document. Can be set by using the root
argument of the constructor.
Returns a copy of a section of an array. For both start and end, a negative index can be used to indicate an offset from the end of the array. For example, -2 refers to the second to last element of the array.
Optional
start: numberThe beginning index of the specified portion of the array. If start is undefined, then the slice begins at index 0.
Optional
end: numberThe end index of the specified portion of the array. This is exclusive of the element at the index 'end'. If end is undefined, then the slice extends to the end of the array.
Adds class(es) to all of the matched elements. Also accepts a function
.
$('.pear').addClass('fruit').html();
//=> <li class="pear fruit">Pear</li>
$('.apple').addClass('fruit red').html();
//=> <li class="apple fruit red">Apple</li>
The instance itself.
Optional
value: string | ((this: Element, i: number, className: string) => undefined | string)Name of new class.
Method for getting attributes. Gets the attribute value for only the first element in the matched set.
$('ul').attr('id');
//=> fruits
The attribute's value.
Name of the attribute.
Method for getting all attributes and their values of the first element in the matched set.
$('ul').attr();
//=> { id: 'fruits' }
The attribute's values.
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
.
$('.apple').attr('id', 'favorite').html();
//=> <li class="apple" id="favorite">Apple</li>
The instance itself.
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.
$('.apple').attr({ id: 'favorite' }).html();
//=> <li class="apple" id="favorite">Apple</li>
The instance itself.
Map of attribute names and values.
Method for getting data attributes, for only the first element in the matched set.
$('<div data-apple-color="red"></div>').data('apple-color');
//=> 'red'
The data attribute's value, or undefined
if the attribute does not exist.
Name of the data attribute.
Method for getting all of an element's data attributes, for only the first element in the matched set.
$('<div data-apple-color="red"></div>').data();
//=> { appleColor: 'red' }
A map with all of the data attributes.
Method for setting data attributes, for only the first element in the matched set.
const apple = $('.apple').data('kind', 'mac');
apple.data('kind');
//=> 'mac'
The instance itself.
Name of the data attribute.
The new value.
Method for setting multiple data attributes at once, for only the first element in the matched set.
const apple = $('.apple').data({ kind: 'mac' });
apple.data('kind');
//=> 'mac'
The instance itself.
Map of names to values.
Check to see if any of the matched elements have the given className
.
$('.pear').hasClass('pear');
//=> true
$('apple').hasClass('fruit');
//=> false
$('li').hasClass('pear');
//=> true
Indicates if an element has the given className
.
Name of the class.
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.
Whether or not the selector matches an element of the instance.
Optional
selector: AcceptedFilters<T>Selector for the selection.
Method for getting and setting properties. Gets the property value for only the first element in the matched set.
$('input[type="checkbox"]').prop('checked');
//=> false
$('input[type="checkbox"]').prop('checked', true).val();
//=> ok
If value
is specified the instance itself, otherwise the prop's value.
Name of the property.
Get a parsed CSS style object.
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.
With baseURI
set to 'https://example.com'
:
$('<img src="image.png">').prop('src');
//=> 'https://example.com/image.png'
Get a property of an element.
Set a property of an element.
Method for removing attributes by name
.
$('.pear').removeAttr('class').html();
//=> <li>Pear</li>
$('.apple').attr('id', 'favorite');
$('.apple').removeAttr('id class').html();
//=> <li>Apple</li>
The instance itself.
Name of the attribute.
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
.
$('.pear').removeClass('pear').html();
//=> <li class="">Pear</li>
$('.apple').addClass('red').removeClass().html();
//=> <li class="">Apple</li>
The instance itself.
Optional
name: string | ((this: Element, i: number, className: string) => undefined | string)Name of the class. If not specified, removes all elements.
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
.
$('.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>
The instance itself.
Optional
value: string | ((this: Element, i: number, className: string, stateVal?: boolean) => string)Name of the class. Can also be a function.
Optional
stateVal: booleanIf specified the state of the class.
Method for getting the value of input, select, and textarea. Note: Support
for map
, and function
has not been added yet.
$('input[type="text"]').val();
//=> input_text
The value.
Method for setting the value of input, select, and textarea. Note: Support
for map
, and function
has not been added yet.
$('input[type="text"]').val('test').html();
//=> <input type="text" value="test"/>
The instance itself.
The new value.
Get the value of a style property for the first element in the set of matched elements.
A map of all of the style properties.
Optional
names: string[]Optionally the names of the properties of interest.
Get the value of a style property for the first element in the set of matched elements.
The property value for the given name.
Set one CSS property for every matched element.
The instance itself.
Set multiple CSS properties for every matched element.
The instance itself.
A map of property names and values.
Encode a set of form elements as an array of names and values.
$('<form><input name="foo" value="bar" /></form>').serializeArray();
//=> [ { name: 'foo', value: 'bar' } ]
The serialized form.
Private
_makePrivate
Create an array of nodes, recursing into arrays and parsing strings if necessary.
The array of nodes.
Optional
elem: BasicAcceptedElems<AnyNode>Elements to make an array of.
Optional
clone: booleanOptionally clone nodes.
Insert content next to each element in the set of matched elements.
$('.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>
The instance itself.
Rest
...elems: BasicAcceptedElems<AnyNode>[] | [((this: AnyNode, i: number, html: string) => BasicAcceptedElems<AnyNode>)]Insert every element in the set of matched elements to the end of the target.
$('<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>
The instance itself.
Element to append elements to.
Insert content previous to each element in the set of matched elements.
$('.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>
The instance itself.
Rest
...elems: BasicAcceptedElems<AnyNode>[] | [((this: AnyNode, i: number, html: string) => BasicAcceptedElems<AnyNode>)]Gets an HTML content string from the first selected element.
$('.orange').html();
//=> Orange
$('#fruits').html('<li class="mango">Mango</li>').html();
//=> <li class="mango">Mango</li>
The HTML content string.
Replaces each selected element's content with the specified content.
$('.orange').html('<li class="mango">Mango</li>').html();
//=> <li class="mango">Mango</li>
The instance itself.
Insert every element in the set of matched elements after the target.
$('<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>
The set of newly inserted elements.
Element to insert elements after.
Insert every element in the set of matched elements before the target.
$('<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>
The set of newly inserted elements.
Element to insert elements before.
Insert every element in the set of matched elements to the beginning of the target.
$('<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>
The instance itself.
Element to prepend elements to.
Removes the set of matched elements from the DOM and all their children.
selector
filters the set of matched elements to be removed.
$('.pear').remove();
$.html();
//=> <ul id="fruits">
// <li class="apple">Apple</li>
// <li class="orange">Orange</li>
// </ul>
The instance itself.
Optional
selector: stringOptional selector for elements to remove.
Replaces matched elements with content
.
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>
The instance itself.
Replacement for matched elements.
Get the combined text contents of each element in the set of matched elements, including their descendants.
$('.orange').text();
//=> Orange
$('ul').text();
//=> Apple
// Orange
// Pear
The text contents of the collection.
Set the content of each element in the set of matched elements to the specified text.
$('.orange').text('Orange');
//=> <div class="orange">Orange</div>
The instance itself.
The .unwrap() function, removes the parents of the set of matched elements from the DOM, leaving the matched elements in their place.
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>
The instance itself, for chaining.
Optional
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.
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.
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>
The instance itself.
The DOM structure to wrap around all matched elements in the selection.
Abstract
Private
_makePrivate
Make a cheerio object.
The new cheerio object.
The contents of the new object.
Optional
context: BasicAcceptedElems<AnyNode>The context of the new object.
Abstract
Private
_parsePrivate
Parses some content.
A document containing the content
.
Content to parse.
Options for parsing.
Allows parser to be switched to fragment mode.
Abstract
Private
_renderOptional
xmlMode: booleanOptional
root: DocumentAdd the previous set of elements on the stack to the current set, optionally filtered by a selector.
$('li').eq(0).addBack('.orange').length;
//=> 2
The combined set.
Optional
selector: stringSelector for the elements to add.
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.
$('.orange').closest();
//=> []
$('.orange').closest('.apple');
// => []
$('.orange').closest('li');
//=> [<li class="orange">Orange</li>]
$('.orange').closest('#fruits');
//=> [<ul id="fruits"> ... </ul>]
The closest nodes.
Optional
selector: AcceptedFilters<Element>Selector for the element to find.
Gets the children of each element in the set of matched elements, including text and comment nodes.
$('#fruits').contents().length;
//=> 3
The children.
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
.
const fruits = [];
$('li').each(function (i, elem) {
fruits[i] = $(this).text();
});
fruits.join(', ');
//=> Apple, Orange, Pear
The instance itself, useful for chaining.
Function to execute.
End the most recent filtering operation in the current chain and return the set of matched elements to its previous state.
$('li').eq(0).end().length;
//=> 3
The previous state of the set of matched elements.
Reduce the set of matched elements to the one at the specified index. Use
.eq(-i)
to count backwards from the last selected element.
$('li').eq(0).text();
//=> Apple
$('li').eq(-1).text();
//=> Pear
The element at the i
th position.
Index of the element to select.
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.
$('li')
.filter(function (i, el) {
// this === el
return $(this).attr('class') === 'orange';
})
.attr('class'); //=> orange
The filtered collection.
Value to look for, following the rules above.
Iterates over a cheerio object, reducing the set of selector elements to those that match the selector or pass the function's test.
this
refers to the current element.$('li').filter('.orange').attr('class');
//=> orange
$('li')
.filter(function (i, el) {
// this === el
return $(this).attr('class') === 'orange';
})
.attr('class'); //=> orange
The filtered collection.
Value to look for, following the rules above. See AcceptedFilters.
Get the descendants of each element in the current set of matched elements, filtered by a selector, jQuery object, or element.
$('#fruits').find('li').length;
//=> 3
$('#fruits').find($('.apple')).length;
//=> 1
The found elements.
Retrieve one of the elements matched by the Cheerio object, at the i
th position.
$('li').get(0).tagName;
//=> li
The element at the i
th position.
Element to retrieve.
Retrieve all elements matched by the Cheerio object, as an array.
$('li').get().length;
//=> 3
All elements matched by the Cheerio object.
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)')
.
$('ul').has('.pear').attr('id');
//=> fruits
$('ul').has($('.pear')[0]).attr('id');
//=> fruits
The filtered collection.
Search for a given element from among the matched elements.
$('.pear').index();
//=> 2 $('.orange').index('li');
//=> 1
$('.apple').index($('#fruit, li'));
//=> 1
The index of the element.
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.
$('li')
.map(function (i, el) {
// this === el
return $(this).text();
})
.toArray()
.join(' ');
//=> "apple orange pear"
The mapped elements, wrapped in a Cheerio collection.
Function to execute.
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.
$('li').not('.apple').length;
//=> 2
$('li').not(function (i, el) {
// this === el
return $(this).attr('class') === 'orange';
}).length; //=> 2
The filtered collection.
Value to look for, following the rules above.
Gets the elements matching the specified range (0-based position).
$('li').slice(1).eq(0).text();
//=> 'Orange'
$('li').slice(1, 2).length;
//=> 1
The elements matching the specified range.
Optional
start: numberA position at which the elements begin to be selected. If negative, it indicates an offset from the end of the set.
Optional
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.
Instance of cheerio. Methods are specified in the modules. Usage of this constructor is not recommended. Please use
$.load
instead.