NWSAPI is the development progress of NWMATCHER aiming at Selectors Level 4 conformance. It has been completely reworked to be easily extended and maintained. It is a right-to-left selector parser and compiler written in pure Javascript with no external dependencies. It was initially thought as a cross browser library to improve event delegation and web page scraping in various frameworks but it has become a popular replacement of the native CSS selection and matching functionality in newer browsers and headless environments.
It uses regular expressions to parse CSS selector strings and metaprogramming to transforms these selector strings into Javascript function resolvers. This process is executed only once for each selector string allowing memoization of the function resolvers and achieving unmatched performances.
Returns a reference to the nearest ancestor element matching selector, starting at context. Returns null if no element is found. If callback is provided, it is invoked for the matched element.
first( selector, context, callback )
Returns a reference to the first element matching selector, starting at context. Returns null if no element matches. If callback is provided, it is invoked for the matched element.
match( selector, element, callback )
Returns true if element matches selector, starting at context; returns false otherwise. If callback is provided, it is invoked for the matched element.
select( selector, context, callback )
Returns an array of all the elements matching selector, starting at context; returns empty Array otherwise. If callback is provided, it is invoked for each matching element.
DOM Helpers
byId( id, from )
Returns a reference to the first element with ID id, optionally filtered to descendants of the element from.
byTag( tag, from )
Returns an array of elements having the specified tag name tag, optionally filtered to descendants of the element from.
byClass( class, from )
Returns an array of elements having the specified class name class, optionally filtered to descendants of the element from.
Engine Configuration
configure( options )
The following is the list of currently available configuration options, their default values and descriptions, they are boolean flags that can be set to true or false:
IDS_DUPES: true - true to allow using multiple elements having the same id, false to disallow
LIVECACHE: true - true for caching both results and resolvers, false for caching only resolvers
MIXEDCASE: true - true to match tag names case insensitive, false to match using case sensitive
LOGERRORS: true - true to print errors and warnings to the console, false to mute both of them
Registers a new selector, the matching RE and the resolver function, in the selectors table. Example:
NW.Dom.registerSelector('Controls', /^\:(control)(.*)/i, (function(global) { return function(match, source, mode, callback) { var status = true; source = 'if(/^(button|input|select|textarea)/i.test(e.nodeName)){' + source + '}'; return { 'source': source, 'status': status }; }; })(this));
💖 Support & Sponsoring
NWSAPI powers millions of builds, web scrapers, and testing suites every single day—including key infrastructure like jsdom.
Maintaining a zero-dependency, ultra-fast CSS engine that strictly adheres to evolving W3C Selectors specifications takes significant time, research, and testing. If NWSAPI helps your company save time, build features, or run reliable tests, please consider supporting its ongoing maintenance!
Why Sponsor?
For Developers: Keep the project actively maintained, bug-free, and ahead of new browser standard updates.
For Businesses: Ensure the stability and long-term security of a critical dependency in your toolchain.
💳 Ways to Contribute
Choose the platform that works best for you or your organization:
GitHub Sponsors: Monthly tier-based sponsorship directly on GitHub.
Open Collective: Transparent funding for open-source projects, ideal for corporate backing.
Patreon: Recurring monthly support with backer rewards.
Ko-fi: Fast one-time tips or recurring micro-donations.