# nwmatcher

> A CSS3-compliant JavaScript selector engine.

Latest version **1.4.4** (published 2018-03-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install nwmatcher
pnpm add nwmatcher
yarn add nwmatcher
bun add nwmatcher
```

## Health

**Score 28/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 1.4.4 |
| Published | 2018-03-17 |
| First published | 2012-01-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/nwmatcher) |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 148.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 314 |
| Author | Diego Perini |
| Maintainers | diego, rvagg |
| Keywords | css, matcher, selector, ender |

## Links

- npm: https://www.npmjs.com/package/nwmatcher
- Repository: https://github.com/dperini/nwmatcher
- Homepage: http://javascript.nwbox.com/NWMatcher/
- Issues: http://github.com/dperini/nwmatcher/issues
- npm.io page: https://npm.io/package/nwmatcher

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 1.4.4 (latest) — 2018-03-17
- 1.4.3 — 2017-10-12
- 1.4.2 — 2017-09-23
- 1.4.1 — 2017-06-19
- 1.4.0 — 2017-05-21
- 1.3.9 — 2016-10-25
- 1.3.8 — 2016-06-13
- 1.3.7 — 2015-11-20
- 1.3.6 — 2015-07-13
- 1.3.5 — 2015-07-13
- 1.3.4 — 2015-01-02
- 1.3.3 — 2014-03-30
- 1.3.2 — 2014-03-26
- 1.3.1 — 2013-02-11
- 1.3.0 — 2013-02-08
- … 1 more at https://npm.io/package/nwmatcher/versions

## README

# [NWMatcher](http://dperini.github.io/nwmatcher/)

A fast CSS selector engine and matcher.


## Installation

To include NWMatcher in a standard web page:

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

To use it with Node.js:

```
$ npm install nwmatcher
```

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](https://github.com/dperini/nwmatcher/wiki/CSS-supported-selectors).


## Features and Compliance

You can read more about NWMatcher [features and compliance](https://github.com/dperini/nwmatcher/wiki/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 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`:

* `CACHING`:   false - false to disable caching of result sets, true to enable
* `ESCAPECHR`: true  - true to allow CSS escaped identifiers, false to disallow
* `NON_ASCII`: true  - true to allow identifiers containing non-ASCII (utf-8) chars
* `SELECTOR3`: true  - switch syntax RE, true to use Level 3, false to use Level 2
* `UNICODE16`: true  - true to allow identifiers containing Unicode (utf-16) chars
* `SHORTCUTS`: false - false to disable mangled selector strings like "+div" or "ul>"
* `SIMPLENOT`: true  - true to disallow complex selectors nested in ':not()' classes
* `SVG_LCASE`: false - false to disable matching lowercase tag names of SVG elements
* `UNIQUE_ID`: true  - true to disallow multiple elements with the same id (strict)
* `USE_HTML5`: true  - true to use HTML5 specs for ":checked" and similar UI states
* `USE_QSAPI`: true  - true to use browsers native Query Selector API if available
* `VERBOSITY`: true  - true to throw exceptions, false to skip throwing exceptions
* `LOGERRORS`: true  - true to print console errors or warnings, false to mute them

Example:

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

#### `registerOperator( symbol, resolver )`

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

```js
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.

---
_Source: https://npm.io/package/nwmatcher · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._