react-query-builder component in a React app

LibraryBeta

LibraryBetaTypeScriptv0.8.0

2.1K downloads

89 stars

Last updated: May 1, 2025

react-query-builder

“Visual query builder component for React — zero dependencies”

A headless React component library for building visual query interfaces. Drop it into any React app to let users construct complex filter queries with AND/OR groups, field pickers, and operator selectors. Works with any data source.

#React#TypeScript#UI Components

Source Code Package Docs

Installation

Requirements

Reactv18+

React 18 or newer

TypeScriptv5+Optional

Optional but strongly recommended

npm install

Install from npm

npm install react-query-builder

Quick Start

Add a query builder to your React app in 2 steps

~3 min

Install the package

Install from npm

terminal

npm install react-query-builder
# or
yarn add react-query-builder

💡 Tips

•Requires React 18+
•TypeScript is supported out of the box

Render the QueryBuilder

Pass your fields config and listen for onChange

FilterPanel.tsx

import { QueryBuilder } from 'react-query-builder';

const fields = [
  { name: 'name', label: 'Name', type: 'text' },
  { name: 'age', label: 'Age', type: 'number' },
  { name: 'status', label: 'Status', type: 'select',
    options: ['active', 'inactive', 'pending'] },
];

export function FilterPanel() {
  const [query, setQuery] = useState({ combinator: 'and', rules: [] });

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

You're all set! Check out the detailed usage guide below for more advanced features.

Usage Guide

Basic filter query

Build a simple filter with AND/OR combinators

Example.tsx

const [query, setQuery] = useState({
  combinator: 'and',
  rules: [
    { field: 'status', operator: 'equals', value: 'active' },
  ],
});

<QueryBuilder fields={fields} query={query} onQueryChange={setQuery} />

Output

Renders a visual query builder with a single rule row

Export to SQL WHERE clause

Convert the query object to a SQL WHERE expression

export.ts

import { formatQuery } from 'react-query-builder';

const sql = formatQuery(query, 'sql');
// "status = 'active' AND age > 18"

const json = formatQuery(query, 'json');

API Reference

QueryBuilder

The main React component. Renders an interactive visual query builder.

Signature

QueryBuilder(props: QueryBuilderProps): JSX.Element

Parameters

fieldsFieldConfig[]Required

Array of field definitions (name, label, type, options)

queryRuleGroupRequired

Controlled query state object

onQueryChange(query: RuleGroup) => voidRequired

Called whenever the query changes

fieldEditorComponentsRecord<string, React.ComponentType>

Custom renderer components keyed by field type

Returns

JSX.Element

Examples

<QueryBuilder fields={fields} query={query} onQueryChange={setQuery} />

formatQuery

Converts a RuleGroup to a string representation (SQL, JSON, or MongoDB)

Signature

formatQuery(query: RuleGroup, format: 'sql' | 'json' | 'mongodb'): string

Parameters

queryRuleGroupRequired

The query object from QueryBuilder state

format'sql' | 'json' | 'mongodb'Required

Output format

Returns

string

Examples

formatQuery(query, 'sql') // "name = 'Alice' AND age > 18"

validateQuery

Validates a query for completeness — returns errors for empty rules or invalid operators.

Signature

validateQuery(query: RuleGroup, fields: FieldConfig[]): ValidationResult

Parameters

queryRuleGroupRequired

The query to validate

fieldsFieldConfig[]Required

Field definitions used to validate field names and types

Returns

ValidationResult — { valid: boolean; errors: string[] }

Examples

const { valid, errors } = validateQuery(query, fields);

Examples

Real-world code examples and use cases

User filter with export to SQL

beginner

Build and export a user filter query

user-filtersql-export

UserFilter.tsx

function UserFilter({ onFilter }) {
  const [query, setQuery] = useState({ combinator: 'and', rules: [] });
  const fields = [
    { name: 'email', label: 'Email', type: 'text' },
    { name: 'role', label: 'Role', type: 'select', options: ['admin', 'editor', 'viewer'] },
  ];
  return (
    <>
      <QueryBuilder fields={fields} query={query} onQueryChange={setQuery} />
      <button onClick={() => onFilter(formatQuery(query, 'sql'))}>Apply Filter</button>
    </>
  );
}

Nested AND/OR groups

intermediate

Example of complex nested query structure

nestedcomplex

complexQuery.ts

const complexQuery = {
  combinator: 'or',
  rules: [
    {
      combinator: 'and',
      rules: [
        { field: 'role', operator: 'equals', value: 'admin' },
        { field: 'status', operator: 'equals', value: 'active' },
      ],
    },
    { field: 'email', operator: 'endsWith', value: '@company.com' },
  ],
};

Server-side validation with Zod

intermediate

Validate the formatted query on the API route

validationzodsecurity

api/validate.ts

import { z } from 'zod';

const AllowedFields = z.enum(['email', 'role', 'status']);
const AllowedOperators = z.enum(['equals', 'contains', 'startsWith']);

const RuleSchema = z.object({
  field: AllowedFields,
  operator: AllowedOperators,
  value: z.string().max(200),
});

const result = RuleSchema.safeParse(incomingRule);

Installation

Requirements

npm install

Quick Start

Install the package

Render the QueryBuilder

Usage Guide

Basic filter query

Export to SQL WHERE clause

API Reference

QueryBuilder

formatQuery

validateQuery

Examples

User filter with export to SQL

Nested AND/OR groups

Server-side validation with Zod

Related Content

Blog Posts

Projects

Installation

Requirements

npm install

Quick Start

Install the package

Render the QueryBuilder

Usage Guide

Basic filter query

Export to SQL WHERE clause

API Reference

QueryBuilder

formatQuery

validateQuery

Examples

User filter with export to SQL

Nested AND/OR groups

Server-side validation with Zod

Related Content

Blog Posts

Projects