Getting started

TL;DR

• Basic example (TypeScript)
• Basic example (JavaScript)
• More examples

Installation

To install react-querybuilder, use a package manager like npm, Yarn, pnpm, or Bun.

npm

npm i react-querybuilder

Bun

bun add react-querybuilder

Yarn

yarn add react-querybuilder

pnpm

pnpm add react-querybuilder

Basics

The simplest way to create a query builder is to render the QueryBuilder component with no props. (Be sure to import the official stylesheet, which is available in .css and .scss flavors.)

import { QueryBuilder } from 'react-querybuilder';
import 'react-querybuilder/dist/query-builder.css';

export default () => <QueryBuilder />;

Open Sandbox

Functional, but not very useful. To really get value out of the query builder, we'll first need to define a set of fields for the user to choose from. We can pass the fields array into the query builder through the fields prop.

In the query builder below, click the "+Rule" button and then the field selector to see the field choices.

import { QueryBuilder } from 'react-querybuilder';
import 'react-querybuilder/dist/query-builder.css';

const fields: Field[] = [
  { name: 'firstName', label: 'First Name' },
  { name: 'lastName', label: 'Last Name' },
];

export default () => <QueryBuilder fields={fields} />;

Open Sandbox

Much more useful, but you probably want to monitor and control what users do with the query builder. Let's set up a state variable using the React Hook useState. This will store our query object and allow us to pass it on to other components, event handlers, etc.

The state variable query will be passed to the query prop, and the setter method setQuery will be used in the onQueryChange callback. Let's also seed the query object with a couple of rules, making sure that the field property of each rule matches the name property of one of our fields.

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' },
];

export default () => {
  const [query, setQuery] = useState<RuleGroupType>({
    combinator: 'and',
    rules: [
      { field: 'firstName', operator: '=', value: 'Steve' },
      { field: 'lastName', operator: '=', value: 'Vai' },
    ],
  });

  return <QueryBuilder fields={fields} query={query} onQueryChange={q => setQuery(q)} />;
};

Open Sandbox

Non-TypeScript version

import { useState } from 'react';
import { QueryBuilder } from 'react-querybuilder';
import 'react-querybuilder/dist/query-builder.css';

const fields = [
  { name: 'firstName', label: 'First Name' },
  { name: 'lastName', label: 'Last Name' },
];

export default () => {
  const [query, setQuery] = useState({
    combinator: 'and',
    rules: [
      { field: 'firstName', operator: '=', value: 'Steve' },
      { field: 'lastName', operator: '=', value: 'Vai' },
    ],
  });

  return <QueryBuilder fields={fields} query={query} onQueryChange={q => setQuery(q)} />;
};

tip

This documentation primarily demonstrates use of the ESM and CommonJS builds of react-querybuilder, but a UMD build is also available.

Exporting queries

To convert a query object into other formats like SQL, MongoDB, and CEL, you can use the formatQuery function (full documentation here). The example below demonstrates the conversion of a query to its equivalent SQL form. Modify the query by manipulating the form elements and the SQL will update accordingly.

import { useState } from 'react';
import { Field, formatQuery, 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' },
];

export default () => {
  const [query, setQuery] = useState<RuleGroupType>({
    combinator: 'and',
    rules: [
      { field: 'firstName', operator: 'beginsWith', value: 'Stev' },
      { field: 'lastName', operator: 'in', value: 'Vai,Vaughan' },
    ],
  });

  return (
    <>
      <QueryBuilder fields={fields} query={query} onQueryChange={q => setQuery(q)} />
      <h4>
        SQL as result of <code>formatQuery(query, 'sql')</code>:
      </h4>
      <pre>{formatQuery(query, 'sql')}</pre>
    </>
  );
};

Open Sandbox

Onward and upward!

To discover all the options of React Query Builder, check out the API documentation. To play around with various configurations, including other export formats and importing from SQL, check out the demo.

Training

For an extended tutorial on configuration and customization of react-querybuilder, including information about integrating it with a backend API and advanced reporting components (grids, maps, charts, etc.), check out the course Building Advanced Admin Reporting in React, which is taught by one of this library's maintainers, over at newline.