React Query Builder Component

Common errors

• unknown top level operator: $not

  cause 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')

  cause 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>'

  cause 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()}`.

Warnings

• deprecated 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`.
  Fix: Use `import { createReactDnDAdapter } from '@react-querybuilder/dnd';` and pass `dnd={createReactDnDAdapter()}` to the QueryBuilder component.
• deprecated The `useReactDnD` hook in `@react-querybuilder/dnd` is deprecated.
  Fix: Migrate to `createReactDnDAdapter` for drag-and-drop integration.
• gotcha 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.
  Fix: Install `react-dnd` and `react-dnd-html5-backend` if using drag-and-drop features: `npm install react-dnd react-dnd-html5-backend`.
• breaking 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.
  Fix: Applications consuming MongoDB queries generated by previous versions should update their logic to handle `$nor` for negated rule groups instead of `$not`.
• 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).

Install

• npm install react-querybuilder npm
• yarn add react-querybuilder yarn
• pnpm add react-querybuilder pnpm

Imports

• QueryBuilder
  wrong:

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

  correct:

  import { QueryBuilder } from 'react-querybuilder';

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

  import { RuleGroupType } from 'react-querybuilder';

  correct:

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

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

  import { Field } from 'react-querybuilder';

  correct:

  import type { 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.

Quickstart

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>
  );
};