Registry / web-framework / react-querybuilder

react-querybuilder

library8.15.0jsnpmunverified

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.

web-framework

npm install react-querybuilder

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-QUERYBUILDER

react-querybuilder

web-frameworkjavascriptv8.15.0

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.

QueryBuilder

✓ import { QueryBuilder } from 'react-querybuilder';

✗ const QueryBuilder = require('react-querybuilder').QueryBuilder;

Main component. The package is ESM-first, CJS is supported but ESM imports are preferred.

RuleGroupType

✓ import type { RuleGroupType } from 'react-querybuilder';

✗ import { RuleGroupType } from 'react-querybuilder';

Import as a type only, not a runtime value. TypeScript users should use `import type`.

Field

✓ import type { Field } from 'react-querybuilder';

✗ import { Field } from 'react-querybuilder';

Import as a type only for defining fields. TypeScript users should use `import type`.

createReactDnDAdapter

✓ import { createReactDnDAdapter } from '@react-querybuilder/dnd';

Preferred way to integrate react-dnd, deprecating raw react-dnd exports and `useReactDnD` hook since v8.15.0.

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.

import { useState } from 'react'; import { Field, QueryBuilder, RuleGroupType } from 'react-querybuilder'; import 'react-querybuilder/dist/query-builder.css'; const fields: Field[] = [ { name: 'firstName', label: 'First Name', placeholder: 'e.g. John' }, { name: 'lastName', label: 'Last Name', placeholder: 'e.g. Doe' }, { name: 'age', label: 'Age', inputType: 'number', placeholder: 'e.g. 30' }, { name: 'address', label: 'Address', placeholder: 'e.g. 123 Main St' }, { name: 'phone', label: 'Phone', placeholder: 'e.g. 555-1234' }, { name: 'email', label: 'Email', validator: ({ value }) => /^[^@]+@[^@]+/.test(value), placeholder: 'e.g. user@example.com' }, { name: 'isDev', label: 'Is a Developer?', valueEditorType: 'checkbox', defaultValue: false }, ]; const initialQuery: RuleGroupType = { combinator: 'and', rules: [ { field: 'age', operator: '>', value: '25' }, { field: 'isDev', operator: '=', value: true } ], }; export const App = () => { const [query, setQuery] = useState(initialQuery); return ( <div> <h2>React Query Builder Example</h2> <QueryBuilder fields={fields} defaultQuery={query} onQueryChange={setQuery} showCombineatorsOnLoad={true} /> <div style={{ marginTop: '20px' }}> <h3>Current Query State:</h3> <pre>{JSON.stringify(query, null, 2)}</pre> </div> </div> ); };

Debug

Known issues

deprecatedDirectly 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`.

fix

Use `import { createReactDnDAdapter } from '@react-querybuilder/dnd';` and pass `dnd={createReactDnDAdapter()}` to the QueryBuilder component.

affects: >=8.15.0

deprecatedThe `useReactDnD` hook in `@react-querybuilder/dnd` is deprecated.

fix

Migrate to `createReactDnDAdapter` for drag-and-drop integration.

affects: >=8.15.0

gotchaThe `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.

fix

Install `react-dnd` and `react-dnd-html5-backend` if using drag-and-drop features: `npm install react-dnd react-dnd-html5-backend`.

affects: >=8.15.0

breakingMongoDB 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.

fix

Applications consuming MongoDB queries generated by previous versions should update their logic to handle `$nor` for negated rule groups instead of `$not`.

affects: >=8.14.4

gotcha`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.

fix

No direct fix needed unless custom transformations were explicitly designed to exploit prototype pollution (highly unlikely and discouraged).

affects: >=8.14.2

Errors

Common errors & fixes

unknown top level operator: $not

Using an older version of react-querybuilder or MongoDB driver that doesn't correctly handle `$not` for negated rule groups in MongoDB queries.

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.

TypeError: Cannot read properties of undefined (reading 'Provider')

Missing `react-dnd` or `react-dnd-html5-backend` when using `@react-querybuilder/dnd` package for drag-and-drop functionality.

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`.

Type 'typeof import("react-dnd")' is not assignable to type 'Partial<ReactDnD.DndProviderProps>'

Attempting to pass raw `react-dnd` exports directly to the `dnd` prop of `QueryBuilder` instead of using the adapter.

fix

Use the `createReactDnDAdapter` function from `@react-querybuilder/dnd` to properly wrap `react-dnd` exports. Example: `dnd={createReactDnDAdapter()}`.

Upgrade

Version history

8.15.0latest on npm

Audit

Dependencies

reactrequiredPeer dependency required for rendering the React component.

react-dndoptionalOptional peer dependency for drag-and-drop functionality when using the @react-querybuilder/dnd package.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/react-querybuilder/react-querybuilder ↗

packagehttps://www.npmjs.com/package/react-querybuilder ↗

homepagehttps://react-querybuilder.js.org/ ↗