cheerio/manipulation

Methods for modifying the DOM structure.

Methods

# (static) after(…content) → {Cheerio}

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

Parameters:
Name Type Attributes Description
content string | Element | Array.<Element> | Cheerio | function <repeatable>

HTML string, DOM element, array of DOM elements or Cheerio to insert after each element in the set of matched elements.
Source:
See:
Returns:

The instance itself.

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

# (static) append()

Inserts content as the last child of each of the selected elements.

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

# (static) appendTo(target) → {Cheerio}

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

Parameters:
Name Type Description
target string | Cheerio

Element to append elements to.
Source:
See:
Returns:

The instance itself.

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

# (static) before(…content) → {Cheerio}

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

Parameters:
Name Type Attributes Description
content string | Element | Array.<Element> | Cheerio | function <repeatable>

HTML string, DOM element, array of DOM elements or Cheerio to insert before each element in the set of matched elements.
Source:
See:
Returns:

The instance itself.

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

# (static) clone() → {Cheerio}

Clone the cheerio object.

Source:
See:
Returns:

The cloned object.

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

# (static) empty() → {Cheerio}

Empties an element, removing all its children.

Source:
See:
Returns:

The instance itself.

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

# (static) html(str) → {Cheerio}

Gets an HTML content string from the first selected element. If htmlString is specified, each selected element's content is replaced by the new content.

Parameters:
Name Type Description
str string | Cheerio

If specified used to replace selection's contents.
Source:
See:
Returns:

The instance itself.

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

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

# (static) insertAfter(target) → {Cheerio}

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

Parameters:
Name Type Description
target string | Cheerio

Element to insert elements after.
Source:
See:
Returns:

The set of newly inserted elements.

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

# (static) insertBefore(target) → {Cheerio}

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

Parameters:
Name Type Description
target string | Cheerio

Element to insert elements before.
Source:
See:
Returns:

The set of newly inserted elements.

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

# (static) prepend()

Inserts content as the first child of each of the selected elements.

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

# (static) prependTo(target) → {Cheerio}

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

Parameters:
Name Type Description
target string | Cheerio

Element to prepend elements to.
Source:
See:
Returns:

The instance itself.

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

# (static) remove(selectoropt) → {Cheerio}

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 Attributes Description
selector string <optional>

Optional selector for elements to remove.
Source:
See:
Returns:

The instance itself.

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

# (static) replaceWith(content) → {Cheerio}

Replaces matched elements with content.

Parameters:
Name Type Description
content Cheerio | function

Replacement for matched elements.
Source:
See:
Returns:

The instance itself.

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

# (static) text(stropt) → {Cheerio|string}

Get the combined text contents of each element in the set of matched elements, including their descendants. If textString is specified, each selected element's content is replaced by the new text content.

Parameters:
Name Type Attributes Description
str string | function <optional>

If specified replacement for the selected element's contents.
Source:
See:
Returns:

The instance itself when setting text, otherwise the rendered document.

Type
Cheerio | string
Example 
$('.orange').text();
  //=> Orange

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

# (static) toString() → {string}

Turns the collection to a string. Alias for .html().

Returns:

The rendered document.

Type
string

# (static) unwrap(selectoropt) → {Cheerio}

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

Parameters:
Name Type Attributes Description
selector string <optional>

A selector to check the parent element against. If an element's parent does not match the selector, the element won't be unwrapped.
Source:
See:
Returns:

The instance itself, for chaining.

Type
Cheerio
Examples

without selector

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

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

with selector

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

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

# (static) wrap(wrapper)

The .wrap() function can take any string or object that could be passed to the $() factory function to specify a DOM structure. This structure may be nested several levels deep, but should contain only one inmost element. A copy of this structure will be wrapped around each of the elements in the set of matched elements. This method returns the original set of elements for chaining purposes.

Parameters:
Name Type Description
wrapper Cheerio

The DOM structure to wrap around each element in the selection.
Source:
See:
Example 
const redFruit = $('<div class="red-fruit"></div>');
  $('.apple').wrap(redFruit);

  //=> <ul id="fruits">
  //     <div class="red-fruit">
  //      <li class="apple">Apple</li>
  //     </div>
  //     <li class="orange">Orange</li>
  //     <li class="plum">Plum</li>
  //   </ul>

  const healthy = $('<div class="healthy"></div>');
  $('li').wrap(healthy);

  //=> <ul id="fruits">
  //     <div class="healthy">
  //       <li class="apple">Apple</li>
  //     </div>
  //     <div class="healthy">
  //       <li class="orange">Orange</li>
  //     </div>
  //     <div class="healthy">
  //        <li class="plum">Plum</li>
  //     </div>
  //   </ul>

# (static) wrapAll(wrapper) → {Cheerio}

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.

Parameters:
Name Type Description
wrapper Cheerio | string | Element | Array.<Element> | function

The DOM structure to wrap around all matched elements in the selection.
Source:
See:
Returns:

The instance itself.

Type
Cheerio
Examples

With markup passed to `wrapAll`

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

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

With an existing cheerio instance

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

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

# (static) wrapInner(wrapper)

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

Parameters:
Name Type Description
wrapper Cheerio

The DOM structure to wrap around the content of each element in the selection.
Source:
See:
Example 
const redFruit = $('<div class="red-fruit"></div>');
  $('.apple').wrapInner(redFruit);

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

  const healthy = $('<div class="healthy"></div>');
  $('li').wrapInner(healthy);

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