nwmatcher

What is nwmatcher?

The nwmatcher npm package is a fast CSS selector engine and matcher, primarily used for matching DOM elements against CSS selectors. It is useful for tasks such as querying and filtering elements in a DOM-like structure.

What are nwmatcher's main functionalities?

Matching Elements

This feature allows you to check if a given DOM element matches a specific CSS selector.

const NWMatcher = require('nwmatcher');
const matcher = NWMatcher({ document });
const element = document.getElementById('example');
const isMatch = matcher.match(element, '.example-class');
console.log(isMatch); // true or false

Querying Elements

This feature allows you to query and retrieve all DOM elements that match a specific CSS selector.

const NWMatcher = require('nwmatcher');
const matcher = NWMatcher({ document });
const elements = matcher.select('.example-class');
console.log(elements); // Array of elements matching the selector

Custom Selectors

This feature allows you to register and use custom selectors for more advanced querying.

const NWMatcher = require('nwmatcher');
const matcher = NWMatcher({ document });
matcher.registerSelector('custom', function(element) {
  return element.hasAttribute('data-custom');
});
const elements = matcher.select(':custom');
console.log(elements); // Array of elements with the 'data-custom' attribute

Other packages similar to nwmatcher

sizzle

Sizzle is a pure-JavaScript CSS selector engine designed to be easily dropped in to a host library. It is highly optimized for performance and is used internally by jQuery. Compared to nwmatcher, Sizzle is more widely used and integrated into larger libraries like jQuery.

css-select

css-select is a library for selecting elements in a DOM-like structure using CSS selectors. It is part of the Cheerio library, which is used for server-side DOM manipulation. css-select is similar to nwmatcher but is often used in conjunction with Cheerio for server-side applications.

query-selector-shadow-dom

query-selector-shadow-dom is a library that extends the native querySelector and querySelectorAll methods to work with shadow DOM. It is useful for querying elements within shadow DOM trees, which nwmatcher does not natively support.

README

NWMatcher

A fast CSS selector engine and matcher.

Installation

To include NWMatcher in a standard web page:

<script type="text/javascript" src="nwmatcher.js"></script>

To use it with Node.js:

$ npm install nwmatcher.js

NWMatcher currently supports browsers (as a global, NW.Dom) and headless environments (as a CommonJS module).

Supported Selectors

Here is a list of all the CSS2/CSS3 Supported selectors.

Features and Compliance

You can read more about NWMatcher features and compliance on the wiki.

API

DOM Selection

first( selector, context )

Returns a reference to the first element matching selector, starting at context.

match( element, selector, context )

Returns true if element matches selector, starting at context; returns false otherwise.

select( selector, context, callback )

Returns an array of all the elements matching selector, starting at context. 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.

byName( name, from )

Returns an array of elements having the specified value name for their name attribute, optionally filtered to descendants of the element from.

getAttribute( element, attribute )

Return the value read from the attribute of element with name attribute, as a string.

hasAttribute( element, attribute )

Returns true element has an attribute with name attribute set; returns false otherwise.

Engine Configuration

configure( options )

The following options exist and can be set to true or false:

• CACHING: enable caching of results
• SHORTCUTS: allow accepting mangled selectors
• SIMPLENOT: disallow nested complex :not() selectors
• UNIQUE_ID: disallow multiple elements with same ID
• USE_QSAPI: enable native querySelectorAll if available
• USE_HTML5: enable special HTML5 rules, related to the relationship between :checked and :selected
• VERBOSITY: choose between throwing errors or just console warnings

Example:

NW.Dom.configure( { USE_QSAPI: false, VERBOSITY: false } );

registerOperator( symbol, resolver )

Registers a new symbol and its matching resolver in the operators table. Example:

NW.Dom.registerOperator( '!=', 'n!="%m"' );

registerSelector( name, rexp, func )

Registers a new selector, with the matching regular expression and the appropriate resolver function, in the selectors table.