{"id":11945,"library":"resq","title":"React Element Selector Query (RESQ)","description":"resq (React Element Selector Query) is a JavaScript library designed to query React components and HTML elements within the React Virtual DOM, emulating the functionality of `querySelector` and `querySelectorAll` for native DOM elements. It provides `resq$` for selecting a single matching component and `resq$$` for selecting multiple matches, supporting advanced features like wildcard selector patterns, asynchronous waiting for React to initialize, and filtering results by component state or props. The library is currently stable at version 1.11.0 and requires React v16 or higher. Its primary use cases include automated testing, debugging, and advanced component introspection in client-side React applications. It offers a programmatic interface to the React component tree, allowing developers to access internal component data like props and state through its `RESQNode` return structure.","status":"active","version":"1.11.0","language":"javascript","source_language":"en","source_url":"https://github.com/baruchvlz/resq","tags":["javascript","react","selector","resq","rescue","queryselector","query"],"install":[{"cmd":"npm install resq","lang":"bash","label":"npm"},{"cmd":"yarn add resq","lang":"bash","label":"yarn"},{"cmd":"pnpm add resq","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for accessing and querying the React Virtual DOM.","package":"react","optional":false}],"imports":[{"note":"Used for selecting a single React component or HTML element by its name or tag. The library primarily uses ES module syntax.","wrong":"const resq$ = require('resq').resq$","symbol":"resq$","correct":"import { resq$ } from 'resq'"},{"note":"Used for selecting multiple React components or HTML elements, returning an array of RESQNode objects.","wrong":"const resq$$ = require('resq').resq$$","symbol":"resq$$","correct":"import { resq$$ } from 'resq'"},{"note":"An asynchronous utility function to wait for React to be loaded on the window object, useful for testing or dynamically loaded applications.","wrong":"const waitToLoadReact = require('resq').waitToLoadReact","symbol":"waitToLoadReact","correct":"import { waitToLoadReact } from 'resq'"}],"quickstart":{"code":"import { resq$, waitToLoadReact } from 'resq';\nimport React from 'react';\nimport ReactDOM from 'react-dom';\n\n// A simple React component for demonstration\nconst MyComponent = () => (\n    <div data-testid=\"my-component\">Hello from MyComponent</div>\n);\n\n// Another component\nconst AnotherComponent = () => (\n    <p>Another one</p>\n)\n\n// The main application component\nconst App = () => (\n    <div>\n        <MyComponent />\n        <AnotherComponent />\n    </div>\n);\n\n// Render the application to the DOM\nconst rootElement = document.createElement('div');\nrootElement.id = 'root';\ndocument.body.appendChild(rootElement);\nReactDOM.render(<App />, rootElement);\n\nasync function queryComponents() {\n    try {\n        // Wait for React to load, then query for 'MyComponent'\n        await waitToLoadReact(1000); // Wait up to 1 second\n\n        const myComponentNode = resq$('MyComponent');\n        if (myComponentNode) {\n            console.log('Found MyComponent:', myComponentNode.name, myComponentNode.node.outerHTML);\n            console.log('MyComponent props:', myComponentNode.props);\n        } else {\n            console.log('MyComponent not found after waiting.');\n        }\n\n        // Query for multiple components using a wildcard\n        const allMyComponents = resq$$('My*');\n        console.log('\\nFound all My* components (count:', allMyComponents.length, '):');\n        allMyComponents.forEach(comp => console.log('- ' + comp.name));\n\n    } catch (error) {\n        console.error('An error occurred during resq query:', error);\n    }\n}\n\nqueryComponents();","lang":"typescript","description":"This quickstart demonstrates how to install `resq`, render a basic React application, and then use `resq$` and `resq$$` to select components from the rendered tree, including waiting for React to load."},"warnings":[{"fix":"Always inspect the component tree in React DevTools to confirm the precise name of the component you intend to select, especially for components wrapped by other libraries or HOCs.","message":"Component name resolution can be inconsistent for higher-order components (HOCs), Styled Components, or Material-UI components. The library relies on `displayName` or function/class names, which might be obfuscated or generic. Using React DevTools is recommended to verify the exact component names for selectors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always wrap calls to `await waitToLoadReact()` in a `try...catch` block to gracefully handle scenarios where React might not load or takes longer than expected, preventing application crashes.","message":"The `waitToLoadReact` function can throw an error if React is not found on the `window` object within the specified timeout duration. This can lead to unhandled promise rejections if not explicitly caught.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `resq` is used exclusively in client-side code where `window` and `document` are available. For testing in Node.js, configure a JSDOM environment to simulate a browser.","message":"resq is designed for client-side React applications running in a browser environment, as it interacts directly with the rendered React Virtual DOM and often the browser's `document` object. It is not intended for use in Node.js server-side rendering (SSR) contexts without a JSDOM-like environment.","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":"Ensure your code runs in a browser environment. If running tests in Node.js, configure a JSDOM environment (e.g., using `jest-environment-jsdom`) to provide the necessary global objects.","cause":"Attempting to use `resq` or its utilities in a Node.js environment without a simulated browser DOM.","error":"ReferenceError: document is not defined"},{"fix":"Increase the timeout value passed to `waitToLoadReact(timeoutInMs)` to allow more time for React to load, or ensure React is loaded on the `window` object if it's not a global dependency.","cause":"The `waitToLoadReact` function timed out because the React global object (`window.React`) was not available within the allotted time.","error":"resq error Error: React was not found on the window object after Xms"},{"fix":"Check if `RESQNode.node` is `null` or `undefined` before attempting to access its properties. Components like React fragments or certain HOCs might not have a direct DOM node.","cause":"Attempting to access properties like `node.outerHTML` on a `RESQNode` where `node` is `null`, indicating the component might be a fragment or not associated with a direct DOM element.","error":"TypeError: Cannot read properties of null (reading 'outerHTML')"}],"ecosystem":"npm"}