Add support for the following selectors to cheerio:

• :first
• :last
• :eq(index)

More selectors can easily be added: Just open an issue and I'll look into it :)

This module is inspired by cheerio-eq with the added support for many different selectors.

npm install cheerio-advanced-selectors

Use the .wrap() function to make cheerio-advanced-selectors take care of everything for you:

var cheerio = require('cheerio')
var cheerioAdv = require('cheerio-advanced-selectors')

cheerio = cheerioAdv.wrap(cheerio)

var $ = cheerio.load('<div>foo</div><div>bar</div>')

$('div:first').text() // => 'foo'

Gotcha: The result returned from .load() isn't a cheerio object but a custom function used to wrap the cheerio-advanced-selector logic (see issue 2).

Alternatively use the .find() function to only use cheerio-advanced-selectors for a specific selector:

var cheerio = require('cheerio')
var cheerioAdv = require('cheerio-advanced-selectors')

var $ = cheerio.load('<div><span>foo</span></div><div><span>bar</span></div>')

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:

var cheerio = require('cheerio')
var cheerioAdv = require('cheerio-advanced-selectors')

var myH1 = cheerioAdv.compile('div:first span:eq(1) h1')

var html1 = cheerio.load('<div><span><h1>foo1</h1></span><span><h1>bar1</h1></span></div>')
var html2 = cheerio.load('<div><span><h1>foo2</h1></span><span><h1>bar2</h1></span></div>')

myH1(html1).text() // => 'bar1'
myH1(html2).text() // => 'bar2'

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:

// 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 :)

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').

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 or make a pull request.

Wraps the main cheerio module to overload the standard load function so it knows how to handle the advanced selectors.

Returns the cheerio module.

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

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)

MIT