Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cheeriojs/cheerio

The fast, flexible, and elegant library for parsing and manipulating HTML and XML.
https://github.com/cheeriojs/cheerio

cheerio dom hacktoberfest html htmlparser htmlparser2 jquery parser scraper selector

Last synced: 11 days ago
JSON representation

The fast, flexible, and elegant library for parsing and manipulating HTML and XML.

Awesome Lists containing this project

README 

        
cheerio



The fast, flexible, and elegant library for parsing and manipulating HTML and XML.





  

    Build Status

  

  

    Coverage

  

  

    OpenCollective backers

  

  

    OpenCollective sponsors

  








[中文文档 (Chinese Readme)](https://github.com/cheeriojs/cheerio/wiki/Chinese-README)



```js

import * as cheerio from 'cheerio';

const $ = cheerio.load('
Hello world
');



$('h2.title').text('Hello there!');

$('h2').addClass('welcome');



$.html();

//=> 
Hello there!


```



## Installation



`npm install cheerio`



## Features



**❤ Proven syntax:** Cheerio implements a subset of core jQuery. Cheerio

removes all the DOM inconsistencies and browser cruft from the jQuery library,

revealing its truly gorgeous API.



**ϟ Blazingly fast:** Cheerio works with a very simple, consistent DOM

model. As a result parsing, manipulating, and rendering are incredibly

efficient.



**❁ Incredibly flexible:** Cheerio wraps around

[parse5](https://github.com/inikulin/parse5) for parsing HTML and can optionally

use the forgiving [htmlparser2](https://github.com/fb55/htmlparser2/). Cheerio

can parse nearly any HTML or XML document. Cheerio works in both browser and

server environments.



## API



### Loading



First you need to load in the HTML. This step in jQuery is implicit, since

jQuery operates on the one, baked-in DOM. With Cheerio, we need to pass in the

HTML document.



```js

// ESM or TypeScript:

import * as cheerio from 'cheerio';



// In other environments:

const cheerio = require('cheerio');



const $ = cheerio.load('
    ...
');



$.html();

//=> 
    ...


```



### Selectors



Once you've loaded the HTML, you can use jQuery-style selectors to find elements

within the document.



#### \$( selector, [context], [root] )



`selector` searches within the `context` scope which searches within the `root`

scope. `selector` and `context` can be a string expression, DOM Element, array

of DOM elements, or cheerio object. `root`, if provided, is typically the HTML

document string.



This selector method is the starting point for traversing and manipulating the

document. Like in jQuery, it's the primary method for selecting elements in the

document.



```js

$('.apple', '#fruits').text();

//=> Apple



$('ul .pear').attr('class');

//=> pear



$('li[class=orange]').html();

//=> Orange

```



### Rendering



When you're ready to render the document, you can call the `html` method on the

"root" selection:



```js

$.root().html();

//=>  

//      

//      

//        
    

    //          
  • Apple
    • 

    //          
  • Orange
    • 

    //          
  • Pear
    • 

    //        


//      

//    

```



If you want to render the

[`outerHTML`](https://developer.mozilla.org/en-US/docs/Web/API/Element/outerHTML)

of a selection, you can use the `outerHTML` prop:



```js

$('.pear').prop('outerHTML');

//=> 
  • Pear
    • 

    ```
    


    You may also render the text content of a Cheerio object using the `text`

    method:
    


    ```js

    const $ = cheerio.load('This is content.');

    $('body').text();

    //=> This is content.

    ```
    


    ### The "DOM Node" object
    


    Cheerio collections are made up of objects that bear some resemblance to

    [browser-based DOM nodes](https://developer.mozilla.org/en-US/docs/Web/API/Node).

    You can expect them to define the following properties:
    


    - `tagName`

    - `parentNode`

    - `previousSibling`

    - `nextSibling`

    - `nodeValue`

    - `firstChild`

    - `childNodes`

    - `lastChild`
    


    ## Screencasts
    


    [https://vimeo.com/31950192](https://vimeo.com/31950192)
    


    > This video tutorial is a follow-up to Nettut's "How to Scrape Web Pages with

    > Node.js and jQuery", using cheerio instead of JSDOM + jQuery. This video shows

    > how easy it is to use cheerio and how much faster cheerio is than JSDOM +

    > jQuery.
    


    ## Cheerio in the real world
    


    Are you using cheerio in production? Add it to the

    [wiki](https://github.com/cheeriojs/cheerio/wiki/Cheerio-in-Production)!
    


    ## Sponsors
    


    Does your company use Cheerio in production? Please consider

    [sponsoring this project](https://github.com/cheeriojs/cheerio?sponsor=1)! Your

    help will allow maintainers to dedicate more time and resources to its

    development and support.
    


    **Headlining Sponsors**
    


    

                Tidelift

                  

    

                Github

                  

    

                AirBnB

              
    


    **Other Sponsors**
    


    

                Casinoonlineaams.com

                  

    

                ZenRows

                  

    

                Ігрові автомати

                  

    

                OnlineCasinosSpelen

                  

    

                CasinoZonderRegistratie.net

                  

    

                Nieuwe-Casinos.net

                  

    

                Vedonlyontiyhtiot.com

                  

    

                Puter.com

                  

    

                No Deposit Bonus

              
    


    ## Backers
    


    [Become a backer](https://github.com/cheeriojs/cheerio?sponsor=1) to show your

    support for Cheerio and help us maintain and improve this open source project.
    


    

                Vasy Kafidoff

                  

    

                Espen Klem

              
    


    ## License
    


    MIT