{"id":17341,"library":"react-querybuilder","title":"React Query Builder Component","description":"React Query Builder is a highly customizable React component designed for constructing complex queries and filters dynamically. It currently maintains a stable version of 8.15.0, with a release cadence that includes frequent patch releases for bug fixes and security updates, alongside regular minor version updates introducing new features and compatibility improvements. Key differentiators include its extensive customization options, first-class support for integration with popular UI libraries like Ant Design, Bootstrap, Chakra UI, and Fluent UI via dedicated compatibility packages, and a comprehensive suite of utility functions for importing and exporting queries to various formats, including SQL, MongoDB, and JSON. The library focuses on providing a flexible and robust solution for building rule-based query interfaces in React applications.","status":"active","version":"8.15.0","language":"javascript","source_language":"en","source_url":"https://github.com/react-querybuilder/react-querybuilder","tags":["javascript","react","querybuilder","query","builder","operators","component","clause","expression","typescript"],"install":[{"cmd":"npm install react-querybuilder","lang":"bash","label":"npm"},{"cmd":"yarn add react-querybuilder","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-querybuilder","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for rendering the React component.","package":"react","optional":false},{"reason":"Optional peer dependency for drag-and-drop functionality when using the @react-querybuilder/dnd package.","package":"react-dnd","optional":true}],"imports":[{"note":"Main component. The package is ESM-first, CJS is supported but ESM imports are preferred.","wrong":"const QueryBuilder = require('react-querybuilder').QueryBuilder;","symbol":"QueryBuilder","correct":"import { QueryBuilder } from 'react-querybuilder';"},{"note":"Import as a type only, not a runtime value. TypeScript users should use `import type`.","wrong":"import { RuleGroupType } from 'react-querybuilder';","symbol":"RuleGroupType","correct":"import type { RuleGroupType } from 'react-querybuilder';"},{"note":"Import as a type only for defining fields. TypeScript users should use `import type`.","wrong":"import { Field } from 'react-querybuilder';","symbol":"Field","correct":"import type { Field } from 'react-querybuilder';"},{"note":"Preferred way to integrate react-dnd, deprecating raw react-dnd exports and `useReactDnD` hook since v8.15.0.","symbol":"createReactDnDAdapter","correct":"import { createReactDnDAdapter } from '@react-querybuilder/dnd';"}],"quickstart":{"code":"import { useState } from 'react';\nimport { Field, QueryBuilder, RuleGroupType } from 'react-querybuilder';\nimport 'react-querybuilder/dist/query-builder.css';\n\nconst fields: Field[] = [\n  { name: 'firstName', label: 'First Name', placeholder: 'e.g. John' },\n  { name: 'lastName', label: 'Last Name', placeholder: 'e.g. Doe' },\n  { name: 'age', label: 'Age', inputType: 'number', placeholder: 'e.g. 30' },\n  { name: 'address', label: 'Address', placeholder: 'e.g. 123 Main St' },\n  { name: 'phone', label: 'Phone', placeholder: 'e.g. 555-1234' },\n  { name: 'email', label: 'Email', validator: ({ value }) => /^[^@]+@[^@]+/.test(value), placeholder: 'e.g. user@example.com' },\n  { name: 'isDev', label: 'Is a Developer?', valueEditorType: 'checkbox', defaultValue: false },\n];\n\nconst initialQuery: RuleGroupType = {\n  combinator: 'and',\n  rules: [\n    { field: 'age', operator: '>', value: '25' },\n    { field: 'isDev', operator: '=', value: true }\n  ],\n};\n\nexport const App = () => {\n  const [query, setQuery] = useState(initialQuery);\n\n  return (\n    <div>\n      <h2>React Query Builder Example</h2>\n      <QueryBuilder\n        fields={fields}\n        defaultQuery={query}\n        onQueryChange={setQuery}\n        showCombineatorsOnLoad={true}\n      />\n      <div style={{ marginTop: '20px' }}>\n        <h3>Current Query State:</h3>\n        <pre>{JSON.stringify(query, null, 2)}</pre>\n      </div>\n    </div>\n  );\n};\n","lang":"typescript","description":"This example demonstrates how to set up a basic QueryBuilder component with predefined fields, an initial query, and state management using React hooks. It also shows the generated query structure."},"warnings":[{"fix":"Use `import { createReactDnDAdapter } from '@react-querybuilder/dnd';` and pass `dnd={createReactDnDAdapter()}` to the QueryBuilder component.","message":"Directly passing raw `react-dnd` exports as the `dnd` prop is deprecated. Although it still works and is auto-detected, the preferred method is to use `createReactDnDAdapter`.","severity":"deprecated","affected_versions":">=8.15.0"},{"fix":"Migrate to `createReactDnDAdapter` for drag-and-drop integration.","message":"The `useReactDnD` hook in `@react-querybuilder/dnd` is deprecated.","severity":"deprecated","affected_versions":">=8.15.0"},{"fix":"Install `react-dnd` and `react-dnd-html5-backend` if using drag-and-drop features: `npm install react-dnd react-dnd-html5-backend`.","message":"The `react-dnd` package is now an *optional* peer dependency for `@react-querybuilder/dnd`. If you use the `dnd` package, ensure `react-dnd` is installed in your project.","severity":"gotcha","affected_versions":">=8.15.0"},{"fix":"Applications consuming MongoDB queries generated by previous versions should update their logic to handle `$nor` for negated rule groups instead of `$not`.","message":"MongoDB export formats (`\"mongodb_query\"`/`\"mongodb\"`) for rule group negation now use `$nor` instead of `$not`. This fixes a runtime error but changes the generated query structure for negated groups.","severity":"breaking","affected_versions":">=8.14.4"},{"fix":"No direct fix needed unless custom transformations were explicitly designed to exploit prototype pollution (highly unlikely and discouraged).","message":"`transformQuery` and `merge[Any]Translation[s]` now include guards against prototype pollution. While this is a security fix, it might subtly change behavior if an application was inadvertently relying on or being affected by such vulnerabilities.","severity":"gotcha","affected_versions":">=8.14.2"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Upgrade `react-querybuilder` to version 8.14.4 or higher. The library now correctly uses `$nor` for rule group negation in MongoDB export formats.","cause":"Using an older version of react-querybuilder or MongoDB driver that doesn't correctly handle `$not` for negated rule groups in MongoDB queries.","error":"unknown top level operator: $not"},{"fix":"Ensure `react-dnd` and its necessary backend (e.g., `react-dnd-html5-backend`) are installed as `react-dnd` became an optional peer dependency in `v8.15.0` for `@react-querybuilder/dnd`.","cause":"Missing `react-dnd` or `react-dnd-html5-backend` when using `@react-querybuilder/dnd` package for drag-and-drop functionality.","error":"TypeError: Cannot read properties of undefined (reading 'Provider')"},{"fix":"Use the `createReactDnDAdapter` function from `@react-querybuilder/dnd` to properly wrap `react-dnd` exports. Example: `dnd={createReactDnDAdapter()}`.","cause":"Attempting to pass raw `react-dnd` exports directly to the `dnd` prop of `QueryBuilder` instead of using the adapter.","error":"Type 'typeof import(\"react-dnd\")' is not assignable to type 'Partial<ReactDnD.DndProviderProps>'"}],"ecosystem":"npm","meta_description":null}