{"id":11471,"library":"nwmatcher","title":"NWMatcher CSS Selector Engine","description":"NWMatcher is a fast and W3C CSS3-compliant JavaScript selector engine, currently at version 1.4.4. It provides robust methods for selecting, matching, and traversing DOM elements using CSS selectors, aiming for behavior consistent with modern web browsers. The library is actively maintained through regular bug fixes, performance enhancements, and improved compliance with CSS specifications, particularly for headless environments like Node.js with JSDOM. It distinguishes itself by offering a reliable, standalone solution for scenarios where native `querySelectorAll` might not be available, or when fine-grained control over selector parsing and matching is required. This includes comprehensive support for CSS2/CSS3 selectors, pseudo-classes, and extensive configuration options to tailor its behavior. Recent releases focus on addressing specific behavioral quirks, optimizing DOM traversal, and ensuring broad W3C compatibility across diverse environments.","status":"active","version":"1.4.4","language":"javascript","source_language":"en","source_url":"git://github.com/dperini/nwmatcher","tags":["javascript","css","matcher","selector","ender"],"install":[{"cmd":"npm install nwmatcher","lang":"bash","label":"npm"},{"cmd":"yarn add nwmatcher","lang":"bash","label":"yarn"},{"cmd":"pnpm add nwmatcher","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For TypeScript with CommonJS interop, `import * as nwmatcher` is recommended. The `nwmatcher` module object provides the `init` method, which is necessary to configure the engine with a DOM `window` object in headless environments like Node.js with JSDOM.","wrong":"import nwmatcher from 'nwmatcher';","symbol":"nwmatcher","correct":"import * as nwmatcher from 'nwmatcher';"},{"note":"The `NW` object (often referenced as `NW.Dom` in browser contexts) is the primary API entry point containing methods like `select`, `first`, and `match`. In Node.js, it's obtained by calling `nwmatcher.init(window)`. In browsers, `NW.Dom` is globally available after including the script.","wrong":"import { select, match } from 'nwmatcher';","symbol":"NW","correct":"import * as nwmatcher from 'nwmatcher'; const NW = nwmatcher.init(window);"}],"quickstart":{"code":"import { JSDOM } from 'jsdom';\nimport * as nwmatcher from 'nwmatcher'; // For TypeScript with CommonJS interop\n\n// 1. Setup a JSDOM environment to simulate a browser DOM\nconst dom = new JSDOM(`\n\n \n NWMatcher Example\n \n \n
\n \n`);\n\nconst { window } = dom;\nconst document = window.document;\n\n// 2. Initialize NWMatcher with the JSDOM window object for headless environments.\n// In a browser, NW.Dom would typically be available globally.\nconst NW = nwmatcher.init(window);\n\nconsole.log('--- DOM Selection Examples ---');\n\n// Select all elements matching a selector\nconst allParagraphs = NW.select('p', document);\nconsole.log(`Found ${allParagraphs.length} paragraphs.`);\n// Expected: 3 paragraphs\n\n// Select the first element matching a selector\nconst firstImportantParagraph = NW.first('p.important', document);\nconsole.log(`First important paragraph text: \"${firstImportantParagraph?.textContent}\"`);\n// Expected: \"First paragraph\"\n\n// Match an element against a selector\nconst targetElement = document.getElementById('myButton');\nconst matchesDisabled = NW.match(targetElement, ':disabled');\nconsole.log(`Button matches ':disabled': ${matchesDisabled}`);\n// Expected: true\n\n// Using context for selection\nconst container = document.getElementById('container');\nconst paragraphsInContainer = NW.select('.text', container);\nconsole.log(`Found ${paragraphsInContainer.length} elements with class 'text' within #container.`);\n// Expected: 3 (p.text.important, span.text, p.text)\n\nconsole.log('\\n--- Engine Configuration Example ---');\n// Disable native Query Selector API usage and suppress errors for demonstration\nNW.configure({ USE_QSAPI: false, VERBOSITY: false, LOGERRORS: false });\nconsole.log('NWMatcher configured to not use native QSA and suppress errors.');\n\n// Re-run a selection with new configuration\nconst allLinks = NW.select('a.link');\nconsole.log(`Found ${allLinks.length} links after re-configuration.`);\n// Expected: 1 link\n\n// Example of DOM helper method\nconst myButtonElement = NW.byId('myButton');\nconsole.log(`Found button by ID: ${myButtonElement?.id}`);\n// Expected: \"myButton\"\n\n// Example of attribute getter\nconst linkHref = NW.getAttribute(allLinks[0], 'href');\nconsole.log(`Href of the link: ${linkHref}`);\n// Expected: \"#\" ","lang":"typescript","description":"Demonstrates initializing NWMatcher in a Node.js JSDOM environment, performing various DOM selections, matching elements, and configuring engine options. It covers `select`, `first`, `match`, `byId`, `getAttribute` methods and `configure`."},"warnings":[{"fix":"Ensure all class names in selectors match the exact casing used in the HTML/DOM. Prior to v1.4.1, case-insensitivity might have been tolerated, leading to unexpected failures post-update.","message":"Class attribute selectors became case-sensitive to mimic browser behavior more closely.","severity":"breaking","affected_versions":">=1.4.1"},{"fix":"Review selectors that might implicitly target or interact with non-Element nodes (e.g., text nodes, comments). Ensure selectors are robust and explicitly target `Element` nodes where necessary.","message":"Improved DOM walking in `v1.4.2` explicitly avoids using unsupported DOM methods on non-'Element' nodes. While a fix, it might subtly alter behavior if previous versions erroneously processed non-element nodes in specific selector contexts.","severity":"gotcha","affected_versions":">=1.4.2"},{"fix":"Always explicitly configure NWMatcher using `NW.configure({ USE_QSAPI: true, SIMPLENOT: false })` or similar, depending on your needs. For full CSS3 compliance and performance, it's often best to enable native QSA and allow complex `:not()` selectors unless specific compatibility issues arise.","message":"The `configure()` method allows disabling native Query Selector API (`USE_QSAPI: false`) or disallowing complex selectors nested in `:not()` classes (`SIMPLENOT: true`). Misconfiguration can lead to unexpected selection results or performance characteristics.","severity":"gotcha","affected_versions":">=1.3.4"},{"fix":"For environments without native `querySelectorAll` (or where it's buggy), consider using `nwmatcher-noqsa.js` and configuring NWMatcher with `USE_QSAPI: false` to force its internal engine. For Node.js with JSDOM, using the full version with `USE_QSAPI: true` is generally fine.","message":"A minimal `nwmatcher-noqsa.js` version is available, specifically recommended for headless environments or older browsers like IE < 9 that lack robust native Query Selector API support. Using the full version in these environments when `USE_QSAPI` is enabled might lead to errors or degraded performance.","severity":"gotcha","affected_versions":">=1.3.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Instead of expecting a global `NW.Dom`, use `const nwmatcher = require('nwmatcher'); const NW = nwmatcher.init(window);` (for CommonJS) or `import * as nwmatcher from 'nwmatcher'; const NW = nwmatcher.init(window);` (for ES Modules/TypeScript with JSDOM's `window` object).","cause":"In Node.js or other headless environments, the NWMatcher engine needs to be explicitly initialized with a DOM `window` object, and the resulting API object assigned to a variable.","error":"ReferenceError: NW is not defined"},{"fix":"Ensure that the casing of class names in your CSS selectors precisely matches the casing of the `class` attributes in your HTML/DOM structure.","cause":"Since `v1.4.1`, class attribute selectors became case-sensitive, mimicking browser behavior. If your HTML or selectors used mixed casing (e.g., class `MyClass` but selector `.myclass`), they will no longer match.","error":"Selectors using class names are failing to match elements that previously worked."},{"fix":"Ensure `NW.configure({ VERBOSITY: false, LOGERRORS: false });` is used to suppress both thrown exceptions and console logging. If issues persist, verify if a specific 'shunt' method or configuration option was introduced or needs to be set.","cause":"While `LOGERRORS: false` in `configure()` mutes standard logging, the `v1.4.0` release notes mention an additional 'shunt flag' for muting *all* errors/warnings, implying `LOGERRORS` might not cover all scenarios or there could be a default verbosity.","error":"NWMatcher throws errors/warnings to the console despite `LOGERRORS` being set to `false`."}],"ecosystem":"npm"}