Sign inDemoInstall


Package Overview
File Explorer

Advanced tools

Install Socket

Protect your apps from supply chain attacks



a CSS selector compiler/engine


Version published
Weekly downloads
decreased by-16.8%

Weekly downloads

Package description

What is css-select?

The css-select package is a CSS selector engine that enables querying and manipulating HTML and XML documents using CSS selectors. It can be used to select elements from a DOM tree, similar to how you would select elements in the browser using CSS.

What are css-select's main functionalities?

Selecting elements

This feature allows you to select elements from a DOM tree using CSS selectors. The code sample demonstrates selecting all <p> elements from a given HTML string.

const cssSelect = require('css-select');
const parseHTML = require('htmlparser2').parseDocument;
const dom = parseHTML('<div><p>Hello World</p></div>');
const elems = cssSelect('p', dom);
console.log(elems[0].children[0].data); // 'Hello World'

Matching elements

This feature checks if a given element matches a CSS selector. The code sample demonstrates checking if the first child of the root element has a class 'foo'.

const cssSelect = require('css-select');
const parseHTML = require('htmlparser2').parseDocument;
const dom = parseHTML('<div class='foo'><p>Hello World</p></div>');
const isMatch =[0], '.foo');
console.log(isMatch); // true


This feature allows the use of pseudo-selectors to select elements. The code sample demonstrates selecting the first child of a list.

const cssSelect = require('css-select');
const parseHTML = require('htmlparser2').parseDocument;
const dom = parseHTML('<ul><li>Item 1</li><li>Item 2</li></ul>');
const firstItem = cssSelect(':first-child', dom);
console.log(firstItem[0].children[0].data); // 'Item 1'

Other packages similar to css-select



css-select NPM version Build Status Downloads Coverage

A CSS selector compiler and engine


As a compiler, css-select turns CSS selectors into functions that tests if elements match them.

As an engine, css-select looks through a DOM tree, searching for elements. Elements are tested "from the top", similar to how browsers execute CSS selectors.

In its default configuration, css-select queries the DOM structure of the domhandler module (also known as htmlparser2 DOM). To query alternative DOM structures, see Options below.


  • 🔬 Full implementation of CSS3 selectors, as well as most CSS4 selectors
  • 🧪 Partial implementation of jQuery/Sizzle extensions (see cheerio-select for the remaining selectors)
  • 🧑‍🔬 High test coverage, including the full test suites from Sizzle, Qwery and NWMatcher and .
  • 🥼 Reliably great performance


Most CSS engines written in JavaScript execute selectors left-to-right. That means thet execute every component of the selector in order, from left to right. As an example: For the selector a b, these engines will first query for a elements, then search these for b elements. (That's the approach of eg. Sizzle, Qwery and NWMatcher.)

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^(k+1)), where k is the number of descendant selectors (that's the space in the example above).

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). That's called right-to-left execution.

And that's what css-select does – and why it's quite performant.

How does it work?

By building a stack of functions.

Wait, what?

Okay, so let's suppose we want to compile the selector a b, for right-to-left execution. We start by parsing the selector. This turns the selector into an array of the building blocks. That's what the css-what module is for, if you want to have a look.

Anyway, after parsing, we end up with an array like this one:

    { type: "tag", name: "a" },
    { type: "descendant" },
    { type: "tag", name: "b" },

(Actually, this array is wrapped in another array, but that's another story, involving commas in selectors.)

Now that we know the meaning of every part of the selector, we can compile it. That is where things become interesting.

The basic idea is to turn every part of the selector into a function, which takes an element as its only argument. The function checks whether a passed element matches its part of the selector: If it does, the element is passed to the next function representing the next part of the selector. That function does the same. If an element is accepted by all parts of the selector, it matches the selector and double rainbow ALL THE WAY.

As said before, we want to do right-to-left execution with all the big O improvements. That means elements are passed from the rightmost part of the selector (b in our example) to the leftmost (which would be c of course a).

For traversals, such as the descendant operating the space between a and b, we walk up the DOM tree, starting from the element passed as argument.

//TODO: More in-depth description. Implementation details. Build a spaceship.


const CSSselect = require("css-select");

Note: css-select throws errors when invalid selectors are passed to it. This is done to aid with writing css selectors, but can be unexpected when processing arbitrary strings.

CSSselect.selectAll(query, elems, options)

Queries elems, returns an array containing all matches.

  • query can be either a CSS selector or a function.
  • elems can be either an array of elements, or a single element. If it is an element, its children will be queried.
  • options is described below.

Aliases: default export, CSSselect.iterate(query, elems).

CSSselect.compile(query, options)

Compiles the query, returns a 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.selectAll(query, elems). Only returns the first match, or null if there was no match.


All options are optional.

  • xmlMode: When enabled, tag names will be case-sensitive. Default: false.
  • rootFunc: The last function in the stack, will be called with the last element that's looked at.
  • adapter: The adapter to use when interacting with the backing DOM structure. By default it uses the domutils module.
  • context: The context of the current query. Used to limit the scope of searches. Can be matched directly using the :scope pseudo-class.
  • relativeSelector: By default, selectors are relative to the context, which means that no parent elements of the context will be matched. (Eg. a b c with context b will never give any results.) If relativeSelector is set to false, selectors won't be absolutized and selectors can test for parent elements outside of the context.
  • cacheResults: Allow css-select to cache results for some selectors, sometimes greatly improving querying performance. Disable this if your document can change in between queries with the same compiled selector. Default: true.
  • pseudos: A map of pseudo-class names to functions or strings.
Custom Adapters

A custom adapter must match the interface described here.

You may want to have a look at domutils to see the default implementation, or at css-select-browser-adapter for an implementation backed by the DOM.

Supported selectors

As defined by CSS 4 and / or jQuery.

License: BSD-2-Clause

Security contact information

To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.

css-select for enterprise

Available as part of the Tidelift Subscription

The maintainers of css-select and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.



Last updated on 27 Apr 2022

Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc