$ Namespace
Invoke DOM traversal and manipulation methods on Cheerio objects using the Cheerio $ namespace.
.add(element, [context]) Source (L892)
Adds new elements to the matched set.
Parameters
Name | Type | Description |
---|---|---|
element
|
String | Object | Element | A string for a selector, a Cheerio object, a DOM element, or a set of DOM elements. |
[
context
]
|
Object | Element | Optional. A Cheerio object or DOM element signifying the point in the document at which the selector should begin matching, provided that the first argument is a selector string. |
Return Value
A Cheerio object whose matched set contains the original and new elements.
Example
$body.find(".apple").add(".orange");
$body.find(".apple").add(".orange", $body.find("ul"));
$body.find(".apple").add(".orange", $body.find("ul").get(0));
$body.find(".apple").add($body.find(".orange"));
$body.find(".apple").add($body.find(".orange").get());
// [for each of the above]
// => Returns: new Cheerio object containing the `.apple` and `.orange` elements
.addBack([selector]) Source (L915)
Adds the previous set of elements on the stack to the current set, optionally filtered by a selector.
Parameters
Name | Type | Description |
---|---|---|
[
selector
]
|
String | Optional. A string for a selector to match the previous set of elements against. |
Return Value
A Cheerio object whose matched set contains the original and new elements.
Examples
$body.find(".apple").nextAll(".pear").addBack();
// => Returns: new Cheerio object containing the `.apple` and `.pear` elements
$body.find(".apple").nextAll().addBack(".pear");
// => Returns: new Cheerio object containing the `.orange` and `.pear` elements
$body.find(".orange").nextAll().addBack(".apple");
// => Returns: new Cheerio object containing the `.pear` element
.addClass(className) Source (L175)
Adds class(es) to each element in the matched set.
Parameters
Name | Type | Description |
---|---|---|
className
|
String | function | A string for one or more space-separated classes, or a function that returns one or more space-separated classes, to be added to the class attribute. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find(".pear").addClass("green");
// => Returns: original Cheerio object associated with $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear green">Pear</li>
// </ul>
$body.find("li").addClass(function(index, currentClass) {
var addedClass;
if (currentClass === "apple" || currentClass === "pear") {
addedClass = "green-" + index;
$body.find("#fruits").attr("data-id", 1);
}
return addedClass;
});
// => Returns: original Cheerio object associated with $body.find("li")
// => HTML output:
// <ul id="fruits" data-id="1">
// <li class="apple green-0" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear green-2">Pear</li>
// </ul>
.after(content) Source (L1019)
Inserts content next to each element in the matched set.
Parameters
Name | Type | Description |
---|---|---|
content
|
Object | String | A Cheerio object or a content string to be inserted after each element in the matched set. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find(".orange").after($body.find(".apple"));
// => Returns: original Cheerio object associated with $body.find(".orange")
// => HTML output:
// <ul id="fruits">
// <li class="orange">Orange</li>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="pear">Pear</li>
// </ul>
let $grape = $(tag("li", {class: "grape"}, "Grape"));
$body.find(".apple").after($grape);
// => Returns: original Cheerio object associated with $body.find(".apple")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="grape">Grape</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
$body.find("#fruits").after("test");
// => Returns: original Cheerio object associated with $body.find("#fruits")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// test
.append(content) Source (L937)
Inserts content as the last child for each element in the matched set.
Parameters
Name | Type | Description |
---|---|---|
content
|
Object | String | A Cheerio object or a content string to be appended. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find("#fruits").append($body.find(".apple"));
// => Returns: original Cheerio object associated with $body.find("#fruits")
// => HTML output:
// <ul id="fruits">
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// <li class="apple" data-which="fuji">Apple</li>
// </ul>
let $tomato = $(tag("li", {class: "tomato"}, "Tomato"));
$body.find("#fruits").append($tomato);
// => Returns: original Cheerio object associated with $body.find("#fruits")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// <li class="tomato">Tomato</li>
// </ul>
$body.find(".apple").append("test");
// => Returns: original Cheerio object associated with $body.find(".apple")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Appletest</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.appendText(str) Source (L1602)
Appends an input string to each element in the matched set. This coerces any text or any children into text, before appending the input string.
Parameters
Name | Type | Description |
---|---|---|
str
|
string | Text to be appended for each matched element. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find(".pear").appendText(", extra text");
// => Returns: original Cheerio object originally with $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear, extra text</li>
// </ul>
$body.find("ul").appendText(", extra text");
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// Apple
// Orange
// Pear
// , extra text
// </ul>
.attr(name, [value]) Source (L15)
Gets or sets attributes. Gets 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 like jQuery.
Parameters
Name | Type | Description |
---|---|---|
name
|
String | A string for an attribute name. |
[
value
]
|
String | Optional. A string for the new attribute's value. |
Return Value
A string for the value (getter), or the updated form of the original Cheerio matched-set object (setter).
Examples
$body.find('ul').attr('id');
// => Returns: "fruits"
$body.find(".apple").attr("id", "favorite");
// => Returns: original Cheerio object associated with $body.find(".apple")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji" id="favorite">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.attributes(attributes) Source (L432)
Updates the set of attributes for each element in the matched set. If an attribute in the input is undefined, it will remove that attribute from the selected nodes.
Parameters
Name | Type | Description |
---|---|---|
attributes
|
Object | Attribute-value pairs in key-value object notation. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find("ul").attributes({id: "food", "data-type": "fruits"});
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="food" data-type="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
$body.find("ul").attributes({id: undefined});
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.before(content) Source (L1094)
Inserts content previous to each element in the matched set.
Parameters
Name | Type | Description |
---|---|---|
content
|
Object | String | A Cheerio object or a content string to be inserted before each element in the matched set. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find(".orange").before($body.find(".pear"));
// => Returns: original Cheerio object associated with $body.find(".orange")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="pear">Pear</li>
// <li class="orange">Orange</li>
// </ul>
let $grape = $(tag("li", {class: "grape"}, "Grape"));
$body.find(".pear").before($grape);
// => Returns: original Cheerio object associated with $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="grape">Grape</li>
// <li class="pear">Pear</li>
// </ul>
$body.find("#fruits").before("test");
// => Returns: original Cheerio object associated with $body.find("#fruits")
// => HTML output:
// test
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.children([selector]) Source (L629)
Gets the children of the first element in the matched set.
Parameters
Name | Type | Description |
---|---|---|
[
selector
]
|
String | Optional. A string for a selector to match elements against. |
Return Value
A Cheerio object containing the children of the first element in the matched set.
Examples
$body.find("#fruits").children();
// => Returns: new Cheerio object containing the `.apple`, `.orange`, and
// `.pear` elements
$body.find("#fruits").children(".pear");
// => Returns: new Cheerio object containing the `.pear` element
.clone() Source (L1402)
Clones the Cheerio matched-set object.
Return Value
A new, distinct Cheerio object, separate from the original matched-set object.
Example
let $pearClone = $body.find(".pear").clone();
// => Returns: new Cheerio object for the matched set of elements contained
by the original Cheerio object.
$body.find("#fruits").append($pearClone);
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear" style="line-height: 12px">Pear</li>
// </ul>
.closest(selector) Source (L433)
Retrieves the first element that matches the selector by traversing up through the current element's ancestors in the DOM tree, for each element in the matched set.
Parameters
Name | Type | Description |
---|---|---|
selector
|
String | Object | A string for a selector, or a Cheerio object, indicating where to stop matching ancestor elements. |
Return Value
A Cheerio object for the first element matching the selector.
Example
$body.find(".apple").closest("body");
$body.find(".apple").closest($body);
// [for each of the above]
// => Returns: new Cheerio object containing the `body` element
.contents() Source (L647)
Gets the children of each element in the matched set, including text and comment nodes.
Return Value
A Cheerio object containing the children (including text and comment nodes) of the first element in the matched set.
Example
$body.find("#fruits").contents();
// => Returns: new Cheerio object containing the `.apple`, `.orange`, and
// `.pear` elements, as well as the whitespace text nodes in between and
// outside of each of them.
.create(element, position, [options]) Source (L1085)
Creates a new element for each of the elements in the matched set, at the specified position.
Parameters
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
element
|
String | A string for an element name. | ||||||
position
|
String | A string for the position where the element should be created ("top", "bottom", "before", or "after"). | ||||||
[
options
]
|
Object |
Optional.
An object containing a list of HTML attribute-value
pairs.
Properties
|
Return Value
The updated form of the original Cheerio matched-set object.
Examples
// Create and place an element and move it to a position
$body.find("ul").create("li", "top");
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li></li>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// Create and place an element with attributes passed in
$body.find("ul").create("li", "top", {content: "Content of the li", id: "test"});
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li id="test">Content of the li</li>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// "Create" a new element using tag() (i.e. move it from memory to a position)
$body.find("ul").create($(tag("li", {id: "test"})), "top");
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li id="test"></li>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.createAfter(element, [options]) Source (L1248)
Creates a new element after each element in the matched set. Alias for the legacy .create_after() method.
Parameters
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
element
|
String | A string for an element name. | ||||||
[
options
]
|
Object |
Optional.
An object containing a list of HTML attribute-value
pairs.
Properties
|
Return Value
The updated form of the original Cheerio matched-set object.
Examples
// Create and place an element and move it to a position
$body.find("ul").createAfter("div");
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// <div></div>
// Create and place an element with attributes passed in
$body.find("ul").createAfter("div", {content: "Content of the div", id: "test"});
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// <div id="test">Content of the div</div>
// "Create" a new element using tag() (i.e. move it from memory to a position)
$body.find("ul").createAfter($(tag("div", {id: "test"})));
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// <div id="test"></div>
.createBefore(element, [options]) Source (L1299)
Creates a new element before each element in the matched set. Alias for the legacy .create_before() method.
Parameters
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
element
|
String | A string for an element name. | ||||||
[
options
]
|
Object |
Optional.
An object containing a list of HTML attribute-value
pairs.
Properties
|
Return Value
The updated form of the original Cheerio matched-set object.
Examples
// Create and place an element and move it to a position
$body.find("ul").createBefore("div");
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <div></div>
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// Create and place an element with attributes passed in
$body.find("ul").createBefore("div", {content: "Content of the div", id: "test"});
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <div id="test">Content of the div</div>
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// "Create" a new element using tag() (i.e. move it from memory to a position)
$body.find("ul").createBefore($(tag("div", {id: "test"})));
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <div id="test"></div>
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.createBottom(element, [options]) Source (L1197)
Creates a new element at the bottom of each element in the matched set. Alias for the legacy .create_bottom() method.
Parameters
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
element
|
String | A string for an element name. | ||||||
[
options
]
|
Object |
Optional.
An object containing a list of HTML attribute-value
pairs.
Properties
|
Return Value
The updated form of the original Cheerio matched-set object.
Examples
// Create and place an element and move it to a position
$body.find("ul").createBottom("li");
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// <li></li>
// </ul>
// Create and place an element with attributes passed in
$body.find("ul").createBottom("li", {content: "Content of the li", id: "test"});
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// <li id="test">Content of the li</li>
// </ul>
// "Create" a new element using tag() (i.e. move it from memory to a position)
$body.find("ul").createBottom($(tag("li", {id: "test"})));
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// <li id="test"></li>
// </ul>
.createTop(element, [options]) Source (L1146)
Creates a new element at the top of each element in the matched set. Alias for the legacy .create_top() method.
Parameters
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
element
|
String | A string for an element name. | ||||||
[
options
]
|
Object |
Optional.
An object containing a list of HTML attribute-value
pairs.
Properties
|
Return Value
The updated form of the original Cheerio matched-set object.
Examples
// Create and place an element and move it to a position
$body.find("ul").createTop("li");
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li></li>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// Create and place an element with attributes passed in
$body.find("ul").createTop("li", {content: "Content of the li", id: "test"});
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li id="test">Content of the li</li>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// "Create" a new element using tag() (i.e. move it from memory to a position)
$body.find("ul").createTop($(tag("li", {id: "test"})));
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li id="test"></li>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.css([properties], [values]) Source (L1317)
Gets the value of a style property for the first element in the set of matched elements or set one or more CSS properties for every matched element.
Parameters
Name | Type | Description |
---|---|---|
[
properties
]
|
String | Array | Object | Optional. A string for the property name (getter), an array of property names (getter), or an object of property-value pairs (setter). Property names must be in the CSS formats, e.g. `background-color` and not `backgroundColor`. Additionally, properties queried using the getter must be consistent with how they may have been assigned with the setter, even if they are defined in the CSS specification as sub-properties. |
[
values
]
|
String | function | Optional. A string for a property value (in the case that the first argument is a property name string, turning this from a getter to a setter), or function returning the value to set (which can take an optional index argument and an optional value argument, which is the old property value). |
Return Value
A string for the CSS property value (string getter), or the updated form of the original Cheerio matched-set object (setter).
Examples
$body.find(".pear").css({
"background-color": "green",
"font-size": "12px"
});
// => Returns: original updated Cheerio object associated with
// $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear" style="background: green; font-size: 12px">Pear</li>
// </ul>
$body.find(".pear").css("background");
// => Returns: undefined
$body.find(".pear").css("backgroundColor");
// => Returns: undefined
$body.find(".pear").css("background-color");
// => Returns: "green"
$body.find(".pear").css(["background-color", "font-size"]);
// => Returns:
// {
// background-color: "green",
// "fontSize": "12px"
// }
$body.find(".pear").css("line-height", "10px");
// => Returns: original updated Cheerio object associated with
// $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear" style="line-height: 10px">Pear</li>
// </ul>
$body.find(".pear").css("line-height", function(i, value) {
return parseFloat(value) * 1.2 + "px";
});
// => Returns: original updated Cheerio object associated with
// $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear" style="line-height: 12px">Pear</li>
// </ul>
.data([name], [value]) Source (L41)
Gets or sets data bound to the first element in the matched set. The getter outputs an object containing the values for the HTML data-attributes (read-only), as well as the values set by using the setter (read/write).
Parameters
Name | Type | Description |
---|---|---|
[
name
]
|
String | Optional. A string for a data attribute name. |
[
value
]
|
String | Optional. A string for the new value for the data attribute in the first argument. |
Return Value
An object containing the attribute-value pairs for the data bound to the first element in the matched set (empty getter), a string containing the value for the given input attribute of the first element in the matched set (nonempty getter), or the updated form of the original Cheerio matched-set object (setter).
Example
let $apple = $body.find(".apple");
$apple.data();
// => Returns: {which: "fuji"}
$apple.data("which");
// => Returns: "fuji"
$apple.data("weight", 0.5);
// => Returns: original Cheerio object associated with $body.find(".apple")
$apple.data("which", "gala");
// => Returns: original Cheerio object associated with $body.find(".apple")
// => Note: no data change, since it existed as an original HTML data-attribute
$apple.data();
// => Returns: {which: "fuji", weight: 0.5}
$apple.data("weight", 0.7);
// => Returns: original Cheerio object associated with $body.find(".apple")
$apple.data();
// => Returns: {which: "fuji", weight: 0.7}
// => Note: changes because weight was not an original HTML data-attribute
.domManipulator(element, position, [options]) Source (L970)
Manipulates the DOM elements around each of the elements in the matched set, by creating new or moving existing elements around them. Generic wrapper of the .create() and .move() methods (see for more details on positioning specifics).
Parameters
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
element
|
String | Object | A string for an element name, or a Cheerio object containing a matched set | ||||||
position
|
String | A string for the position where the element should be created ("top", "bottom", "before", or "after"). | ||||||
[
options
]
|
Object |
Optional.
An object containing a list of HTML attribute-value
pairs.
Properties
|
Return Value
The updated form of the original Cheerio matched-set object.
Examples
// Create and place an element and move it to a position
$body.find("ul").domManipulator("li", "top");
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li></li>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// Create and place an element with attributes passed in
$body.find("ul").domManipulator("li", "top", {content: "Content of the li", id: "test"});
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li id="test">Content of the li</li>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// Move an existing element to a position
$body.find(".pear").domManipulator($body.find(".orange"), "after");
// => Returns: original Cheerio object originally with $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="pear">Pear</li>
// <li class="orange">Orange</li>
// </ul>
// "Create" a new element using tag() (i.e. move it from memory to a position)
$body.find(".pear").domManipulator($(tag("li", {id: "test"})), "after");
// => Returns: original Cheerio object originally with $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// <li id="test"></li>
// </ul>
.dumpTable() Source (L803)
Converts selected tables into a div structure. It removes the original table attributes and adds classnames corresponding to its former node name.
Return Value
The updated form of the original Cheerio matched-set object.
Example
let $ul = $body.find("ul");
let $table = $(tag("table"));
let $thead = $(tag("thead"));
let $tr1 = $(tag("tr"));
let $th = $(tag("th"));
let $tbody = $(tag("tbody"));
let $tr2 = $(tag("tr"));
let $td= $(tag("td"));
let $tfoot = $(tag("tfoot"));
let $tableClone;
$table.append($thead.append($tr1.append($th)));
$table.append($tbody.append($tr2.append($td)));
$table.append($tfoot);
// create a clone to compare dumped and non-dumped tables side-by-side
$tableClone = $table.clone();
$tableClone.addClass("table-clone");
$ul.after($table);
$ul.after($tableClone);
$tableClone.dumpTable();
// => Returns: original Cheerio object associated with $tableClone
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// <div class="table-clone mw-was-table">
// <div class="mw-was-thead">
// <div class="mw-was-th"></div>
// </div>
// <div class="mw-was-tbody">
// <div class="mw-was-td></div>
// </div>
// <div class="mw-was-tfoot"></div>
// </div>
// <table>
// <thead>
// <th></th>
// </thead>
// <tbody>
// <td></td>
// </tbody>
// <tfoot></tfoot>
// </table>
.dumpTables() Source (L732)
Dumps all tables under each element of the matched set.
Return Value
The updated form of the original Cheerio matched-set object.
Example
let $ul = $body.find("ul");
let $table = $(tag("table"));
let $thead = $(tag("thead"));
let $tr1 = $(tag("tr"));
let $th = $(tag("th"));
let $tbody = $(tag("tbody"));
let $tr2 = $(tag("tr"));
let $td= $(tag("td"));
let $tfoot = $(tag("tfoot"));
let $tableClone;
$table.append($thead.append($tr1.append($th)));
$table.append($tbody.append($tr2.append($td)));
$table.append($tfoot);
// create a clone to see that all given tables get dumped
$tableClone = $table.clone();
$tableClone.addClass("table-clone");
$ul.after($table);
$ul.after($tableClone);
$body.dumpTables();
// => Returns: original Cheerio object associated with $body
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// <div class="table-clone mw-was-table">
// <div class="mw-was-thead">
// <div class="mw-was-th"></div>
// </div>
// <div class="mw-was-tbody">
// <div class="mw-was-td></div>
// </div>
// <div class="mw-was-tfoot"></div>
// </div>
// <div class="mw-was-table">
// <div class="mw-was-thead">
// <div class="mw-was-th"></div>
// </div>
// <div class="mw-was-tbody">
// <div class="mw-was-td></div>
// </div>
// <div class="mw-was-tfoot"></div>
// </div>
.each(function) Source (L663)
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.
Parameters
Name | Type | Description |
---|---|---|
function
|
function | A callback function to run for each element in the matched set, optionally taking in an Integer `index` argument and a DOM element `element` argument (for its `this`). |
Return Value
The updated form of the original Cheerio matched-set object.
Example
$body.find("li").each(function(index) {
$(this).attr("id", "fruit-" + index);
});
// => Returns: original Cheerio object associated with $body.find("li")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji" id="fruit-0">Apple</li>
// <li class="orange" id="fruit-1">Orange</li>
// <li class="pear" id="fruit-2">Pear</li>
// </ul>
.empty() Source (L1221)
Empties each element in the matched set, removing all their children, including text nodes.
Return Value
The updated form of the original Cheerio matched-set object.
Example
$body.find(".pear").empty();
// => Returns: original Cheerio object associated with $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear"></li>
// </ul>
.end() Source (L878)
Ends the most recent filtering operation in the current chain and return the set of matched elements to its previous state.
Return Value
A Cheerio object for the set of matched elements at the previous state.
Example
$body.find("li").eq(0).end();
// => Returns: original Cheerio object associated with $body.find("li")
.eq(i) Source (L815)
Reduces the set of matched elements to the one at the specified index. Use .eq(-i) to count backwards from the last selected element.
Parameters
Name | Type | Description |
---|---|---|
i
|
Integer | An integer for the specified index to match. |
Return Value
A new Cheerio object containing the specified element of the original matched set.
Examples
$body.find("li").eq(2);
// => Returns: new Cheerio object contining the `.pear` element
$body.find("li").eq(-3);
// => Returns: new Cheerio object contining the `.apple` element
.filter(filter) Source (L713)
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.
Parameters
Name | Type | Description |
---|---|---|
filter
|
String | Object | function | A string containing a selector, a Cheerio object, or a function used as a test (with `this` as the current DOM element) for each element in the set to match. each element in the set, |
Return Value
A new Cheerio object containing the set of elements in the original matched set, reduced by the filter.
Example
$body.find("li").filter(".orange");
$body.find("li").filter($body.find(".orange"));
$body.find("li").filter(function(i, el) {
return $(this).attr("class").indexOf("orange") > -1;
});
// [for each of the above]
// => Returns: new Cheerio object containing the `.orange` element
.find(filter) Source (L351)
Retrieves the descendants of each element in the current set of matched elements, filtered by a selector or Cheerio object.
Parameters
Name | Type | Description |
---|---|---|
filter
|
String | Object | A string for a selector, or a Cheerio object, to match elements against. |
Return Value
A Cheerio object containing a new matched set of elements.
Example
$body.find("ul");
$body.find($body.find("ul"));
// [for each of the above]
// => Returns: new Cheerio object with a set that matches all `ul` elements
// found under the body element subtree
.first() Source (L789)
Selects the first element of a matched set.
Return Value
A new Cheerio object containing the first element of the original matched set.
Example
$body.find("li").first();
// => Returns: new Cheerio object containing the `.apple` element
.get([i]) Source (L833)
Retrieves the DOM elements matched by the Cheerio object. If an index is specified, retrieve one of the elements matched by the Cheerio object.
Parameters
Name | Type | Description |
---|---|---|
[
i
]
|
Integer | Optional. An integer for the specified index to match. If empty, gets all DOM elements that match. |
Return Value
An array containing the DOM elements associated with the Cheerio object (empty argument), or the DOM element itself (specified index).
Examples
$body.find("li").get();
// => Returns: new array of DOM elements associated with the `.apple`, `.orange`,
// and `.pear` elements
$body.find("li").get(0);
// => Returns: DOM element associated with the `.apple` element
.has(filter) Source (L770)
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
Name | Type | Description |
---|---|---|
filter
|
String | Element | A string containing a selector, or a DOM element, for each element in the set to match. |
Return Value
A new Cheerio object containing the set of elements matching the filter.
Example
$body.find("ul").has(".pear");
$body.find("ul").has($body.find(".pear")[0]);
// [for each of the above]
// => Returns: new Cheerio object containing the `ul` element
.hasClass(className) Source (L160)
Checks whether any of the elements in the matched set has a given class name.
Parameters
Name | Type | Description |
---|---|---|
className
|
String | A string for the name of the class to be checked. |
Return Value
A Boolean for whether any elements in the matched set has the input class name.
Example
$body.find("li").hasClass("pear");
// => Returns: true
.html([content]) Source (L1240)
Gets an HTML content string from the first selected element. If content is specified, each selected element's content is replaced by the new input content.
Parameters
Name | Type | Description |
---|---|---|
[
content
]
|
String | Optional. An optional string to change this method from a getter to a setter, setting the new HTML content of the first element in the matched set. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find("#fruits").html();
// => Returns:
// "
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// "
$body.find("#fruits").html("<li>None</li>");
// => Returns: original updated Cheerio object associated with
// $body.find("#fruits")
// => HTML output:
// <ul id="fruits">
// <li>None</li>
// </ul>
.index([selector]) Source (L855)
Searches for a given element from among the matched elements.
Parameters
Name | Type | Description |
---|---|---|
[
selector
]
|
String | Object | Optional. A string for a selector or a Cheerio object to search for. |
Return Value
The position of the first element within the Cheerio object relative to its sibling elements. Returns -1 if it's not found.
Examples
$body.find(".pear").index();
$body.find(".pear").index("li");
$body.find("li").index($body.find(".pear"));
// [for each of the above]
// => Returns: 2
$body.find(".pear").index("div");
$body.find(".pear").index($body.find("li"));
// [for each of the above]
// => Returns: -1
.insertAfter(target) Source (L1060)
Inserts every element in the set of matched elements after the target.
Parameters
Name | Type | Description |
---|---|---|
target
|
String | Object | A string for a selector or a Cheerio object to insert the set of matched elements after. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find(".apple").insertAfter(".orange");
$body.find(".apple").insertAfter($body.find(".orange"));
// [for each of the above]
// => Returns: original Cheerio object associated with $body.find(".apple")
// => HTML output:
// <ul id="fruits">
// <li class="orange">Orange</li>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="pear">Pear</li>
// </ul>
let $grape = $(tag("li", {class: "grape"}, "Grape"));
$grape.insertAfter($body.find(".apple"));
// => Returns: original Cheerio object containing the `.grape` element
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="grape">Grape</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.insertBefore(target) Source (L1135)
Inserts every element in the set of matched elements before the target.
Parameters
Name | Type | Description |
---|---|---|
target
|
String | Object | A string for a selector or a Cheerio object to insert the set of matched elements before. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find(".pear").insertBefore(".orange");
$body.find(".pear").insertBefore($body.find(".orange"));
// [for each of the above]
// => Returns: original Cheerio object associated with $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="pear">Pear</li>
// <li class="orange">Orange</li>
// </ul>
let $grape = $(tag("li", {class: "grape"}, "Grape"));
$grape.insertBefore($body.find(".pear"));
// => Returns: original Cheerio object containing the `.grape` element
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="grape">Grape</li>
// <li class="pear">Pear</li>
// </ul>
.is(className) Source (L310)
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. When using a predicate function, the function is executed in the context of the selected element, so this refers to the current element.
Parameters
Name | Type | Description |
---|---|---|
className
|
String | Object | function | A string for a selector, another Cheerio object, or a callback function (whose this refers to the current DOM element) to test against every element in the matched set. |
Return Value
A Boolean for whether any elements in the matched set matches with the input selector, object, or function.
Example
$body.find("[data-which='fuji']").is(".apple");
$body.find("li").is(".apple");
$body.find("li").is($body.find(".apple"));
$body.find("li").is(function() {
return $body.find("[data-which='fuji']").length;
});
// [for each of the above]
// => Returns: true
.last() Source (L802)
Selects the last element of a matched set.
Return Value
A new Cheerio object containing the last element of the original matched set.
Example
$body.find("li").last();
// => Returns: new Cheerio object containing the `.pear` element
.makeToggler(options) Source (L1639)
Creates a Uranium toggler using toggler-specific data-attributes and new class names.
Parameters
Name | Type | Description | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options
|
Object |
An object containing specified toggler options.
Properties
|
Return Value
The updated form of the original Cheerio matched-set object.
Examples
// Simple Toggler
let $button = $(tag("a", {href: "#"}, "Fruits"));
let $wrapper;
let $pageContent;
$body.find("ul").wrap("div", {class: "wrapper"});
$wrapper = $body.find(".wrapper");
$wrapper.prepend($button);
$wrapper.wrap("div", {id: "pageContent"});
$pageContent = $body.find("#pageContent");
$pageContent.makeToggler({
container: ".wrapper",
button: "a",
content: "ul"
});
// => Returns: original Cheerio object containing the `#pageContent` element
// => HTML output:
// <div id="pageContent" class="mw-toggler-main-wrap">
// <div class="wrapper mw-toggle-depth-1 mw-toggler-container mw-default-toggler" data-ur-set="toggler">
// <a href="#" class="mw-toggler-button" data-ur-toggler-component="button" data-ur-state="disabled">Fruits</a>
// <ul id="fruits" class="mw-toggler-content" data-ur-toggler-component="content" data-ur-state="disabled">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// </div>
// </div>
// Toggler with skin
let $button = $(tag("a", {href: "#"}, "Fruits"));
let $wrapper;
let $pageContent;
$body.find("ul").wrap("div", {class: "wrapper"});
$wrapper = $body.find(".wrapper");
$wrapper.prepend($button);
$wrapper.wrap("div", {id: "pageContent"});
$pageContent = $body.find("#pageContent");
$pageContent.makeToggler({
container: ".wrapper",
button: "a",
content: "ul",
skin: "mw-blue-toggler"
});
// => Returns: original Cheerio object containing the `#pageContent` element
// => HTML output:
// <div id="pageContent" class="mw-toggler-main-wrap mw-blue-toggler-wrap">
// <div class="wrapper mw-toggle-depth-1 mw-toggler-container mw-default-toggler mw-blue-toggler" data-ur-set="toggler">
// <a href="#" class="mw-toggler-button" data-ur-toggler-component="button" data-ur-state="disabled">Fruits</a>
// <ul id="fruits" class="mw-toggler-content" data-ur-toggler-component="content" data-ur-state="disabled">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// </div>
// </div>
// Toggler with viewMoreText and wrapLink
let $button = $(tag("a", {href: "/fruits"}, "Fruits"));
let $wrapper;
let $pageContent;
$body.find("ul").wrap("div", {class: "wrapper"});
$wrapper = $body.find(".wrapper");
$wrapper.prepend($button);
$wrapper.wrap("div", {id: "pageContent"});
$pageContent = $body.find("#pageContent");
$pageContent.makeToggler({
container: ".wrapper",
button: "a",
content: "ul",
wrapLink: "li",
viewMoreText: "View all"
});
$pageContent.find(".mw-toggler-container").children("div").attributes({
class: "mw-toggler-button",
"data-ur-toggler-component": "button"
});
// => Returns: original Cheerio object containing the `#pageContent` element
// => HTML output:
// <div id="pageContent" class="mw-toggler-main-wrap">
// <div class="wrapper mw-toggle-depth-1 mw-toggler-container mw-default-toggler" data-ur-set="toggler">
// <div data-ur-toggler-component="button">Fruits</div>
// <ul id="fruits" class="mw-toggler-content" data-ur-toggler-component="content" data-ur-state="disabled">
// <li class="mw-wrap-link-toggler">
// <a href="/fruits">View all</a>
// </li>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// </div>
// </div>
// Toggler with keepOpened
let $button = $(tag("a", {href: "#"}, "Fruits"));
let $wrapper;
let $pageContent;
$body.find("ul").wrap("div", {class: "wrapper"});
$wrapper = $body.find(".wrapper");
$wrapper.prepend($button);
$wrapper.wrap("div", {id: "pageContent"});
$pageContent = $body.find("#pageContent");
$pageContent.makeToggler({
container: ".wrapper",
button: "a",
content: "ul",
keepOpened: true
});
// => Returns: original Cheerio object containing the `#pageContent` element
// => HTML output:
// <div id="pageContent" class="mw-toggler-main-wrap mw-blue-toggler-wrap">
// <div class="wrapper mw-toggle-depth-1 mw-toggler-container mw-default-toggler">
// <a href="#" class="mw-toggler-button">Fruits</a>
// <ul id="fruits" class="mw-toggler-content">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// </div>
// </div>
.map(function) Source (L690)
Passes 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. As the method invokation returns a jQuery object, it's common to call .get() to work with a basic array instead.
Parameters
Name | Type | Description |
---|---|---|
function
|
function | A function invoked for each element in the matched set, optionally taking in an Integer `index` argument and a DOM element `element` argument (for its `this`). |
Return Value
A new Cheerio object containing the return values.
Example
$body.find("li").map(function(i, el) {
return $(this).text();
}).get();
// => Returns: ["Apple", "Orange", "Pear"]
.move(element, position, [options]) Source (L1350)
Moves all elements in an input matched set to a specified position of each element in the selected matched set. If there's more than one element in the matched set for the target, each "moved" element is duplicated.
Parameters
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
element
|
Object | A Cheerio object containing a matched set. | ||||||
position
|
String | A string for a position where the element should be moved ("top", "bottom", "before", or "after"). | ||||||
[
options
]
|
Object |
Optional.
An object containing a list of HTML attribute-value
pairs to add to or replace any existing set of attributes.
Properties
|
Return Value
The updated form of the original Cheerio matched-set object.
Examples
// Move an existing element to a position
$body.find(".pear").move($body.find(".orange"), "after");
// => Returns: original Cheerio object originally with $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// Move a new element from memory to a position
$body.find("ul").move($(tag("li", {id: "test"})), "bottom");
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// <li id="test"></li>
// </ul>
.moveAfter(element, [options]) Source (L1483)
Moves all elements in an input matched set after each element in the selected matched set. If there's more than one element in the selected matched set, each "moved" element is duplicated. Alias for the legacy .move_after() method.
Parameters
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
element
|
Object | A Cheerio object containing a matched set. | ||||||
[
options
]
|
Object |
Optional.
An object containing a list of HTML attribute-value
pairs to add to or replace any existing set of attributes.
Properties
|
Return Value
The updated form of the original Cheerio matched-set object.
Examples
// Move an existing element to a position
$body.find(".pear").moveAfter($body.find(".orange"));
// => Returns: original Cheerio object originally with $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="pear">Pear</li>
// <li class="orange">Orange</li>
// </ul>
// Move a new element from memory to a position
$body.find("ul").moveAfter($(tag("div", {id: "test"})));
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// <div id="test"></div>
.moveBefore(element, [options]) Source (L1524)
Moves all elements in an input matched set before each element in the selected matched set. If there's more than one element in the selected matched set, each "moved" element is duplicated. Alias for the legacy .move_before() method.
Parameters
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
element
|
Object | A Cheerio object containing a matched set. | ||||||
[
options
]
|
Object |
Optional.
An object containing a list of HTML attribute-value
pairs to add to or replace any existing set of attributes.
Properties
|
Return Value
The updated form of the original Cheerio matched-set object.
Examples
// Move an existing element to a position
$body.find(".pear").moveBefore($body.find(".apple"));
// => Returns: original Cheerio object originally with $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="orange">Orange</li>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="pear">Pear</li>
// </ul>
// Move a new element from memory to a position
$body.find("ul").moveBefore($(tag("div", {id: "test"})));
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <div id="test"></div>
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.moveBottom(element, [options]) Source (L1442)
Moves all elements in an input matched set to the bottom of each element in the selected matched set. If there's more than one element in the selected matched set, each "moved" element is duplicated. Alias for the legacy .move_bottom() method.
Parameters
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
element
|
Object | A Cheerio object containing a matched set. | ||||||
[
options
]
|
Object |
Optional.
An object containing a list of HTML attribute-value
pairs to add to or replace any existing set of attributes.
Properties
|
Return Value
The updated form of the original Cheerio matched-set object.
Examples
// Move an existing element to a position
$body.find("ul").moveBottom($body.find(".orange"));
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="pear">Pear</li>
// <li class="orange">Orange</li>
// </ul>
// Move a new element from memory to a position
$body.find("ul").moveBottom($(tag("li", {id: "test"})));
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// <li id="test"></li>
// </ul>
.moveTop(element, [options]) Source (L1401)
Moves all elements in an input matched set to the top of each element in the selected matched set. If there's more than one element in the selected matched set, each "moved" element is duplicated. Alias for the legacy .move_top() method.
Parameters
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
element
|
Object | A Cheerio object containing a matched set. | ||||||
[
options
]
|
Object |
Optional.
An object containing a list of HTML attribute-value
pairs to add to or replace any existing set of attributes.
Properties
|
Return Value
The updated form of the original Cheerio matched-set object.
Examples
// Move an existing element to a position
$body.find("ul").moveTop($body.find(".orange"));
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li class="orange">Orange</li>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="pear">Pear</li>
// </ul>
// Move a new element from memory to a position
$body.find("ul").moveTop($(tag("li", {id: "test"})));
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li id="test"></li>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.name(tagName) Source (L140)
Changes the node names of each element in the matched set.
Parameters
Name | Type | Description |
---|---|---|
tagName
|
string | A string for the new tag name. |
Return Value
The updated form of the original Cheerio matched-set object.
Example
$body.find("ul").name("ol");
// => Returns: original Cheerio object originally associated with
// $body.find("ul") (which is now the ol)
// => HTML output:
// <ol id="fruits">
// <li class="apple" data-which="florina">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ol>
.next([selector]) Source (L451)
Gets the next sibling of the first element in the matched set, optionally filtered by a selector.
Parameters
Name | Type | Description |
---|---|---|
[
selector
]
|
String | Optional. A string for a selector to match elements against. |
Return Value
A Cheerio object containing the immediate next sibling for the first element in the original matched set.
Examples
$body.find(".apple").next();
$body.find(".apple").next(".orange");
// [for each of the above]
// => Returns: new Cheerio object containing the `.orange` element
$body.find(".apple").next(".pear");
// => Returns: new empty Cheerio object
.nextAll([selector]) Source (L471)
Gets all of the following siblings of the first selected element, optionally filtered by a selector.
Parameters
Name | Type | Description |
---|---|---|
[
selector
]
|
String | Optional. A string for a selector to match elements against. |
Return Value
A Cheerio object containing all the following siblings for the first element in the original matched set.
Examples
$body.find(".apple").nextAll();
// => Returns: new Cheerio object containing the `.orange` and `.pear` elements
$body.find(".apple").nextAll(".pear");
// => Returns: new Cheerio object containing the `.pear` element
.nextUntil(selector, [filter]) Source (L489)
Gets all of the following siblings of the first selected element, up to (but not including) the element matched by the selector, optionally filtered by another selector. If the selector argument passed in does not represent any known elements, or if no selector argument is passed, then this functions like `.nextAll()`.
Parameters
Name | Type | Description |
---|---|---|
selector
|
String | Object | A string for a selector, or a Cheerio object, indicating where to stop matching subsequent elements. |
[
filter
]
|
String | Optional. A string for a selector to match elements against. |
Return Value
A Cheerio object containing all the following siblings (up to the specified selector) for the first element in the original matched set.
Examples
$body.find(".apple").nextUntil(".pear");
$body.find(".apple").nextUntil(".pear", "li");
// [for each of the above]
// => Returns: new Cheerio object containing the `.orange` element
$body.find(".apple").nextUntil(".pear", "div");
// => Returns: new empty Cheerio object
$body.find(".apple").nextUntil("div");
// => Returns: new Cheerio object containing the `.orange` and `.pear` elements
.not(filter) Source (L741)
Removes 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.
Parameters
Name | Type | Description |
---|---|---|
filter
|
String | Object | function | A string containing a selector, a Cheerio object, or a function used as a test (with `this` as the current DOM element) for each element in the set to match. each element in the set, |
Return Value
A new Cheerio object containing the set of elements not in the original matched set, distinguished by the filter.
Example
$body.find("li").not(".apple");
$body.find("li").not($body.find(".apple"));
$body.find("li").not(function(i, el) {
return $(this).attr("class").indexOf("apple") > -1;
});
// [for each of the above]
// => Returns: new Cheerio object containing the `.orange` and `.pear` elements
.parent([filter]) Source (L369)
Retrieves the parent of each element in the current set of matched elements, optionally filtered by a selector.
Parameters
Name | Type | Description |
---|---|---|
[
filter
]
|
String | Object | Optional. A string for a selector, or a Cheerio object, to match elements against. |
Return Value
A Cheerio object containing a new matched set of elements.
Examples
$body.find(".apple").parent();
$body.find(".apple").parent("#fruits");
$body.find("li").parent("#fruits");
// [for each of the above]
// => Returns: new Cheerio object containing the `#fruits` parent element
// => Note: the last example returns exactly the same object as the above two.
// It does _not_ return an object with three duplicated #fruits elements.
$body.find(".apple").parent("div");
// => Returns: new empty Cheerio object
.parents([filter]) Source (L392)
Retrieves the set of ancestor of each element in the current set of matched elements, optionally filtered by a selector.
Parameters
Name | Type | Description |
---|---|---|
[
filter
]
|
String | Object | Optional. A string for a selector, or a Cheerio object, to match elements against. |
Return Value
A Cheerio object containing a new matched set of elements.
Examples
$body.find(".apple").parents();
// => Returns: new Cheerio object containing the `ul`, `body`, and `html`
// elements
$body.find(".apple").parents("body");
// => Returns: new Cheerio object containing the `body` element
.parentsUntil(selector, [filter]) Source (L411)
Retrieves the set of ancestor of each element in the current set of matched elements, up to (but not including) the element matched by the selector or Cheerio object, optionally filtered by a selector.
Parameters
Name | Type | Description |
---|---|---|
selector
|
String | Object | A string for a selector, or a Cheerio object, indicating where to stop matching ancestor elements. |
[
filter
]
|
String | Optional. A string for a selector to match elements against. |
Return Value
A Cheerio object containing a new matched set of elements.
Examples
$body.find(".apple").parentsUntil("html");
$body.find(".apple").parentsUntil($html);
// [for each of the above]
// => Returns: new Cheerio object containing the `ul` and `body` elements
$body.find(".apple").parentsUntil("html", "#fruits");
// => Returns: new Cheerio object containing the `#fruits` element
.prepend(content) Source (L978)
Inserts content as the first child for each element in the matched set.
Parameters
Name | Type | Description |
---|---|---|
content
|
Object | String | A Cheerio object or a content string to be prepended. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find("#fruits").prepend($body.find(".pear"));
// => Returns: original Cheerio object associated with $body.find("#fruits")
// => HTML output:
// <ul id="fruits">
// <li class="pear">Pear</li>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// </ul>
let $tomato = $(tag("li", {class: "tomato"}, "Tomato"));
$body.find("#fruits").prepend($tomato);
// => Returns: original Cheerio object associated with $body.find("#fruits")
// => HTML output:
// <ul id="fruits">
// <li class="tomato">Tomato</li>
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
$body.find(".apple").prepend("test");
// => Returns: original Cheerio object associated with $body.find(".apple")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">testApple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.prependText(str) Source (L1565)
Prepends an input string to each element in the matched set. This coerces any text or any children into text, before prepending the input string.
Parameters
Name | Type | Description |
---|---|---|
str
|
string | Text to be prepended for each matched element. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find(".pear").prependText("extra text, ");
// => Returns: original Cheerio object originally with $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">extra text, Pear</li>
// </ul>
$body.find("ul").prependText("extra text, ");
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// extra text,
// Apple
// Orange
// Pear
// </ul>
.prev([selector]) Source (L517)
Gets the previous sibling of the first element in the matched set, optionally filtered by a selector.
Parameters
Name | Type | Description |
---|---|---|
[
selector
]
|
String | Optional. A string for a selector to match elements against. |
Return Value
A Cheerio object containing the immediate previous sibling for the first element in the original matched set.
Examples
$body.find(".pear").prev();
$body.find(".pear").prev(".orange");
// [for each of the above]
// => Returns: new Cheerio object containing the `.orange` element
$body.find(".pear").prev(".apple");
// => Returns: new empty Cheerio object
.prevAll([selector]) Source (L537)
Gets all of the preceding siblings of the first selected element, optionally filtered by a selector.
Parameters
Name | Type | Description |
---|---|---|
[
selector
]
|
String | Optional. A string for a selector to match elements against. |
Return Value
A Cheerio object containing all the preceding siblings for the first element in the original matched set.
Examples
$body.find(".pear").prevAll();
// => Returns: new Cheerio object containing the `.orange` and `.apple` elements
$body.find(".pear").prevAll(".apple");
// => Returns: new Cheerio object containing the `.apple` element
.prevUntil(selector, [filter]) Source (L555)
Gets all of the preceding siblings of the first selected element, up to (but not including) the element matched by the selector, optionally filtered by another selector. If the selector argument passed in does not represent any known elements, or if no selector argument is passed, then this functions like `.prevAll()`.
Parameters
Name | Type | Description |
---|---|---|
selector
|
String | Object | A string for a selector, or a Cheerio object, indicating where to stop matching preceding elements. |
[
filter
]
|
String | Optional. A string for a selector to match elements against. |
Return Value
A Cheerio object containing all the preceding siblings (up to the specified selector) for the first element in the original matched set.
Examples
$body.find(".pear").prevUntil(".apple");
$body.find(".pear").prevUntil(".apple", "li");
// [for each of the above]
// => Returns: new Cheerio object containing the `.orange` element
$body.find(".pear").prevUntil(".apple", "div");
// => Returns: new empty Cheerio object
$body.find(".pear").prevUntil("div");
// => Returns: new Cheerio object containing the `.orange` and `.apple` elements
.remove([selector]) Source (L1169)
Removes the set of matched elements from the DOM and all their children. selector filters the set of matched elements to be removed.
Parameters
Name | Type | Description |
---|---|---|
[
selector
]
|
String | Optional. A string for a selector to match on removal. |
Return Value
The original Cheerio matched-set object.
Example
$body.find(".apple").remove();
$body.find("li").remove(".apple");
// [for both of the above]
// => Returns: original Cheerio object associated with $body.find(".apple")
// => HTML output:
// <ul id="fruits">
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.removeAttr(name) Source (L141)
Removes HTML attributes by name.
Parameters
Name | Type | Description |
---|---|---|
name
|
String | A string for the name of the attribute. |
Return Value
The updated form of the original Cheerio matched-set object.
Example
$body.find(".pear").removeAttr("class");
// => Returns: original Cheerio object associated with $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li>Pear</li>
// </ul>
.removeAttrs() Source (L165)
Removes all attributes for each element in the matched set.
Return Value
The updated form of the original Cheerio matched-set object.
Example
$body.find(".apple").removeAttrs();
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li>Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.removeClass([className]) Source (L212)
Removes one or more space-separated classes from each element in the matched set. If invoked with no arguments, all classes will be removed.
Parameters
Name | Type | Description |
---|---|---|
[
className
]
|
String | function | Optional. A string for one or more space-separated classes, or a function that returns one or more space-separated classes, to be removed from the class attribute. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find("li").removeClass("pear");
// => Returns: original Cheerio object associated with $body.find("li")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="">Pear</li>
// </ul>
$body.find("li").removeClass(function(index, currentClass) {
var removedClass;
if (currentClass === "apple") {
removedClass = "color";
$body.find("#fruits").attr("data-note", "This is a test note");
}
return removedClass;
});
// => Returns: original Cheerio object associated with $body.find("li")
// => HTML output:
// <ul id="fruits" data-notes="This is a test note">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="">Pear</li>
// </ul>
.removeIfEmpty([options]) Source (L559)
Removes each element in a matched set, if it has no content inside. Trims the selection, then removes any nodes that have no hide param is for when we can't remove the element(s).
Parameters
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
[
options
]
|
Object |
Optional.
An object of options.
Properties
|
Return Value
The updated form of the original Cheerio matched-set object.
Example
let $apple = $body.find(".apple");
$apple.removeIfEmpty();
// => Returns: original Cheerio object originally with $body.find(".apple")
// => HTML output (stays the same):
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
$apple.empty();
$apple.removeIfEmpty();
// => Returns: original Cheerio object originally with $body.find(".apple")
// => HTML output:
// <ul id="fruits">
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.removeTextNodes() Source (L475)
Removes text nodes for each element in the matched set.
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find(".apple").removeTextNodes();
// => Returns: original Cheerio object originally with $body.find(".apple")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji"></li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
$body.find("ul").removeTextNodes();
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits"><li class="apple" data-which="fuji">Apple</li><li class="orange">Orange</li> <li class="pear">Pear</li></ul>
.replace(attr, oldval, newval) Source (L108)
Replaces all or a portion of an old value of an attribute with a new value.
Parameters
Name | Type | Description |
---|---|---|
attr
|
string | A string for the attribute whose value is to be replaced. |
oldval
|
string | A string for the old value to be replaced. |
newval
|
string | A string for a new value to replace the old value. |
Return Value
The updated form of the original Cheerio matched-set object.
Example
$body.find(".apple").replace("data-which", "uji", "lorina");
// => Returns: original Cheerio object associated with $body.find(".apple")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="florina">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.replaceWith([content]) Source (L1190)
Replaces matched elements with content. This does not duplicate content if the content already exists in the DOM.
Parameters
Name | Type | Description |
---|---|---|
[
content
]
|
Object | function | Optional. A DOM element, Cheerio object, or a function that returns content with which to replace the set of matched elements. |
Return Value
The original Cheerio matched-set object.
Examples
let $plum = $(tag("li", {class: "plum"}, "Plum"));
$body.find(".pear").replaceWith($plum);
// => Returns: original Cheerio object associated with $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="plum">Plum</li>
// </ul>
$body.find(".apple").replaceWith($body.find(".pear"));
// => Returns: original Cheerio object associated with $body.find(".apple")
// => HTML output:
// <ul id="fruits">
// <li class="pear">Pear</li>
// <li class="orange">Orange</li>
// </ul>
.revertDumpTable() Source (L890)
Reverts the cheerio.dumpTable back to a table, using the ".mw-was-" classes ascribed by calls to the original .dumpTable() or .dumpTables() methods.
Return Value
The updated form of the original Cheerio matched-set object.
Example
let $ul = $body.find("ul");
let $table = $(tag("table"));
let $thead = $(tag("thead"));
let $tr1 = $(tag("tr"));
let $th = $(tag("th"));
let $tbody = $(tag("tbody"));
let $tr2 = $(tag("tr"));
let $td= $(tag("td"));
let $tfoot = $(tag("tfoot"));
$table.append($thead.append($tr1.append($th)));
$table.append($tbody.append($tr2.append($td)));
$table.append($tfoot);
$ul.after($table);
$body.dumpTables();
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// <div class="mw-was-table">
// <div class="mw-was-thead">
// <div class="mw-was-th"></div>
// </div>
// <div class="mw-was-tbody">
// <div class="mw-was-td></div>
// </div>
// <div class="mw-was-tfoot"></div>
// </div>
$table.revertDumpTable();
// => Returns: original Cheerio object associated with $table
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// <table class="mw-no-changes mw-table-dump-reverted">
// <thead class="mw-table-dump-reverted-thead">
// <th class="mw-table-dump-reverted-th"></th>
// </thead>
// <tbody class="mw-table-dump-reverted-tbody">
// <td class="mw-table-dump-reverted-td"></td>
// </tbody>
// <tfoot class="mw-table-dump-reverted-tfoot"></tfoot>
// </table>
.serializeArray() Source (L336)
Encodes a form element as an array of names and values.
Return Value
An array containing a dictionary of attribute-value pairs for the form element's HTML attributes.
Example
let $myForm = $(tag("form"));
$myForm.append(tag("input", {name: "foo", value: "bar"}));
$myForm.serializeArray();
// => Returns: [{name: "foo", value: "bar"}]
.setLower() Source (L708)
Sets the text of each element in the matched set to lowercase.
Return Value
The updated form of the original Cheerio matched-set object.
Example
$body.find(".apple").setLower();
// => Returns: original Cheerio object originally with $body.find(".apple")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.setText(reg1, reg2) Source (L657)
Performs a regular expression replacement for each element in the matched set.
Parameters
Name | Type | Description |
---|---|---|
reg1
|
string | Original text. |
reg2
|
string | New text. |
Return Value
The updated form of the original Cheerio matched-set object.
Example
$body.find("li").setText("e", "x");
// => Returns: original Cheerio object originally with $body.find("li")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Applx</li>
// <li class="orange">Orangx</li>
// <li class="pear">Pxar</li>
// </ul>
.setUpper() Source (L684)
Sets the text of each element in the matched set to uppercase.
Return Value
The updated form of the original Cheerio matched-set object.
Example
$body.find(".apple").setUpper();
// => Returns: original Cheerio object originally with $body.find(".apple")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">APPLE</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.siblings([selector]) Source (L611)
Gets the siblings for the first element in the matched set, excluding itself.
Parameters
Name | Type | Description |
---|---|---|
[
selector
]
|
String | Optional. A string for a selector to match elements against. |
Return Value
A Cheerio object containing any and all of the siblings of the first element in the matched set.
Examples
$body.find(".orange").siblings();
// => Returns: new Cheerio object containing the `.apple` and `.pear` elements
$body.find(".orange").siblings("[data-which]");
// => Returns: new Cheerio object containing the `.apple` element
.slice(start, [end]) Source (L583)
Gets the elements matching the specified range.
Parameters
Name | Type | Description |
---|---|---|
start
|
Integer | An integer indicating the 0-based position at which the elements begin to be selected. If negative, it indicates an offset from the end of the set. |
[
end
]
|
Integer | Optional. An integer indicating the 0-based position at which the elements stop being selected (exclusive). If indicated, it indicates an offset from the end of the set. If omitted, the range continues until the end of the set. |
Return Value
A reduced Cheerio matched-set object.
Examples
$body.find("li").slice(1);
$body.find("li").slice(-2);
$body.find("li").slice(1, 3);
// [for each of the above]
// => Returns: new Cheerio object containing the `.orange` and `.pear` elements
$body.find("li").slice(1, 2);
// => Returns: new Cheerio object containing the `.orange` element
$body.find("li").slice(-3, -1);
// => Returns: new Cheerio object containing the `.apple` and `.orange` elements
.text([content]) Source (L1270)
Gets the combined text contents of each element in the matched set, including their descendants. If content is specified, each selected element's content is replaced by the new text content.
Parameters
Name | Type | Description |
---|---|---|
[
content
]
|
String | Optional. An optional string to change this method from a getter to a setter, setting the new text content of each element in the matched set. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find(".pear").text();
// => Returns: "Pear"
$body.find("#fruits").text();
// => Returns:
// "
// Apple
// Orange
// Pear
//
// "
$body.find(".pear").text("This is a pear");
// => Returns: original updated Cheerio object associated with
// $body.find(".pear")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">This is a pear</li>
// </ul>
let $fruits = $body.find("#fruits");
$fruits.text($fruits.text());
// => Returns: original updated Cheerio object associated with
// $body.find("#fruits")
// => HTML output:
// <ul id="fruits">
// Apple
// Orange
// Pear
// </ul>
.toArray() Source (L1389)
Retrieves all DOM elements in the matched set into an array.
Return Value
An array of DOM elements associated with the elements in the matched set.
Example
$body.find("li").toArray();
// => Returns: array of DOM elements associated with the `li` selector
.toggleClass(className, [switch]) Source (L250)
Adds or removes class(es) from each element in the matched set, depending on either the class's presence or the value of the switch argument.
Parameters
Name | Type | Description |
---|---|---|
className
|
String | function | A string for one or more space-separated classes, or a function that returns one or more space-separated classes, to be toggled from the class attribute. |
[
switch
]
|
Boolean | Optional. A Boolean to determine whether the class should be added or removed. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find(".pear").toggleClass("pear");
// => Returns: original Cheerio object associated with the element originally
// found from $body.find(".pear")
// => HTML output:
// <ul id="fruits" data-id="1">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="">Pear</li>
// </ul>
let $li = $body.find("li");
$li.toggleClass("red blue", true);
// => Returns: original Cheerio object associated with $body.find("li")
// => HTML output:
// <ul id="fruits" data-id="1">
// <li class="apple red blue" data-which="fuji">Apple</li>
// <li class="orange red blue">Orange</li>
// <li class="pear red blue">Pear</li>
// </ul>
$li.toggleClass("apple blue", false);
// => Returns: original Cheerio object associated with $body.find("li")
// => HTML output:
// <ul id="fruits" data-id="1">
// <li class="red" data-which="fuji">Apple</li>
// <li class="orange red">Orange</li>
// <li class="pear red">Pear</li>
// </ul>
$body.find("li").toggleClass(function() {
if ($(this).attr("data-which") === "fuji") {
return "red";
} else {
return "black";
}
});
// => Returns: original Cheerio object associated with $body.find("li")
// => HTML output:
// <ul id="fruits" data-id="1">
// <li class="apple red" data-which="fuji">Apple</li>
// <li class="orange black">Orange</li>
// <li class="pear black">Pear</li>
// </ul>
.trim() Source (L516)
Trims whitespace for each element in the matched set. Only looks one level deep for whitespace; nested text nodes remain untouched.
Return Value
The updated form of the original Cheerio matched-set object.
Example
let $grape = $(tag("li", {class: "grape"}, " Grape "));
$body.find("ul").append($grape);
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// <li class="grape"> Grape </li>
// </ul>
$grape.trim();
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// <li class="grape">Grape</li>
// </ul>
.unwrap() Source (L412)
Removes the wrapping element while retaining selected element itself, for each element in the matched set.
Return Value
The updated form of the original Cheerio matched-set object.
Example
$body.find("ul").unwrap();
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
.val([value]) Source (L85)
Gets or sets the value of inputs, selects, and textareas.
Parameters
Name | Type | Description |
---|---|---|
[
value
]
|
String | Optional. A string for the new form element value. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
let $newInput = $(tag("input"));
$body.find("#fruits").after($newInput);
$newInput.val("input test");
// => Returns: original Cheerio object containing the `input[type="checkbox"]`
// element
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// <input value="input test">
$newInput.val();
// => Returns: "input test"
let $newTextArea = $(tag("textarea"));
$body.find("#fruits").after($newTextArea);
$newTextArea.val("textarea test");
// => Returns: original Cheerio object containing the `textarea` element
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// <textarea>textarea test</textarea>
let $newSelect = $(tag("select", {name: "sel1"}));
$body.find("#fruits").after($newSelect);
$newSelect.append(tag("option", {value: "val1"}, "test1"));
$newSelect.append(tag("option", {value: "val2"}, "test2"));
$newSelect.val("val2");
// => Returns: original Cheerio object containing the `select` element
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// <select name="sel1">
// <option value="val1">test1</option>
// <option value="val2" selected>test2</option>
// </select>
$newSelect.val();
// => Returns: "val2"
.wrap(name, [options]) Source (L258)
Wraps each element in the matched set with a newly-defined input element. Note that this is different from the original Cheerio's .wrap() implementation.
Parameters
Name | Type | Description |
---|---|---|
name
|
String | A string for an element name. |
[
options
]
|
Object | Optional. An object containing a list of HTML attribute-value pairs. |
Return Value
The updated form of the original Cheerio matched-set object.
Example
$body.find("#fruits").wrap("div", {class: "wrapper"});
// => Returns: original Cheerio object originally with $body.find("#fruits")
// => HTML output:
// <div class="wrapper">
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
// </div>
.wrapInner(name, [options]) Source (L307)
Wraps inner contents of each element in the matched set.
Parameters
Name | Type | Description |
---|---|---|
name
|
String | A string for an element name. |
[
options
]
|
Object | Optional. An object containing a list of HTML attribute-value pairs. |
Return Value
The updated form of the original Cheerio matched-set object.
Example
$body.find("#fruits").name("div");
$body.find("#fruits").wrapInner("ol", {class: "fruits-inner"});
// => Returns: original Cheerio object originally with $body.find("#fruits")
// => HTML output:
// <div id="fruits">
// <ol class="fruits-inner">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ol>
// </div>
.wrapNonemptyTextChildren(name, [options]) Source (L620)
Wraps any text nodes for each element in the matched set. This differs from wrapTextChildren(), since this ignores text nodes that are comprised entirely of whitespace.
Parameters
Name | Type | Description |
---|---|---|
name
|
String | A string for an element name. |
[
options
]
|
Object | Optional. An object containing a list of HTML attribute-value pairs. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find("li").wrapNonemptyTextChildren("span", {class: "text"});
// => Returns: original Cheerio object originally with $body.find("li")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji"><span class="text">Apple</span></li>
// <li class="orange"><span class="text">Orange</span></li>
// <li class="pear"><span class="text">Pear</span></li>
// </ul>
$body.find("ul").wrapNonemptyTextChildren("li", {class: "text"});
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output (stays the same):
// <ul id="fruits">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ul>
.wrapTextChildren(name, [options]) Source (L193)
Wraps any text nodes for each element in the matched set. This includes text nodes that are comprised entirely of whitespace.
Parameters
Name | Type | Description |
---|---|---|
name
|
String | A string for an element name. |
[
options
]
|
Object | Optional. An object containing a list of HTML attribute-value pairs. |
Return Value
The updated form of the original Cheerio matched-set object.
Examples
$body.find("li").wrapTextChildren("span", {class: "text"});
// => Returns: original Cheerio object originally with $body.find("li")
// => HTML output:
// <ul id="fruits">
// <li class="apple" data-which="fuji"><span class="text">Apple</span></li>
// <li class="orange"><span class="text">Orange</span></li>
// <li class="pear"><span class="text">Pear</span></li>
// </ul>
$body.find("ul").wrapTextChildren("li", {class: "text"});
// => Returns: original Cheerio object originally with $body.find("ul")
// => HTML output:
// <ul id="fruits"><li class="text">
// </li><li class="apple" data-which="fuji">Apple</li><li class="text">
// </li><li class="orange">Orange</li><li class="text">
// </li><li class="pear">Pear</li><li class="text">
// </li></ul>
.wrapTogether(name, [options]) Source (L344)
Wraps all elements in a matched set under a single newly-defined element, and insert this new element where the first element in the matched set once was.
Parameters
Name | Type | Description |
---|---|---|
name
|
String | A string for an element name. |
[
options
]
|
Object | Optional. An object containing a list of HTML attribute-value pairs. |
Return Value
The updated form of the original Cheerio matched-set object.
Example
$body.find("#fruits").name("div");
$body.find("li").wrapTogether("ol", {class: "fruits-inner"});
// => Returns: original Cheerio object originally with $body.find("li")
// => HTML output:
// <div id="fruits">
// <ol class="fruits-inner">
// <li class="apple" data-which="fuji">Apple</li>
// <li class="orange">Orange</li>
// <li class="pear">Pear</li>
// </ol>
// </div>