# cheerio-advanced-selectors > Add advanced selector support to cheerio Latest version **2.0.1** (published 2018-03-12) · MIT license · 0 weekly downloads ## Install ```sh npm install cheerio-advanced-selectors pnpm add cheerio-advanced-selectors yarn add cheerio-advanced-selectors bun add cheerio-advanced-selectors ``` ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 2.0.1 | | Published | 2018-03-12 | | First published | 2015-06-29 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 0 | | Unpacked size | 13 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 31 | | Author | Thomas Watson Steen | | Maintainers | watson | | Keywords | cheerio, css, jquery, query, queries, selector, selectors, find, last, first, eq, scraping, scraper, scrape | ## Links - npm: https://www.npmjs.com/package/cheerio-advanced-selectors - Repository: https://github.com/watson/cheerio-advanced-selectors - Issues: https://github.com/watson/cheerio-advanced-selectors/issues - npm.io page: https://npm.io/package/cheerio-advanced-selectors ## Alternatives - [@tsparticles/shape-image](https://npm.io/package/@tsparticles/shape-image.md) — 303.7K weekly downloads - [@tsparticles/shape-line](https://npm.io/package/@tsparticles/shape-line.md) — 233.7K weekly downloads - [stringify-attributes](https://npm.io/package/stringify-attributes.md) — 58.6K weekly downloads - [mobile-drag-drop](https://npm.io/package/mobile-drag-drop.md) — 46.3K weekly downloads - [@comunica/actor-rdf-parse-html](https://npm.io/package/@comunica/actor-rdf-parse-html.md) — 29.2K weekly downloads ## Recent versions - 2.0.1 (latest) — 2018-03-12 - 2.0.0 — 2018-03-12 - 1.1.1 — 2016-07-07 - 1.1.0 — 2015-06-30 - 1.0.2 — 2015-06-30 - 1.0.1 — 2015-06-30 - 1.0.0 — 2015-06-29 ## README # cheerio-advanced-selectors Add support for the following selectors to [cheerio](https://github.com/cheeriojs/cheerio): - `:first` - `:last` - `:eq(index)` More selectors can easily be added: Just [open an issue](https://github.com/watson/cheerio-advanced-selectors/issues) and I'll look into it :) [![Build status](https://travis-ci.org/watson/cheerio-advanced-selectors.svg?branch=master)](https://travis-ci.org/watson/cheerio-advanced-selectors) [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://github.com/feross/standard) This module is inspired by [cheerio-eq](https://github.com/watson/cheerio-eq) with the added support for many different selectors. Supports cheerio version 0.18.0 and above. ## Installation ``` npm install cheerio-advanced-selectors ``` ## Usage Use the `.wrap()` function to make cheerio-advanced-selectors take care of everything for you: ```js var cheerio = require('cheerio') var cheerioAdv = require('cheerio-advanced-selectors') cheerio = cheerioAdv.wrap(cheerio) var $ = cheerio.load('
foo
bar
') $('div:first').text() // => 'foo' ``` ## Advanced usage Alternatively use the `.find()` function to only use cheerio-advanced-selectors for a specific selector: ```js var cheerio = require('cheerio') var cheerioAdv = require('cheerio-advanced-selectors') var $ = cheerio.load('
foo
bar
') cheerioAdv.find($, 'div:eq(1)').text() // => 'bar' ``` If you need to run the same selector on a lot of different HTML documents, you can speed things up by pre-compiling the selector using the `.compile()` function: ```js var cheerio = require('cheerio') var cheerioAdv = require('cheerio-advanced-selectors') var myH1 = cheerioAdv.compile('div:first span:eq(1) h1') var html1 = cheerio.load('

foo1

bar1

') var html2 = cheerio.load('

foo2

bar2

') myH1(html1).text() // => 'bar1' myH1(html2).text() // => 'bar2' ``` ## What's the problem? Cheerio sacrifices advanced CSS selector support for speed. This means for instance that the `:eq()` selector isn't supported. The work-around is normally to use the `.eq()` function instead: ```js // this will not work: $('div:eq(1)'); // use this instead: $('div').eq(1); ``` This is a good alternative if you write the CSS selectors from scrach, but what if you are working with selectors that already contain `:eq()`? **Don't fear, cheerio-advanced-selectors is here :)** ### Solution The solution to the problem is to automatically parse the selector string at run-time. So if you give cheerio-advanced-selectors a selector like `div:eq(1)` it will return the following cheerio cursor: `$('div').eq(1)`. It also works for complex selectors, so that `div:eq(1) h2:first span` will be converted and interpreted as `$('div').eq(1).find('h2').first().find('span')`. ## Supported advanced selectors This module currently only support a minimal subset of the possible advanced selectors: - `:first` - `:last` - `:eq(index)` But don't fear :) It's easy to add support for other selectors. Just [open an issue](https://github.com/watson/cheerio-advanced-selectors/issues) or make a pull request. ## API #### `.wrap(cheerio)` Wraps the main cheerio module to overload the standard `load` function so it knows how to handle the advanced selectors. Returns the `cheerio` module. #### `.find(cheerio, selector [, context [, root]])` Run the `selector` on the given cheerio object optionally within the given `context` and optionally on the given `root`. The `cheerio` object is usually called `$`. #### `.compile(selector)` Compiles the `selector` and returns a function which take 3 arguments: `fn(cheerio [, context [, root]])`: - `cheerio` - a reference to the cheerio object (usually called `$`) - `context` - the context in which to run the selector (optional) - `root` - the HTML root on which to run the selector (optional) ## License MIT --- _Source: https://npm.io/package/cheerio-advanced-selectors · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._