Registry / web-framework / query-selector

query-selector

library0.99.4jsnpmunverified

This package provides a JavaScript implementation of `querySelectorAll`, designed to offer consistent DOM querying functionality across various environments, including Node.js (with `jsdom`) and older browser contexts. The current stable version is 2.0.0, released in August 2019. The project exhibits a slow release cadence, with no substantial updates since its last major version. Its key differentiator is providing a polyfill-like solution for `querySelectorAll` where native implementations might be absent or incomplete, ensuring broader compatibility for selector-based DOM manipulation. It serves as a foundational utility for projects requiring reliable CSS selector-based element retrieval outside of modern browser engines.

web-framework testing

npm install query-selector

github ↗package ↗

INSTALL

IMPORT

SIG · QUERY-SELECTOR

query-selector

web-frameworkjavascriptv0.99.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

querySelectorAll

✓ const querySelectorAll = require('query-selector').default;

✗ const querySelectorAll = require('query-selector');

Since v2.0.0, the package exports the function as a default export on the module object for CommonJS. Attempting to require the module directly will return the module object, not the function.

querySelectorAll (ESM)

✓ import querySelectorAll from 'query-selector';

✗ import { querySelectorAll } from 'query-selector';

While primarily a CommonJS package from 2019, if used in an ESM context via a transpiler or bundler, the CommonJS default export typically translates to a default ESM import.

Standalone Browser Global

✓ <script src="/build/query-selector-standalone-debug.js"></script> <script>console.log(querySelectorAll('#t span'));</script>

For standalone browser usage, the library exposes 'querySelectorAll' as a global variable after including its build script.

This quickstart demonstrates how to use `query-selector` within a Node.js environment by integrating it with `jsdom` to provide a document context. It shows both the native `querySelectorAll` (if available in the JSDOM instance) and the package's implementation, highlighting its usage and expected output.

const querySelectorAll = require('query-selector').default; const { JSDOM } = require('jsdom'); // Create a JSDOM environment for Node.js to simulate a browser DOM const dom = new JSDOM('<html><body><div id="t"><span>1</span><span>2</span></div></body></html>'); const doc = dom.window.document; console.log('--- Using native doc.querySelectorAll ---'); const nativeElements = doc.querySelectorAll('#t span'); console.log('Native result length:', nativeElements.length); console.log('Native first element innerHTML:', nativeElements[0].innerHTML); console.log('\n--- Using query-selector package ---'); const customElements = querySelectorAll('#t span', doc); console.log('Custom result length:', customElements.length); console.log('Custom first element innerHTML:', customElements[0].innerHTML); // Demonstrates calling the custom querySelectorAll with a specific context (the document) // The output should be identical, showcasing its polyfill capability. // In a browser, the 'doc' argument would often be 'document' or 'this'.

Debug

Known issues

gotchaPerformance of this JavaScript-based implementation may be slower compared to native browser `querySelectorAll` methods, especially for complex selectors or large DOM trees. Modern browser engines are highly optimized for this task.

fix

For browser environments with native `querySelectorAll` support, prefer the native implementation. Use this package primarily for environments lacking native support or for specific polyfill requirements.

affects: >=1.0.0

gotchaThe package, last updated in 2019, may not fully support all modern CSS Selectors Level 4 features or advanced pseudo-classes that newer browser engines have implemented. This could lead to unexpected results or unsupported selectors.

fix

Thoroughly test complex or newer CSS selectors when using this package. If specific modern selectors are critical, consider alternative, more actively maintained DOM manipulation libraries or ensure a modern browser environment.

affects: >=1.0.0

breakingVersion 2.0.0 changed the CommonJS export mechanism, requiring developers to access the function via `.default`. Directly requiring the module `require('query-selector')` without `.default` will no longer return the `querySelectorAll` function itself, but the module object.

fix

Update all CommonJS `require` statements from `const querySelectorAll = require('query-selector');` to `const querySelectorAll = require('query-selector').default;`.

affects: >=2.0.0

gotchaThe `querySelectorAll` function (both native and this implementation) returns a `NodeList` (or similar array-like object in Node.js with `jsdom`), not a standard JavaScript Array. This means methods like `map`, `filter`, or `reduce` are not directly available without explicit conversion (e.g., `Array.from(nodeList)` or `[...nodeList]`).

fix

Convert the `NodeList` to an Array when array methods are needed: `Array.from(querySelectorAll('.selector'))` or `[...querySelectorAll('.selector')]`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: require(...) is not a function

In version 2.0.0+, the `querySelectorAll` function is exported as a default property on the module, not the module itself, in CommonJS.

fix

Change `const querySelectorAll = require('query-selector');` to `const querySelectorAll = require('query-selector').default;`

TypeError: (0, _queryselector.default) is not a function

This error typically occurs in a transpiled ESM environment when trying to import a CommonJS module's named export as a default, or when a default export is incorrectly accessed from an object.

fix

Ensure you are using `import querySelectorAll from 'query-selector';` for default imports, or verify your transpilation configuration correctly handles CommonJS default exports for modules like this.

Cannot read properties of undefined (reading 'innerHTML') for a selected element

The selector did not match any elements, resulting in an empty NodeList (or similar), and attempting to access an index like `[0]` on it returns `undefined`.

fix

Always check the `length` property of the returned `NodeList` before attempting to access elements by index: `const elements = querySelectorAll('.my-selector'); if (elements.length > 0) { console.log(elements[0].innerHTML); }`

Upgrade

Version history

0.99.4latest on npm

Audit

Dependencies

jsdomoptionalRequired for using the querySelectorAll implementation in a Node.js environment to create a DOM context.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/yiminghe/query-selector ↗

packagehttps://www.npmjs.com/package/query-selector ↗