{"id":11615,"library":"query-selector","title":"Cross-Environment querySelectorAll Implementation","description":"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.","status":"maintenance","version":"2.0.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/yiminghe/query-selector","tags":["javascript"],"install":[{"cmd":"npm install query-selector","lang":"bash","label":"npm"},{"cmd":"yarn add query-selector","lang":"bash","label":"yarn"},{"cmd":"pnpm add query-selector","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for using the querySelectorAll implementation in a Node.js environment to create a DOM context.","package":"jsdom","optional":true}],"imports":[{"note":"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.","wrong":"const querySelectorAll = require('query-selector');","symbol":"querySelectorAll","correct":"const querySelectorAll = require('query-selector').default;"},{"note":"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.","wrong":"import { querySelectorAll } from 'query-selector';","symbol":"querySelectorAll (ESM)","correct":"import querySelectorAll from 'query-selector';"},{"note":"For standalone browser usage, the library exposes 'querySelectorAll' as a global variable after including its build script.","symbol":"Standalone Browser Global","correct":"\n"}],"quickstart":{"code":"const querySelectorAll = require('query-selector').default;\nconst { JSDOM } = require('jsdom');\n\n// Create a JSDOM environment for Node.js to simulate a browser DOM\nconst dom = new JSDOM('12
');\nconst doc = dom.window.document;\n\nconsole.log('--- Using native doc.querySelectorAll ---');\nconst nativeElements = doc.querySelectorAll('#t span');\nconsole.log('Native result length:', nativeElements.length);\nconsole.log('Native first element innerHTML:', nativeElements[0].innerHTML);\n\nconsole.log('\\n--- Using query-selector package ---');\nconst customElements = querySelectorAll('#t span', doc);\nconsole.log('Custom result length:', customElements.length);\nconsole.log('Custom first element innerHTML:', customElements[0].innerHTML);\n\n// Demonstrates calling the custom querySelectorAll with a specific context (the document)\n// The output should be identical, showcasing its polyfill capability.\n// In a browser, the 'doc' argument would often be 'document' or 'this'.","lang":"javascript","description":"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."},"warnings":[{"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.","message":"Performance 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update all CommonJS `require` statements from `const querySelectorAll = require('query-selector');` to `const querySelectorAll = require('query-selector').default;`.","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Convert the `NodeList` to an Array when array methods are needed: `Array.from(querySelectorAll('.selector'))` or `[...querySelectorAll('.selector')]`.","message":"The `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]`).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const querySelectorAll = require('query-selector');` to `const querySelectorAll = require('query-selector').default;`","cause":"In version 2.0.0+, the `querySelectorAll` function is exported as a default property on the module, not the module itself, in CommonJS.","error":"TypeError: require(...) is not a function"},{"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.","cause":"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.","error":"TypeError: (0, _queryselector.default) is not a function"},{"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); }`","cause":"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`.","error":"Cannot read properties of undefined (reading 'innerHTML') for a selected element"}],"ecosystem":"npm"}