# React Query Builder: a rule editor for React that exports to SQL and MongoDB

> React Query Builder renders a nested and/or rule tree in React and ships import/export utilities for SQL, MongoDB and other query languages. It is for teams that need a structured filter UI they can style themselves, not a complete query console.

**react-querybuilder/react-querybuilder** — Project brief: The Query Builder component for React. [!TIP] To enable drag-and-drop, use @react-querybuilder/dnd.

- Repository: https://github.com/react-querybuilder/react-querybuilder
- Website: https://react-querybuilder.js.org/
- Stars: 1,738 · Forks: 309
- Language: TypeScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/react-querybuilder-react-querybuilder

## The problem React Query Builder solves, and who ends up using it

Any admin interface that filters a list eventually outgrows a row of dropdowns. Users want to express things like "status is active AND (plan is pro OR seats greater than 20)", and they want to see that structure while they edit it. Hand-rolling that tree means writing recursion for groups, a combinator per group, per-field operator lists, value editors that change with the field type, and a serialization format that survives a round trip to your API. React Query Builder is the component that already does that part.

The audience is narrower than "anyone who needs a filter UI". It fits a React application that already has its own design system and wants the rule editor to look like the rest of the app. The README describes the main component as "fully customizable", and the repository backs that up with compatibility packages for Ant Design, Bootstrap, Bulma, Chakra UI, Fluent UI, Mantine, MUI, PrimeReact and Tremor, plus a React Native component. If your stack is one of those, you are the intended user. If you want a hosted query console with schema browsing and saved queries, this is a building block, not the product.

One detail worth noting early: the query object is plain data. The README's starter example initializes it as an object with a combinator and a rules array, and the component reports changes back through a callback. That means the same structure can be persisted, diffed, validated or sent to a server without any adapter layer.

## How the rule tree, the query object and formatQuery fit together

The mechanism is a controlled component over a recursive data structure. A query is an object with a combinator and a rules array; each entry in rules is either a rule (field, operator, value) or another group with its own combinator and rules. Nesting groups inside groups is what produces the parenthesised logic. The component renders that tree and calls back with a new tree whenever the user changes something, so the state lives in your application, not inside the library.

The second half of the library is the import/export layer. The README describes "a collection of utility functions for importing from, and exporting to, various query languages like SQL, MongoDB, and more", documented under the utils/import and utils/export paths on the documentation site. The export side is what most teams reach for first: you keep the query as the plain object, then convert it to the dialect your backend speaks at the moment you submit. Because the conversion is a separate function rather than part of the component, you can also run it server-side or in a test without rendering anything.

The repository is a monorepo. The root package.json declares workspaces for packages/* and website, and the optional capabilities are separate packages: @react-querybuilder/dnd for drag-and-drop, @react-querybuilder/datetime for enhanced date and time support, @react-querybuilder/expr for expressions inside rules, and @react-querybuilder/rules-engine for if-then-else behaviour. That split is deliberate and it has a cost: each one is an additional dependency and an additional version to keep aligned with the core.

## Installing React Query Builder and rendering a first query

The README's getting-started section shows the minimal path: import the component and the default stylesheet, then render it. The stylesheet is available as CSS or SCSS, and the import path is react-querybuilder/dist/query-builder.css. The example below is the README version, with a state hook added so the query object is visible.

```jsx
import { QueryBuilder } from 'react-querybuilder';
import 'react-querybuilder/dist/query-builder.css'; // or .scss

export function App() {
  const [query, setQuery] = useState({
    combinator: 'and',
    rules: [],
  });

  return <QueryBuilder defaultQuery={query} onQueryChange={setQuery} />;
}
```

What you should see after this renders is an empty rule group with a combinator control and an add-rule affordance. It will not yet know what fields exist, because the README's starter example does not pass a field list. Field definitions are what drive the operator and value editor choices, and they are documented on the documentation site rather than in the README, so plan to read the full docs before the component becomes useful.

If your project uses one of the supported UI libraries, the compatibility packages are the reason to install a second dependency. The names follow the pattern @react-querybuilder/antd, @react-querybuilder/bootstrap, @react-querybuilder/bulma, @react-querybuilder/chakra, @react-querybuilder/fluent, @react-querybuilder/mantine, @react-querybuilder/material, @react-querybuilder/prime and @react-querybuilder/tremor. The repository also carries a native package for React Native. Choosing one of these means the controls come from your existing component library instead of the default markup.

For local development against the monorepo itself, the root package.json defines a start script that runs bun --hot ./utils/devapp/server.ts, plus per-package scripts such as start:rqb, start:antd and start:dnd. Those are repository scripts, not something you need in a consuming application.

## Where React Query Builder is the wrong tool

The first limitation is that the component is not the query. React Query Builder produces a structure and, through the export utilities, a string in a target language. It does not parse an existing SQL statement back into a rule tree, and the README does not present it as a SQL parser. If your users need to paste a query they already have and edit it visually, the round trip you need is import, and the documentation's import utilities are the place to check exactly which formats are supported before you promise that feature.

The second is the styling contract. The README tells you to import react-querybuilder/dist/query-builder.css, and the compatibility packages exist precisely because the default markup does not match every design system. If your team has a strict component library that is not in the supported list, you are choosing between restyling the default output and writing your own controls. That is real work, and it is the kind of work that looks small in a spike and large in a design review.

The third is scope creep in the other direction. The optional features are separate packages, which keeps the core small but means drag-and-drop, expressions and if-then-else are not there when you install the main package. A team that assumes the component ships with everything will discover the gap after the first demo.

Finally, there is no backend. Nothing in the README describes a server component, an API or a database connection. The exported query is a string or an object that you are responsible for parameterising and executing safely. If you were hoping the library would also run the query, it will not.

## React Query Builder compared with React Awesome Query Builder and Syncfusion

The README itself credits React Awesome Query Builder as prior work that inspired this component, and the repository ships a migration guide from it at docs/tips/migrate-from-raqb. That guide is the honest starting point for a comparison, because the two projects solve the same problem with different packaging. React Awesome Query Builder is a single, configuration-heavy widget: you describe fields, widgets and operators in one config object, and the library renders a complete UI from it. React Query Builder splits that responsibility. The core renders a rule tree, and the import/export utilities handle conversion, with compatibility packages supplying the visual layer for a specific design system. If your team already owns its form controls and wants the rule editor to inherit them, the split is an advantage. If you want one config object to produce a finished UI, the single-widget approach is closer to what you are asking for.

Syncfusion's Query Builder is a different proposition again: it is a commercial component library with its own licensing and support terms, spread across multiple frameworks rather than React only. The practical difference is not the rule tree, which both render, but what comes with it. A commercial vendor bundles support and a release cadence under contract; React Query Builder is MIT licensed and maintained in the open, with the last push on 2026-08-19. Which of those matters more depends on whether your organisation needs a support agreement attached to the dependency.

The related searches also surface react querybuilder shadcn, which points at a gap rather than an alternative: shadcn/ui is a copy-into-your-repo component collection, and the repository's compatibility package list does not include one for it. Teams on that stack should expect to style the default output or wrap the controls themselves.

## Maintenance, licensing and the upgrade cost you should budget for

React Query Builder is MIT licensed, and the LICENSE.md file sits at the repository root. MIT is permissive: it allows commercial use and modification, and it comes without warranty. That last part is the one to read carefully if you are embedding the component in a product you sell, because it means the maintainers carry no obligation if the component misbehaves. This is a description of the licence text, not legal advice; your own counsel decides what your product needs.

The repository is not archived, and its last push was on 2026-08-19. The recent release history shows a steady patch cadence: v8.23.1 on 2026-08-19, v8.23.0 on 2026-08-14 and v8.22.5 on 2026-08-11. Frequent patch releases are good for fixes and awkward for pinning, because a caret range on the core package will move you through them. The repository keeps a CHANGELOG.md at the root, which is where to look before any bump.

The upgrade cost is dominated by the monorepo split. Core, the compatibility package for your UI library, and any of dnd, datetime, expr or rules-engine you have adopted all move independently, and a version mismatch between them is the failure mode to watch. The README points to a version migration guide at docs/migrate for earlier versions, which is the document to read when a major release lands rather than a patch. There is also a migration path documented for teams coming from react-awesome-query-builder.

## Conclusion

Adopt React Query Builder when you need a nested and/or rule editor inside an existing React design system and you are willing to write the field definitions yourself. Do not adopt it if you expect a finished query console with schema discovery, saved queries and result tables; the README describes a component plus import/export utilities, and the optional behaviour (drag-and-drop, date/time, expressions, if-then-else) lives in separate packages you must add. Before committing, verify three things against your own build: that the default stylesheet import path resolves in your bundler, that the formatQuery output for your target dialect matches what your backend actually accepts, and that the compatibility package for your UI library is published at the version you need. The repository's last push was on 2026-08-19, so check the CHANGELOG for the current release before you pin a version.

## FAQ

### What is React Query Builder?

It is a customizable query builder component for React, distributed as the react-querybuilder package, together with utility functions for importing from and exporting to query languages such as SQL and MongoDB. The repository also hosts compatibility packages for several UI libraries and a React Native component.

### What are the alternatives to React Query Builder?

The README credits jQuery QueryBuilder, Angular QueryBuilder and React Awesome Query Builder as prior work that inspired this component, and the repository includes a migration guide from React Awesome Query Builder at docs/tips/migrate-from-raqb. Syncfusion's Query Builder is another option that appears in related searches and is a commercial component rather than an MIT-licensed one.

### What does a query builder do?

In this project it renders a nested and/or rule tree in React and reports changes back through a callback, so the application holds the query as plain data. Utility functions then import from and export to query languages such as SQL and MongoDB.

## Sources

- [Official documentation](https://react-querybuilder.js.org/)
- [Official README](https://github.com/react-querybuilder/react-querybuilder#readme)
- [Project repository](https://github.com/react-querybuilder/react-querybuilder)
- [Release notes](https://github.com/react-querybuilder/react-querybuilder/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/react-querybuilder-react-querybuilder