Gathering detailed insights and metrics for css-select
css-select-base-adapter
Provides some base functions needed by a css-select adapter so that you don't have to implement the whole thing.
css-blank-pseudo
Style form elements when they are empty
cheerio-select
CSS selector engine supporting jQuery selectors
postcss-focus-visible
Use the :focus-visible pseudo-selector in CSS
npm install css-selectTypescript
Module System
Node Version
NPM Version
97.5
Supply Chain
99.6
Quality
75.8
Maintenance
100
Vulnerability
100
License
TypeScript (100%)
Total Downloads
6,793,874,951
Last Day
6,117,472
Last Week
27,708,260
Last Month
125,081,660
Last Year
1,608,247,060
558 Stars
1,582 Commits
70 Forks
7 Watching
7 Branches
22 Contributors
Minified
Minified + Gzipped
Latest Version
5.1.0
Package Id
css-select@5.1.0
Unpacked Size
218.83 kB
Size
33.52 kB
File Count
92
NPM Version
8.5.5
Node Version
17.9.0
Cumulative downloads
Total Downloads
Last day
-4.7%
6,117,472
Compared to previous day
Last week
-16.4%
27,708,260
Compared to previous week
Last month
3.4%
125,081,660
Compared to previous month
Last year
6.5%
1,608,247,060
Compared to previous year
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 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.
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:
1[ 2 { type: "tag", name: "a" }, 3 { type: "descendant" }, 4 { type: "tag", name: "b" }, 5];
(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.
1const 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>) )>)<)+)~)[attr=foo]), with supported comparisons:
[attr] (existential)=~=|=*=^=$=!=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.:not:contains:icontains (case-insensitive version of :contains):has:root:empty:parent: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,:link,
:any-link:visited,
:hover,
:active
(these depend on optional Adapter methods, so these will only match
elements if implemented in Adapter):selected,
:checked:enabled,
:disabled:required,
:optional:header,
:button,
:input,
:text,
:checkbox,
:file,
:password,
:reset,
:radio etc.:is, plus its
legacy alias :matches:scope
(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.
No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
30 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10
Reason
no binaries found in the repo
Reason
license file detected
Details
Reason
SAST tool is run on all commits
Details
Reason
0 existing vulnerabilities detected
Reason
dependency not pinned by hash detected -- score normalized to 4
Details
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
Reason
detected GitHub workflow tokens with excessive permissions
Details
Reason
project is not fuzzed
Details
Score
Last Scanned on 2025-01-27
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More