cheerio/traversing

Methods for traversing the DOM structure.

Methods

# (static) add(other, contextopt) → {Cheerio}

Add elements to the set of matched elements.

Parameters:
Name Type Attributes Description
other string | Cheerio

Elements to add.
context Cheerio <optional>

Optionally the context of the new selection.
Source:
See:
Returns:

The combined set.

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

# (static) addBack(selector) → {Cheerio}

Add the previous set of elements on the stack to the current set, optionally filtered by a selector.

Parameters:
Name Type Description
selector string

Selector for the elements to add.
Source:
See:
Returns:

The combined set.

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

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

Gets the children of the first selected element.

Parameters:
Name Type Attributes Description
selector string <optional>

If specified filter for children.
Source:
See:
Returns:

The children.

Type
Cheerio
Example 
$('#fruits').children().length;
  //=> 3

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

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

For each element in the set, get the first element that matches the selector by testing the element itself and traversing up through its ancestors in the DOM tree.

Parameters:
Name Type Attributes Description
selector string <optional>

Selector for the element to find.
Source:
See:
Returns:

The closest nodes.

Type
Cheerio
Example 
$('.orange').closest();
  // => []
  $('.orange').closest('.apple');
  // => []
  $('.orange').closest('li');
  // => [<li class="orange">Orange</li>]
  $('.orange').closest('#fruits');
  // => [<ul id="fruits"> ... </ul>]

# (static) contents() → {Cheerio}

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

Source:
See:
Returns:

The children.

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

# (static) each(fn) → {Cheerio}

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
fn function

Function to execute.
Source:
See:
Returns:

The instance itself, useful for chaining.

Type
Cheerio
Example 
const fruits = [];

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

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

# (static) end() → {Cheerio}

End the most recent filtering operation in the current chain and return the set of matched elements to its previous state.

Source:
See:
Returns:

The previous state of the set of matched elements.

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

# (static) eq(i) → {Cheerio}

Reduce 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 number

Index of the element to select.
Source:
See:
Returns:

The element at the ith position.

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

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

# (static) filter(match, containeropt) → {Cheerio}

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 Attributes Description
match string | function

Value to look for, following the rules above.
container Cheerio <optional>

Optional node to filter instead.
Source:
See:
Returns:

The filtered collection.

Type
Cheerio
Examples

Selector

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

Function

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

# (static) find(selectorOrHaystack) → {Cheerio}

Get the descendants of each element in the current set of matched elements, filtered by a selector, jQuery object, or element.

Parameters:
Name Type Description
selectorOrHaystack string | Cheerio | Node

Element to look for.
Source:
See:
Returns:

The found elements.

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

# (static) first() → {Cheerio}

Will select the first element of a cheerio object.

Source:
See:
Returns:

The first element.

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

# (static) get(iopt) → {Node}

Retrieve 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 Attributes Description
i number <optional>

Element to retrieve.
Source:
See:
Returns:

The node at the ith position.

Type
Node
Examples 
$('li').get(0).tagName
  //=> li

  If no index is specified, retrieve all elements matched by the Cheerio object:
$('li').get().length;
  //=> 3

# (static) has(selectorOrHaystack) → {Cheerio}

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
selectorOrHaystack string | Cheerio | Node

Element to look for.
Source:
See:
Returns:

The filtered collection.

Type
Cheerio
Examples

Selector

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

Element

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

# (static) index(selectorOrNeedleopt) → {number}

Search for a given element from among the matched elements.

Parameters:
Name Type Attributes Description
selectorOrNeedle string | Cheerio | Node <optional>

Element to look for.
Source:
See:
Returns:

The index of the element.

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

# (static) last() → {Cheerio}

Will select the last element of a cheerio object.

Source:
See:
Returns:

The last element.

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

# (static) map(fn) → {Cheerio}

Pass each element in the current matched set through a function, producing a new Cheerio object containing the return values. The function can return an individual data item or an array of data items to be inserted into the resulting set. If an array is returned, the elements inside the array are inserted into the set. If the function returns null or undefined, no element will be inserted.

Parameters:
Name Type Description
fn function

Function to execute.
Source:
See:
Returns:

The mapped elements, wrapped in a Cheerio collection.

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

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

Gets the next sibling of the first selected element, optionally filtered by a selector.

Parameters:
Name Type Attributes Description
selector string <optional>

If specified filter for sibling.
Source:
See:
Returns:

The next nodes.

Type
Cheerio
Example 
$('.apple').next().hasClass('orange');
  //=> true

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

Gets all the following siblings of the first selected element, optionally filtered by a selector.

Parameters:
Name Type Attributes Description
selector string <optional>

If specified filter for siblings.
Source:
See:
Returns:

The next nodes.

Type
Cheerio
Example 
$('.apple').nextAll();
  //=> [<li class="orange">Orange</li>, <li class="pear">Pear</li>]
  $('.apple').nextAll('.orange');
  //=> [<li class="orange">Orange</li>]

# (static) nextUntil(selector, filterSelectoropt) → {Cheerio}

Gets all the following siblings up to but not including the element matched by the selector, optionally filtered by another selector.

Parameters:
Name Type Attributes Description
selector string | Cheerio | Node

Selector for element to stop at.
filterSelector string <optional>

If specified filter for siblings.
Source:
See:
Returns:

The next nodes.

Type
Cheerio
Example 
$('.apple').nextUntil('.pear');
  //=> [<li class="orange">Orange</li>]

# (static) not(match, containeropt) → {Cheerio}

Remove elements from the set of matched elements. Given a jQuery object that represents a set of DOM elements, the .not() method constructs a new jQuery 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 Attributes Description
match string | function

Value to look for, following the rules above.
container Array.<Node> | Cheerio <optional>

Optional node to filter instead.
Source:
See:
Returns:

The filtered collection.

Type
Cheerio
Examples

Selector

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

Function

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

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

Get the parent of each element in the current set of matched elements, optionally filtered by a selector.

Parameters:
Name Type Attributes Description
selector string <optional>

If specified filter for parent.
Source:
See:
Returns:

The parents.

Type
Cheerio
Example 
$('.pear').parent().attr('id');
  //=> fruits

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

Get a set of parents filtered by selector of each element in the current set of match elements.

Parameters:
Name Type Attributes Description
selector string <optional>

If specified filter for parents.
Source:
See:
Returns:

The parents.

Type
Cheerio
Example 
$('.orange').parents().length;
  // => 2
  $('.orange').parents('#fruits').length;
  // => 1

# (static) parentsUntil(selector, filteropt) → {Cheerio}

Get the ancestors of each element in the current set of matched elements, up to but not including the element matched by the selector, DOM node, or cheerio object.

Parameters:
Name Type Attributes Description
selector string | Node | Cheerio

Selector for element to stop at.
filter string | function <optional>

Optional filter for parents.
Source:
See:
Returns:

The parents.

Type
Cheerio
Example 
$('.orange').parentsUntil('#food').length;
  // => 1

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

Gets the previous sibling of the first selected element optionally filtered by a selector.

Parameters:
Name Type Attributes Description
selector string <optional>

If specified filter for siblings.
Source:
See:
Returns:

The previous nodes.

Type
Cheerio
Example 
$('.orange').prev().hasClass('apple');
  //=> true

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

Gets all the preceding siblings of the first selected element, optionally filtered by a selector.

Parameters:
Name Type Attributes Description
selector string <optional>

If specified filter for siblings.
Source:
See:
Returns:

The previous nodes.

Type
Cheerio
Example 
$('.pear').prevAll();
  //=> [<li class="orange">Orange</li>, <li class="apple">Apple</li>]
  $('.pear').prevAll('.orange');
  //=> [<li class="orange">Orange</li>]

# (static) prevUntil(selector, filterSelectoropt) → {Cheerio}

Gets all the preceding siblings up to but not including the element matched by the selector, optionally filtered by another selector.

Parameters:
Name Type Attributes Description
selector string | Cheerio | Node

Selector for element to stop at.
filterSelector string <optional>

If specified filter for siblings.
Source:
See:
Returns:

The previous nodes.

Type
Cheerio
Example 
$('.pear').prevUntil('.apple');
  //=> [<li class="orange">Orange</li>]

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

Gets the first selected element's siblings, excluding itself.

Parameters:
Name Type Attributes Description
selector string <optional>

If specified filter for siblings.
Source:
See:
Returns:

The siblings.

Type
Cheerio
Example 
$('.pear').siblings().length;
  //=> 2

  $('.pear').siblings('.orange').length;
  //=> 1

# (static) slice(startopt, endopt) → {Cheerio}

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

Parameters:
Name Type Attributes Description
start number <optional>

An position at which the elements begin to be selected. If negative, it indicates an offset from the end of the set.
end number <optional>

An position at which the elements stop being selected. If negative, it indicates an offset from the end of the set. If omitted, the range continues until the end of the set.
Source:
See:
Returns:

The elements matching the specified range.

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

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