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.

Documentation

Complete documentation is available at https://react-querybuilder.js.org.

Demo

Click here to see a live, interactive demo.

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

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

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} query={query} onQueryChange={setQuery} />;
};

To enable drag-and-drop, install the @react-querybuilder/dnd package and nest <QueryBuilder /> under <QueryBuilderDnD />.

Export

To export queries as SQL, MongoDB, or one of several other formats, use the formatQuery function.

const query = {
  combinator: 'and',
  rules: [
    {
      field: 'first_name',
      operator: 'beginsWith',
      value: 'Stev',
    },
    {
      field: 'last_name',
      operator: 'in',
      value: 'Vai, Vaughan',
    },
  ],
};
const sqlWhere = formatQuery(query, 'sql');
console.log(sqlWhere);
// `(first_name like 'Stev%' and last_name in ('Vai', 'Vaughan'))`

Import

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

Tip: parseSQL will accept a full SELECT statement or the WHERE clause by itself (everything but the expressions in the WHERE clause will be ignored). Trailing semicolon is optional.

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 { 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

[v7.2.1] - 2024-05-06

Fixed

• [#682] parseCEL processes "like" operators ("contains"/"startsWith"/"endsWith") that are negated without parentheses, like !f1.contains(f2).
• [#692] formatQuery updates (these are probably technically breaking changes, but the logic itself is equivalent to the previous version so we're considering them bug fixes):
  • For the "jsonlogic" export format, the entire group structure is retained even if only one top-level child object exists.
  • For the "jsonlogic", "mongodb", and "cel" formats, rules where the operator is "in" or "notIn" and the value evaluates to an empty array are retained.
  • The "jsonata" format now respects the quoteFieldNamesWith option.
• [#692] Custom field selectors can set their rule's field property to an arbitrary value without throwing an error, even if the value is not included in the fields prop list.