Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

a CSS selector compiler/engine

branch: master

Fetching latest commit…


Cannot retrieve the latest commit at this time

Octocat-spinner-32 lib compile: don't parse token again in :not
Octocat-spinner-32 test compile: initial support for contexts
Octocat-spinner-32 .travis.yml added coveralls
Octocat-spinner-32 LICENSE added license
Octocat-spinner-32 readme: use travis svg badge
Octocat-spinner-32 browser_functions.js [browser] return an array of children
Octocat-spinner-32 index.js
Octocat-spinner-32 package.json use jshint

CSSselect NPM version Build Status Downloads Coverage

a CSS selector compiler/engine


CSSselect turns CSS selectors into functions that tests if elements match them. When searching for elements, testing is executed "from the top", similar to how browsers execute CSS selectors.

In its default configuration, CSSselect queries the DOM structure of the domhandler module.


  • Full implementation of CSS3 selectors
  • Partial implementation of jQuery/Sizzle extensions
  • 100% test coverage


var CSSselect = require("CSSselect");

CSSselect(query, elems, options)

  • query can be either a function or a string. If it's a string, the string is compiled as a CSS selector.
  • elems can be either an array of elements, or a single element. If it is an element, its children will be used (so we're working with an array again).
  • options is described below.

Queries elems, returns an array containing all matches.

Aliases: CSSselect.selectAll(query, elems), CSSselect.iterate(query, elems).


Compiles the query, returns the function., query, options)

Tests whether or not an element is matched by query. query can be either a CSS selector or a function.

CSSselect.selectOne(query, elems, options)

Arguments are the same as for CSSselect(query, elems). Only returns the first match, or null if there was no match.


  • xmlMode: When enabled, tag names will be case-sensitive. Default: false.
  • strict: Limits the module to only use CSS3 selectors. Default: false.
  • rootFunc: The last function in the stack. Will be called with the last element that's looked at. Should return true if it shouldn't be called again for every matching subselector.


The common approach of executing CSS selectors (used eg. by Sizzle, nwmatcher and qwery) is to execute every component of the selector in order, from left to right. The selector a b for example will first look for a elements, then search these for b elements.

While this works, it has some downsides: Children of as will be checked multiple times, first, to check if they are also as, then, for every superior a once, if they are bs. Using Big O notation, that would be O(n^2).

The far more efficient approach is to first look for b elements, then check if they have superior a elements: Using big O notation again, that would be O(n).

And that's exactly what CSSselect does.


By stacking functions!

//TODO: Better explanation. For now, if you're interested, have a look at the source code.

Supported selectors:

  • Universal (*)
  • Tag (<tagname>)
  • Descendant ()
  • Child (>)
  • Parent (<) *
  • Sibling (+)
  • Adjacent (~)
  • Attribute ([attr=foo]), with supported comparisons:
    • [attr] (existential)
    • =
    • ~=
    • |=
    • *=
    • ^=
    • $=
    • != *
    • Also, i can be added after the comparison to make the comparison case-insensitive (eg. [attr=foo i]) *
  • Pseudos:
    • :not
    • :contains *
    • :has *
    • :root
    • :empty
    • :parent *
    • :[first|last]-child[-of-type]
    • :only-of-type, :only-child
    • :nth-[last-]child[-of-type]
    • :selected *, :checked
    • :enabled, :disabled
    • :header, :button, :input, :text, :checkbox, :file, :password, :reset, :radio etc. *

*: Non-standard extensions

License: BSD-like

Something went wrong with that request. Please try again.