Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Cheerio's version of node-soupselect.
Pull request Compare This branch is 33 commits ahead, 27 commits behind harryf:master.
Latest commit 36f4fd7 @matthewmueller note


DEPRECATED: This library has been deprecated in favor of:

A fork of harryf's node-soupselect, which is originally a port of Simon Willison's soupselect for use with node.js and node-htmlparser.


$ npm install cheerio-soupselect


From the root folder:

$ make test



cheerio-soupselect supports all of the most common jQuery selectors, including multiple attribute selectors and multiple selectors.


soupselect also supports a bunch of basic filters, listed below. Each filter is implement according to the jQuery specification.

  • contains
  • empty
  • parent
  • has
  • header
  • not
  • eq
  • gt
  • lt
  • even
  • odd
  • first
  • last

Filter Extensions

cheerio-soupselect supports custom filters through the exported filters object. It's simple:

var soupselect = require("cheerio-soupselect"),
    filters = soupselect.filters;
filters["custom-filter"] = function(ctx, val){
    console.log("Hello filters!");
    return [];
var ret =, ":custom-filter('awesome arg')");

The ctx parameter provides an array of htmlparser2 DOMs, which are themselves arrays. These element are grouped by parent.

The val parameter provides access to everything inside the brackets of the filter, if anything.

A few notes about custom selectors:

  • Your custom function must return an array.

  • For the most part, you will not need to handle nesting filters/selectors. However, if you wish to modify the nested selector then, you may do so by modifiying val.

Something went wrong with that request. Please try again.