Class Cheerio<T>Abstract

Type Parameters

  • T

Hierarchy

  • AttributesType
  • TraversingType
  • ManipulationType
  • CssType
  • FormsType
  • Iterable<T>
    • Cheerio

Implements

  • ArrayLike<T>

Indexable

[index: number]: T

Constructors

  • Private

    Instance of cheerio. Methods are specified in the modules. Usage of this constructor is not recommended. Please use $.load instead.

    Type Parameters

    • T

    Parameters

    • elements: undefined | ArrayLike<T>

      The new selection.

    • root: null | Cheerio<Document>

      Sets the root node.

    • options: InternalOptions

      Options for the instance.

    Returns Cheerio<T>

Properties

_root: null | Cheerio<Document>

The root of the document. Can be set by using the root argument of the constructor.

cheerio: "[cheerio object]"
length: number = 0
options: InternalOptions
prevObject: undefined | Cheerio<any>
splice: ((start?: number, end?: number) => any[])

Type declaration

    • (start?: number, end?: number): any[]
    • Returns a copy of a section of an array. For both start and end, a negative index can be used to indicate an offset from the end of the array. For example, -2 refers to the second to last element of the array.

      Parameters

      • Optional start: number

        The beginning index of the specified portion of the array. If start is undefined, then the slice begins at index 0.

      • Optional end: number

        The end index of the specified portion of the array. This is exclusive of the element at the index 'end'. If end is undefined, then the slice extends to the end of the array.

      Returns any[]

Attributes Methods

  • Adds class(es) to all of the matched elements. Also accepts a function.

    Example

    $('.pear').addClass('fruit').html();
    //=> <li class="pear fruit">Pear</li>

    $('.apple').addClass('fruit red').html();
    //=> <li class="apple fruit red">Apple</li>

    Returns

    The instance itself.

    See

    https://api.jquery.com/addClass/

    Type Parameters

    • T extends AnyNode

    • R extends ArrayLike<T, R>

    Parameters

    • this: R
    • Optional value: string | ((this: Element, i: number, className: string) => undefined | string)

      Name of new class.

    Returns R

  • Method for getting attributes. Gets the attribute value for only the first element in the matched set.

    Example

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

    Returns

    The attribute's value.

    See

    https://api.jquery.com/attr/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • name: string

      Name of the attribute.

    Returns string | undefined

  • Method for getting all attributes and their values of the first element in the matched set.

    Example

    $('ul').attr();
    //=> { id: 'fruits' }

    Returns

    The attribute's values.

    See

    https://api.jquery.com/attr/

    Type Parameters

    Parameters

    Returns Record<string, string> | undefined

  • Method for setting attributes. Sets the attribute value for only the first element in the matched set. If you set an attribute's value to null, you remove that attribute. You may also pass a map and function.

    Example

    $('.apple').attr('id', 'favorite').html();
    //=> <li class="apple" id="favorite">Apple</li>

    Returns

    The instance itself.

    See

    https://api.jquery.com/attr/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • name: string

      Name of the attribute.

    • Optional value: null | string | ((this: Element, i: number, attrib: string) => null | string)

      The new value of the attribute.

    Returns Cheerio<T>

  • Method for setting multiple attributes at once. Sets the attribute value for only the first element in the matched set. If you set an attribute's value to null, you remove that attribute.

    Example

    $('.apple').attr({ id: 'favorite' }).html();
    //=> <li class="apple" id="favorite">Apple</li>

    Returns

    The instance itself.

    See

    https://api.jquery.com/attr/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • values: Record<string, null | string>

      Map of attribute names and values.

    Returns Cheerio<T>

  • Method for getting data attributes, for only the first element in the matched set.

    Example

    $('<div data-apple-color="red"></div>').data('apple-color');
    //=> 'red'

    Returns

    The data attribute's value, or undefined if the attribute does not exist.

    See

    https://api.jquery.com/data/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • name: string

      Name of the data attribute.

    Returns unknown | undefined

  • Method for getting all of an element's data attributes, for only the first element in the matched set.

    Example

    $('<div data-apple-color="red"></div>').data();
    //=> { appleColor: 'red' }

    Returns

    A map with all of the data attributes.

    See

    https://api.jquery.com/data/

    Type Parameters

    Parameters

    Returns Record<string, unknown>

  • Method for setting data attributes, for only the first element in the matched set.

    Example

    const apple = $('.apple').data('kind', 'mac');

    apple.data('kind');
    //=> 'mac'

    Returns

    The instance itself.

    See

    https://api.jquery.com/data/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • name: string

      Name of the data attribute.

    • value: unknown

      The new value.

    Returns Cheerio<T>

  • Method for setting multiple data attributes at once, for only the first element in the matched set.

    Example

    const apple = $('.apple').data({ kind: 'mac' });

    apple.data('kind');
    //=> 'mac'

    Returns

    The instance itself.

    See

    https://api.jquery.com/data/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • values: Record<string, unknown>

      Map of names to values.

    Returns Cheerio<T>

  • Check to see if any of the matched elements have the given className.

    Example

    $('.pear').hasClass('pear');
    //=> true

    $('apple').hasClass('fruit');
    //=> false

    $('li').hasClass('pear');
    //=> true

    Returns

    Indicates if an element has the given className.

    See

    https://api.jquery.com/hasClass/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • className: string

      Name of the class.

    Returns boolean

  • Checks the current list of elements and returns true if any of the elements match the selector. If using an element or Cheerio selection, returns true if any of the elements match. If using a predicate function, the function is executed in the context of the selected element, so this refers to the current element.

    Returns

    Whether or not the selector matches an element of the instance.

    See

    https://api.jquery.com/is/

    Type Parameters

    • T

    Parameters

    Returns boolean

  • Method for getting and setting properties. Gets the property value for only the first element in the matched set.

    Example

    $('input[type="checkbox"]').prop('checked');
    //=> false

    $('input[type="checkbox"]').prop('checked', true).val();
    //=> ok

    Returns

    If value is specified the instance itself, otherwise the prop's value.

    See

    https://api.jquery.com/prop/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • name: "tagName" | "nodeName"

      Name of the property.

    Returns T extends Element ? string : undefined

  • Type Parameters

    Parameters

    • this: Cheerio<T>
    • name: "innerHTML" | "outerHTML" | "innerText" | "textContent"

    Returns string | null

  • Get a parsed CSS style object.

    Type Parameters

    Parameters

    Returns StyleProp | undefined

  • Resolve href or src of supported elements. Requires the baseURI option to be set, and a global URL object to be part of the environment.

    Example

    With baseURI set to 'https://example.com':

    $('<img src="image.png">').prop('src');
    //=> 'https://example.com/image.png'

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • name: "href" | "src"

    Returns string | undefined

  • Get a property of an element.

    Type Parameters

    Parameters

    Returns Element[K]

  • Set a property of an element.

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • name: K
    • value: Element[K] | ((this: Element, i: number, prop: K) => undefined | null | string | number | TagSourceCodeLocation | Document | Element | CDATA | Text | Comment | ProcessingInstruction | ChildNode[] | {
          [name: string]: string;
      } | Attribute[] | Record<string, string> | (<T>(this: T, recursive?: boolean) => T))

    Returns Cheerio<T>

  • Type Parameters

    Parameters

    • this: Cheerio<T>
    • name: Record<string, undefined | null | string | number | boolean | TagSourceCodeLocation | Document | Element | CDATA | Text | Comment | ProcessingInstruction | ChildNode[] | {
          [name: string]: string;
      } | Attribute[] | Record<string, string> | (<T>(this: T, recursive?: boolean) => T)>

    Returns Cheerio<T>

  • Type Parameters

    Parameters

    • this: Cheerio<T>
    • name: string
    • value: null | string | boolean | ((this: Element, i: number, prop: string) => string | boolean)

    Returns Cheerio<T>

  • Type Parameters

    Parameters

    Returns string

  • Method for removing attributes by name.

    Example

    $('.pear').removeAttr('class').html();
    //=> <li>Pear</li>

    $('.apple').attr('id', 'favorite');
    $('.apple').removeAttr('id class').html();
    //=> <li>Apple</li>

    Returns

    The instance itself.

    See

    https://api.jquery.com/removeAttr/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • name: string

      Name of the attribute.

    Returns Cheerio<T>

  • Removes one or more space-separated classes from the selected elements. If no className is defined, all classes will be removed. Also accepts a function.

    Example

    $('.pear').removeClass('pear').html();
    //=> <li class="">Pear</li>

    $('.apple').addClass('red').removeClass().html();
    //=> <li class="">Apple</li>

    Returns

    The instance itself.

    See

    https://api.jquery.com/removeClass/

    Type Parameters

    • T extends AnyNode

    • R extends ArrayLike<T, R>

    Parameters

    • this: R
    • Optional name: string | ((this: Element, i: number, className: string) => undefined | string)

      Name of the class. If not specified, removes all elements.

    Returns R

  • Add or remove class(es) from the matched elements, depending on either the class's presence or the value of the switch argument. Also accepts a function.

    Example

    $('.apple.green').toggleClass('fruit green red').html();
    //=> <li class="apple fruit red">Apple</li>

    $('.apple.green').toggleClass('fruit green red', true).html();
    //=> <li class="apple green fruit red">Apple</li>

    Returns

    The instance itself.

    See

    https://api.jquery.com/toggleClass/

    Type Parameters

    • T extends AnyNode

    • R extends ArrayLike<T, R>

    Parameters

    • this: R
    • Optional value: string | ((this: Element, i: number, className: string, stateVal?: boolean) => string)

      Name of the class. Can also be a function.

    • Optional stateVal: boolean

      If specified the state of the class.

    Returns R

  • Method for getting the value of input, select, and textarea. Note: Support for map, and function has not been added yet.

    Example

    $('input[type="text"]').val();
    //=> input_text

    Returns

    The value.

    See

    https://api.jquery.com/val/

    Type Parameters

    Parameters

    Returns string | undefined | string[]

  • Method for setting the value of input, select, and textarea. Note: Support for map, and function has not been added yet.

    Example

    $('input[type="text"]').val('test').html();
    //=> <input type="text" value="test"/>

    Returns

    The instance itself.

    See

    https://api.jquery.com/val/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • value: string | string[]

      The new value.

    Returns Cheerio<T>

CSS Methods

  • Get the value of a style property for the first element in the set of matched elements.

    Returns

    A map of all of the style properties.

    See

    https://api.jquery.com/css/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • Optional names: string[]

      Optionally the names of the properties of interest.

    Returns Record<string, string> | undefined

  • Get the value of a style property for the first element in the set of matched elements.

    Returns

    The property value for the given name.

    See

    https://api.jquery.com/css/

    Type Parameters

    Parameters

    Returns string | undefined

  • Set one CSS property for every matched element.

    Returns

    The instance itself.

    See

    https://api.jquery.com/css/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • prop: string

      The name of the property.

    • val: string | ((this: Element, i: number, style: string) => undefined | string)

      The new value.

    Returns Cheerio<T>

  • Set multiple CSS properties for every matched element.

    Returns

    The instance itself.

    See

    https://api.jquery.com/css/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • map: Record<string, string>

      A map of property names and values.

    Returns Cheerio<T>

Forms Methods

  • Encode a set of form elements as an array of names and values.

    Example

    $('<form><input name="foo" value="bar" /></form>').serializeArray();
    //=> [ { name: 'foo', value: 'bar' } ]

    Returns

    The serialized form.

    See

    https://api.jquery.com/serializeArray/

    Type Parameters

    Parameters

    Returns SerializedField[]

Manipulation Methods

  • Gets an HTML content string from the first selected element.

    Example

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

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

    Returns

    The HTML content string.

    See

    https://api.jquery.com/html/

    Type Parameters

    Parameters

    Returns string | null

  • Replaces each selected element's content with the specified content.

    Example

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

    Returns

    The instance itself.

    See

    https://api.jquery.com/html/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • str: string | Cheerio<T>

      The content to replace selection's contents with.

    Returns Cheerio<T>

  • Removes the set of matched elements from the DOM and all their children. selector filters the set of matched elements to be removed.

    Example

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

    Returns

    The instance itself.

    See

    https://api.jquery.com/remove/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • Optional selector: string

      Optional selector for elements to remove.

    Returns Cheerio<T>

  • Get the combined text contents of each element in the set of matched elements, including their descendants.

    Example

    $('.orange').text();
    //=> Orange

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

    Returns

    The text contents of the collection.

    See

    https://api.jquery.com/text/

    Type Parameters

    Parameters

    Returns string

  • Set the content of each element in the set of matched elements to the specified text.

    Example

    $('.orange').text('Orange');
    //=> <div class="orange">Orange</div>

    Returns

    The instance itself.

    See

    https://api.jquery.com/text/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • str: string | ((this: AnyNode, i: number, text: string) => string)

      The text to set as the content of each matched element.

    Returns Cheerio<T>

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

    Example

    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>

    Example

    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>

    Returns

    The instance itself, for chaining.

    See

    https://api.jquery.com/unwrap/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • Optional selector: string

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

    Returns Cheerio<T>

  • The .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.

    Example

    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>

    Example

    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>

    Returns

    The instance itself.

    See

    https://api.jquery.com/wrapAll/

    Type Parameters

    Parameters

    • this: Cheerio<T>
    • wrapper: AcceptedElems<T>

      The DOM structure to wrap around all matched elements in the selection.

    Returns Cheerio<T>

Other Methods

  • Returns Iterator<T, any, undefined>

  • Private

    Parses some content.

    Returns

    A document containing the content.

    Parameters

    • content: string | AnyNode | AnyNode[] | Buffer

      Content to parse.

    • options: InternalOptions

      Options for parsing.

    • isDocument: boolean

      Allows parser to be switched to fragment mode.

    • context: null | ParentNode

    Returns Document

  • Private

    Render an element or a set of elements.

    Returns

    The rendered DOM.

    Parameters

    Returns string

  • Retrieve all the DOM elements contained in the jQuery set as an array.

    Example

    $('li').toArray();
    //=> [ {...}, {...}, {...} ]

    Returns

    The contained items.

    Type Parameters

    • T

    Parameters

    Returns T[]

Traversing Methods

  • 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.

    Example

    const fruits = [];

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

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

    Returns

    The instance itself, useful for chaining.

    See

    https://api.jquery.com/each/

    Type Parameters

    • T

    Parameters

    • this: Cheerio<T>
    • fn: ((this: T, i: number, el: T) => boolean | void)

      Function to execute.

        • (this: T, i: number, el: T): boolean | void
        • Parameters

          • this: T
          • i: number
          • el: T

          Returns boolean | void

    Returns Cheerio<T>

  • Reduce the set of matched elements to the one at the specified index. Use .eq(-i) to count backwards from the last selected element.

    Example

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

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

    Returns

    The element at the ith position.

    See

    https://api.jquery.com/eq/

    Type Parameters

    • T

    Parameters

    • this: Cheerio<T>
    • i: number

      Index of the element to select.

    Returns Cheerio<T>

  • Iterates over a cheerio object, reducing the set of selector elements to those that match the selector or pass the function's test.

    This is the definition for using type guards; have a look below for other ways to invoke this method. The function is executed in the context of the selected element, so this refers to the current element.

    Example

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

    Returns

    The filtered collection.

    See

    https://api.jquery.com/filter/

    Type Parameters

    • T

    • S

    Parameters

    • this: Cheerio<T>
    • match: ((this: T, index: number, value: T) => value is S)

      Value to look for, following the rules above.

        • (this: T, index: number, value: T): value is S
        • Parameters

          • this: T
          • index: number
          • value: T

          Returns value is S

    Returns Cheerio<S>

  • Iterates over a cheerio object, reducing the set of selector elements to those that match the selector or pass the function's test.

    • 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.

    Example

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

    Example

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

    Returns

    The filtered collection.

    See

    https://api.jquery.com/filter/

    Type Parameters

    • T

    • S

    Parameters

    Returns Cheerio<S extends string ? Element : T>

  • Retrieve one of the elements matched by the Cheerio object, at the ith position.

    Example

    $('li').get(0).tagName;
    //=> li

    Returns

    The element at the ith position.

    See

    https://api.jquery.com/get/

    Type Parameters

    • T

    Parameters

    • this: Cheerio<T>
    • i: number

      Element to retrieve.

    Returns T | undefined

  • Retrieve all elements matched by the Cheerio object, as an array.

    Example

    $('li').get().length;
    //=> 3

    Returns

    All elements matched by the Cheerio object.

    See

    https://api.jquery.com/get/

    Type Parameters

    • T

    Parameters

    Returns T[]

  • 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.

    Example

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

    Returns

    The mapped elements, wrapped in a Cheerio collection.

    See

    https://api.jquery.com/map/

    Type Parameters

    • T

    • M

    Parameters

    • this: Cheerio<T>
    • fn: ((this: T, i: number, el: T) => undefined | null | M | M[])

      Function to execute.

        • (this: T, i: number, el: T): undefined | null | M | M[]
        • Parameters

          • this: T
          • i: number
          • el: T

          Returns undefined | null | M | M[]

    Returns Cheerio<M>

  • Remove elements from the set of matched elements. Given a Cheerio object that represents a set of DOM elements, the .not() method constructs a new Cheerio object from a subset of the matching elements. The supplied selector is tested against each element; the elements that don't match the selector will be included in the result.

    The .not() method can take a function as its argument in the same way that .filter() does. Elements for which the function returns true are excluded from the filtered set; all other elements are included.

    Example

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

    Example

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

    Returns

    The filtered collection.

    See

    https://api.jquery.com/not/

    Type Parameters

    Parameters

    Returns Cheerio<T>

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

    Example

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

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

    Returns

    The elements matching the specified range.

    See

    https://api.jquery.com/slice/

    Type Parameters

    • T

    Parameters

    • this: Cheerio<T>
    • Optional start: number

      A position at which the elements begin to be selected. If negative, it indicates an offset from the end of the set.

    • Optional end: number

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

    Returns Cheerio<T>