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.0] - 2024-04-15

Added

• [#677] JSONata export format.

Fixed

• [#677] A bug in the default SpEL and CEL rule processors for formatQuery caused rules to be ignored when the operator was "between" or "notBetween" and one of the values was falsey without being null or undefined (e.g, 0 or "").