a CSS selector compiler & engine
BSD-2-CLAUSE License
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
andNWMatcher
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 a
s will be checked
multiple times; first, to check if they are also a
s, then, for every superior
a
once, if they are b
s. 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
c
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 anoptions
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 lastadapter
: The adapter to use when interacting with the backing DOMdomutils
module.context
: The context of the current query. Used to limit the scope of:scope
pseudo-class.relativeSelector
: By default, selectors are relative to the context
,a b c
with context b
will never give any results.) If relativeSelector
false
, selectors won't becontext
.cacheResults
: Allow css-select to cache results for some selectors,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: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,=
: Selects elements with the specified attribute and value.~=
: Selects elements with the specified attribute and value, separated|=
: Selects elements with the specified attribute and value, separated*=
: Selects elements with the specified attribute and value, anywhere^=
: Selects elements with the specified attribute and value, beginning$=
: Selects elements with the specified attribute and value, ending at!=
: Selects elements with the specified attribute and value, not equali
and s
can be added after the comparison to make the comparison[attr=foo i]
). If neither is,
): Selects elements that match any of the specified selectors.*
): Selects all elements.:not
: Selects:contains
: Selects:icontains
: Selects elements that contain the specified text,:has
: Selects:root
::empty
::first-child
::last-child
::first-of-type
::last-of-type
::only-of-type
::only-child
::nth-child
::nth-last-child
::nth-of-type
::nth-last-of-type
::any-link
::link
::visited
,:hover
,:active
Adapter
methods, so these will only matchAdapter
):checked
:input
elements that are checked, or option
elements that are:disabled
::enabled
::required
::optional
::parent
: Selects:header
: Selects header:selected
: Selectsoption
elements that are selected.:button
: Selects buttoninput
elements of type button
.:input
: Selects input
,textarea
, select
, and button
elements.:text
: Selects input
text
.:checkbox
: Selectsinput
elements of type checkbox
.:file
: Selects input
file
.:password
: Selectsinput
elements of type password
.:reset
: Selects input
reset
.:radio
: Selects input
radio
.:is
, as well:where
, and:matches
: Selects elements that match any of the:scope
: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.