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.

!Screenshot

- Demo
- Full documentation
- CodeSandbox / StackBlitz example projects

Basic usage

``bash
npm i react-querybuilder


OR yarn add / pnpm add / bun add


`

`tsx
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 ;
};
`

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.
>
> For rules engine functionality (if-then-else) use @react-querybuilder/rules-engine.

Export

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

`ts
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.

`ts
// 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:

`js
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.)