react-awesome-query-builder

React Awesome Query Builder is a React component that lets end users build complex, nested filter conditions through a visual, drag-and-drop interface rather than hand-writing query syntax. Fields can be simple (string, number, boolean, date/time, list) or complex (structs, arrays), operators range from basic comparisons to ‘between’ and proximity matching, and both sides of a rule can reference functions or other fields, with nested function arguments supported.

The built query tree can be exported to SQL WHERE clauses, MongoDB queries, JsonLogic, SpEL, or Elasticsearch, and imported back from JsonLogic, SpEL, or SQL, making it a common choice for building admin dashboards, report filters, and rule engines where the underlying query must be persisted and later replayed on a backend. A ternary (if-then-else) mode extends the same tree model to conditional logic beyond simple filtering.

Since v6 the project is split into scoped packages under @react-awesome-query-builder/*: core for framework-agnostic tree/import/export logic usable in Node.js, ui for the base React components and vanilla widgets, and theme packages (antd, mui, bootstrap, fluent) that layer widgets from popular UI kits on top. The react-awesome-query-builder name on npm corresponds to the original, now-legacy unscoped package that predates this split; the actively maintained code lives in the monorepo’s scoped packages, which the README directs new consumers toward.

The library is MIT licensed with no restricted or paid tiers - every export format, widget theme, and API surface is available to any consumer, self-hosted or otherwise.

What You Get

• A <Query>/<Builder> React component pair that renders a nested rule/group tree the end user edits interactively
• Framework-agnostic core (@react-awesome-query-builder/core) that can run in Node.js for server-side validation or query translation
• Theme packages providing ready-made widgets for Ant Design, MUI, Bootstrap, and Fluent UI, plus a vanilla fallback
• Export utilities to SQL WHERE clauses, MongoDB queries, JsonLogic, SpEL, Elasticsearch, or a custom format
• Import utilities to load a tree back from JsonLogic, SpEL, or SQL
• Support for field-to-field comparisons, aggregation-style queries, and unary/binary/proximity operators
• Drag-and-drop reordering of rules and groups within the builder
• Full TypeScript typings and a ternary (if-then-else) mode alongside the standard filter mode

Common Use Cases

• Admin dashboards where non-technical users build ad-hoc report or list filters without writing SQL
• Rule engines where business rules are authored visually and evaluated via JsonLogic or a custom export format
• Search/filter UIs backed by Elasticsearch or MongoDB where the query tree maps directly to the datastore’s native syntax
• SaaS products exposing a ‘segment builder’ or ‘audience builder’ for filtering users/records by attribute
• Internal tools that need to persist a structured filter to a database and reload it later for re-editing

Under The Hood

Architecture The project is a pnpm/lerna monorepo (packages/core, ui, and per-theme packages antd/mui/material/bootstrap/fluent, plus sql and tests) with a strict dependency direction: core has no React dependency and holds the immutable query tree (modules/stores/tree.js), config/constants, and the import/export modules (modules/export/{sql,mongoDb,jsonLogic,spel,elasticSearch,queryString}.js, modules/import/{tree,jsonLogic,spel}.js); ui re-exports core and adds the React component layer (modules/components/{containers,rule,item,operators,widgets}) plus hooks and vanilla widgets; each theme package re-exports ui and swaps in its own widget set. This lets the same core tree logic run in Node.js for server-side query translation while the UI layer stays a thin, swappable presentation shell — changing the underlying tree/query-string abstraction in core would ripple through every downstream theme package, but swapping a theme package touches only its own widget layer.

Tech Stack Built on React with TypeScript (strict mode enabled per tsconfig.json, though strictNullChecks is relaxed), transpiled via Babel for both CJS and ESM output per package, using Immutable.js-style tree structures for the query state. Theme packages depend on their respective UI kits (Ant Design, MUI, Material-UI v4, Reactstrap/Bootstrap, Fluent UI) as peer dependencies rather than bundling them. Demo/sandbox apps use Vite and Next.js; the workspace is managed with pnpm workspaces and lerna, with a dedicated sql package built on a SQL parser for round-tripping WHERE clauses.

Code Quality The packages/tests package runs an extensive Karma/webpack browser test suite (30+ spec files covering widgets, interactions, drag-and-drop, JsonLogic, SpEL, validation, and XSS handling per UI theme), with both .test.js and typed .test.ts specs. ESLint is configured per-package and run in CI (smoke.yml GitHub Actions workflow chains lint, test, and build across the whole workspace), and TypeScript strict mode catches a meaningful class of type errors even without full null-strictness. Naming and module boundaries are consistent across theme packages, which mirror the same internal structure.

What Makes It Unique Unlike most React form/filter builders that only render UI, this library treats the query tree as a portable intermediate representation with bidirectional translation to and from multiple external query languages (SQL, MongoDB, JsonLogic, SpEL, Elasticsearch) plus field-to-field comparison, nested function arguments on either side of a rule, and a ternary if-then-else mode layered on the same tree model — giving it reach into both frontend filter UIs and backend rule-engine scenarios from a single config-driven schema.