Skip to main content
Version: Next

Getting started

TL;DR​

Installation​

Install react-querybuilder using npm, Yarn, pnpm, or Bun, or follow buildless setup instructions.

npm i react-querybuilder

Basics​

Create a basic query builder by rendering QueryBuilder with no props. Import the official stylesheet (available in .css and .scss formats).

This query builder works but isn't very useful yet. To get real value from it, you need to define fields for users to select from. Pass an array of field objects to the fields prop.

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

Much better! However, you'll likely want to monitor and control user interactions with the query builder. Let's add state management using React's useState hook to store the query object and make it accessible to other components.

The query state variable gets passed to the query prop, and the setQuery setter function handles the onQueryChange callback. We'll also initialize the query with some example rules, ensuring each rule's field property matches a field name from our fields array.

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

Exporting queries​

Use the formatQuery function to convert query objects to formats like SQL, MongoDB, and CEL (full documentation). The example below shows real-time SQL generation—modify the query and watch the SQL update automatically.

Onward and upward!​

Explore all React Query Builder options in the main component documentation. Try different configurations, export/import formats, and features in the interactive demo.

Coming from another library? See how React Query Builder compares, and the guide for migrating from react-awesome-query-builder.

Using with AI agents​

React Query Builder publishes an agent skill that teaches coding agents to use the library correctly:

npx skills add react-querybuilder/react-querybuilder --skill react-querybuilder

See Using with AI agents for manual skill installation, MCP server configuration, LLM-friendly docs (/llms.txt, /llms-full.txt, /llms-api.txt), and generated recipes.

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, taught by this library's maintainer at newline.