css-select
Advanced tools
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.
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 = cssSelect.is(dom.children[0], '.foo');
console.log(isMatch); // truePseudo-selectors
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'Cheerio is a fast, flexible, and lean implementation of core jQuery designed specifically for the server. It uses css-select under the hood for its CSS selector engine, providing a familiar jQuery-like API for manipulating the DOM.
jsdom is a pure-JavaScript implementation of many web standards, notably the WHATWG DOM and HTML Standards, for use with Node.js. It allows you to create a DOM from an HTML string and then interact with it as if you were in the browser, including using CSS selectors to find elements.
Soupselect is a module that ports the functionality of Python's BeautifulSoup library to Node.js. It allows for similar CSS selector-based element selection but is less actively maintained and has fewer features compared to css-select.
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.
Features:
Sizzle,
Qwery and
NWMatcher and .Most CSS engines written in JavaScript execute selectors left-to-right. That
means they 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.
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 of course
ca).
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.
CSSselect.is(elem, 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.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.
As defined by CSS 4 and / or jQuery.
<tagname>): Selects elements by their tag name. ): Selects elements that are descendants of the specified element.>): Selects elements that are direct children of the specified element.<): Selects elements that are direct parents of the specified
element. This follows an
old proposal
that has been made obsolete by the :has() pseudo-class.+): Selects elements that are the next sibling of the specified element.~): Selects elements that are siblings of the specified element.[attr=foo]), with supported comparisons:
[attr] (existential): Selects elements with the specified attribute,
whatever its value.=: Selects elements with the specified attribute and value.~=: Selects elements with the specified attribute and value, separated
by spaces.|=: Selects elements with the specified attribute and value, separated
by hyphens.*=: Selects elements with the specified attribute and value, anywhere in
the attribute value.^=: Selects elements with the specified attribute and value, beginning
at the beginning of the attribute value.$=: Selects elements with the specified attribute and value, ending at
the end of the attribute value.!=: Selects elements with the specified attribute and value, not equal
to the specified value.i and s can be added after the comparison to make the comparison
case-insensitive or case-sensitive (eg. [attr=foo i]). If neither is
supplied, css-select will follow the HTML spec's
case-sensitivity rules.,): Selects elements that match any of the specified selectors.*): Selects all elements.:not: Selects
elements that do not match the specified selector.:contains: Selects elements
that contain the specified text.:icontains: Selects elements that contain the specified text,
case-insensitively.:has: Selects
elements that have descendants that match the specified selector.:root: Selects
the root element.:empty:
Selects elements that have no children.:first-child:
Selects elements that are the first element child of their parent.:last-child:
Selects elements that are the last element child of their parent.:first-of-type:
Selects elements that are the first element of their type.:last-of-type:
Selects elements that are the last element of their type.:only-of-type:
Selects elements that are the only element of their type.:only-child:
Selects elements that are the only element child of their parent.:nth-child:
Selects elements that are the nth element child of their parent.:nth-last-child:
Selects elements that are the nth element child of their parent, counting
from the last child.:nth-of-type:
Selects elements that are the nth element of their type.:nth-last-of-type:
Selects elements that are the nth element of their type, counting from the
last child.:any-link:
Selects elements that are links.:link: Selects
elements that are links and have not been visited.:visited,
:hover,
:active
(these depend on optional Adapter methods, so these will only match
elements if implemented in Adapter):checked:
Selects input elements that are checked, or option elements that are
selected.:disabled:
Selects input elements that are disabled.:enabled:
Selects input elements that are not disabled.:required:
Selects input elements that are required.:optional:
Selects input elements that are not required.:parent: Selects elements
that have at least one child.:header: Selects header
elements.:selected: Selects
option elements that are selected.:button: Selects button
elements, and input elements of type button.:input: Selects input,
textarea, select, and button elements.:text: Selects input
elements of type text.:checkbox: Selects
input elements of type checkbox.:file: Selects input
elements of type file.:password: Selects
input elements of type password.:reset: Selects input
elements of type reset.:radio: Selects input
elements of type radio.:is, as well as
the aliases
:where, and
the legacy alias :matches: Selects elements that match any of the given
selectors.:scope:
Selects elements that are part of the scope of the current selector. This
uses the context from the passed options.License: BSD-2-Clause
To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.
css-select for enterpriseAvailable 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.
FAQs
a CSS selector compiler/engine
The npm package css-select receives a total of 35,003,055 weekly downloads. As such, css-select popularity was classified as popular.
We found that css-select demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
CAI is a new open source AI framework that automates penetration testing tasks like scanning and exploitation up to 3,600× faster than humans.
Security News
Deno 2.4 brings back bundling, improves dependency updates and telemetry, and makes the runtime more practical for real-world JavaScript projects.
Security News
CVEForecast.org uses machine learning to project a record-breaking surge in vulnerability disclosures in 2025.