react-querybuilder

react-querybuilder

The Query Builder component for React

React Query Builder is a fully customizable query builder component for React, along with a collection of utility functions for importing from, and exporting to, various query languages like SQL, MongoDB, and more.

• Demo
• Full documentation
• CodeSandbox / StackBlitz example projects

Basic usage

npm i react-querybuilder
# OR yarn add / pnpm add / bun add

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' },
  { name: 'lastName', label: 'Last Name' },
  { name: 'age', label: 'Age', inputType: 'number' },
  { name: 'address', label: 'Address' },
  { name: 'phone', label: 'Phone' },
  { name: 'email', label: 'Email', validator: ({ value }) => /^[^@]+@[^@]+/.test(value) },
  { name: 'twitter', label: 'Twitter' },
  { name: 'isDev', label: 'Is a Developer?', valueEditorType: 'checkbox', defaultValue: false },
];

const initialQuery: RuleGroupType = {
  combinator: 'and',
  rules: [],
};

export const App = () => {
  const [query, setQuery] = useState(initialQuery);

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

Customizations are not limited to the following libraries, but these have first-class support through their respective compatibility packages:

Library	Compatibility package	Demo	Example projects
Ant Design	@react-querybuilder/antd	demo	CodeSandbox · StackBlitz
Bootstrap	@react-querybuilder/bootstrap	demo	CodeSandbox · StackBlitz
Bulma	@react-querybuilder/bulma	demo	CodeSandbox · StackBlitz
Chakra UI	@react-querybuilder/chakra	demo	CodeSandbox · StackBlitz
Fluent UI	@react-querybuilder/fluent	demo	CodeSandbox · StackBlitz
Mantine	@react-querybuilder/mantine	demo	CodeSandbox · StackBlitz
MUI	@react-querybuilder/material	demo	CodeSandbox · StackBlitz
React Native	@react-querybuilder/native		CodeSandbox · StackBlitz
Tremor	@react-querybuilder/tremor	demo	CodeSandbox · StackBlitz

[!TIP]

To enable drag-and-drop, use @react-querybuilder/dnd.

For enhanced date/time support, use @react-querybuilder/datetime.

Export

To export queries as a SQL WHERE clause, MongoDB query object, or one of several other formats, use formatQuery.

const query = {
  combinator: 'and',
  rules: [
    {
      field: 'first_name',
      operator: 'beginsWith',
      value: 'Stev',
    },
    {
      field: 'last_name',
      operator: 'in',
      value: 'Vai, Vaughan',
    },
  ],
};

formatQuery(query, 'sql');
/*
"(first_name like 'Stev%' and last_name in ('Vai', 'Vaughan'))"
*/

Import

To import queries use parseSQL, parseMongoDB, parseJsonLogic, parseJSONata, parseCEL, or parseSpEL depending on the source.

// Tip: `parseSQL` will accept either a full `SELECT` statement or a `WHERE` clause by itself.
// Everything but the `WHERE` expressions will be ignored.

const query = parseSQL(
  `SELECT * FROM my_table WHERE first_name LIKE 'Stev%' AND last_name in ('Vai', 'Vaughan')`
);

console.log(query);
/*
{
  "combinator": "and",
  "rules": [
    {
      "field": "first_name",
      "operator": "beginsWith",
      "value": "Stev",
    },
    {
      "field": "last_name",
      "operator": "in",
      "value": "Vai, Vaughan",
    },
  ],
}
*/

Utilities

formatQuery, transformQuery, and the parse* functions can be used without importing from react (on the server, for example) like this:

import { formatQuery } from 'react-querybuilder/formatQuery';
import { parseCEL } from 'react-querybuilder/parseCEL';
import { parseJSONata } from 'react-querybuilder/parseJSONata';
import { parseJsonLogic } from 'react-querybuilder/parseJsonLogic';
import { parseMongoDB } from 'react-querybuilder/parseMongoDB';
import { parseSpEL } from 'react-querybuilder/parseSpEL';
import { parseSQL } from 'react-querybuilder/parseSQL';
import { transformQuery } from 'react-querybuilder/transformQuery';

(As of version 7, the parse* functions are only available through these extended exports.)

Changelog

[v8.8.0] - 2025-07-09

Added

• [#900] Support for matching elements of a nested array.
  • New optional RuleType property match?: { mode: MatchMode, threshold?: number }
    • type MatchMode = 'all' | 'some' | 'none' | 'atLeast' | 'atMost' | 'exactly'
    • In most contexts, a rule's operator will be ignored when match is present and valid.
  • New component MatchModeEditor, which renders when a field is determined to have one or more match modes. The mode selector is the configured valueSelector and—when a threshold is appropriate—the threshold editor is the configured valueEditor with inputType: "number".
  • New props getMatchModes and getSubQueryBuilderProps to manage these configurations at the top level.
  • New Field properties matchModes and subproperties to manage these configurations at the field level.
  • parseJsonLogic support for "all", "none", and "some" operations.
  • formatQuery (partial) support for the match rule property.
    • Supported formats include "sql", "parameterized", "drizzle", "natural_language", "mongodb_query", "jsonlogic", "jsonata", "spel", and "cel".
    • To avoid invalid syntax, the SQL-based formats only work with preset: "postgresql", and only with nested arrays of primitives like strings or numbers.
• [#903] New parser option bigIntOnOverflow. When true, a bigint will be generated for parsed tokens that represent valid integers outside the safe boundaries of the number type. (This currently only applies to parseSQL.)
• [#911] Support for inputType: "bigint" in all value editors, which will render an input with type="text" but will store the value as a bigint if a valid integer is entered.
• [#900] Extracted fields prop processing logic to new useFields hook.
• [#900] "Justified layout" styles from the demo (to push the "+ Rule", "+ Group", clone, lock, and remove buttons to the right edge) are now included in the default stylesheet. To apply the styles, add the queryBuilder-justified class to the query builder using the controlClassnames prop, or to any ancestor element.
• [#900] All components that render <label> elements now have htmlFor attributes linking their corresponding <input> elements using an id generated with useId().
• [#900] The getValueSources prop and the Field#valueSources property can now evaluate to a full option list instead of a simple array of value source strings. This enables translations of the value sources through the label property.
• [#914] Option list props (including fields, operators, combinators, getOperators, and getValues) can now include strings in addition to—or instead of—Option objects (e.g. ["=", "between"]). The string itself will be used as both the identifier and label, except in the case of operators and combinators where the default labels will be used if the string matches a value from the default set.

Fixed

• [#903] parseSQL maintains precision for large integers by generating a bigint instead of a number when necessary.
• [#900] Preact compatibility improved by using React.Fragment explicitly instead of the shorthand <>...</>.
• [#900] If the preset option for formatQuery is one from sqlDialectPresets, it will only apply if the format is undefined or one of the SQL-based formats.