React Query Builder is a TypeScript library for building nested filter editors, formatting them into external query syntaxes, and parsing supported expressions back into builder state.

It also supports an optional SQL text mode for Builder, with built-in syntax and semantic validation, plus an optional Monaco-based advanced editor integration for protected locked ranges.

Full documentation, API reference, and the interactive demo are available on the project website:

• Documentation
• API
• Demo

Installation

npm install @vojtechportes/react-query-builder

React Query Builder supports React 18+.

UI Adapters

The package also exposes ready-made component mappings through versioned subpath exports:

• @vojtechportes/react-query-builder/mui/v9 for new Material UI projects
• @vojtechportes/react-query-builder/mui/v7 for applications still on MUI 7
• @vojtechportes/react-query-builder/antd/v6 for new Ant Design projects
• @vojtechportes/react-query-builder/antd/v5 for applications still on Ant Design 5

Install the peer dependencies that match the adapter you want to use and pass the exported components object to Builder.

Material UI example:

npm install @mui/material@^9.0.1 @mui/icons-material@^9.0.1 @emotion/react @emotion/styled

import React from 'react';
import { Builder } from '@vojtechportes/react-query-builder';
import { components } from '@vojtechportes/react-query-builder/mui/v9';

export const MyMuiBuilder = () => {
  return (
    <Builder
      fields={fields}
      data={data}
      components={components}
      onChange={setData}
    />
  );
};

Ant Design example:

npm install antd@^6.0.0 @ant-design/icons@^6.0.0

import React from 'react';
import { Builder } from '@vojtechportes/react-query-builder';
import { components } from '@vojtechportes/react-query-builder/antd/v6';

export const MyAntdBuilder = () => {
  return (
    <Builder
      fields={fields}
      data={data}
      components={components}
      onChange={setData}
    />
  );
};

ThemeProvider customizes the built-in default component set. It does not theme the MUI or ANTD adapters, which keep their styling in their host UI libraries.

More adapter details:

• Documentation: Adapters
• API: Adapters

Example

import React, { useState } from 'react';
import {
  Builder,
  type DenormalizedQuery,
  type IBuilderFieldProps,
} from '@vojtechportes/react-query-builder';

const fields: IBuilderFieldProps[] = [
  {
    field: 'STATE',
    label: 'State',
    type: 'LIST',
    operators: ['EQUAL', 'NOT_EQUAL'],
    value: [
      { value: 'CZ', label: 'Czech Republic' },
      { value: 'SK', label: 'Slovakia' },
    ],
  },
  {
    field: 'IS_IN_EU',
    label: 'Is in EU',
    type: 'BOOLEAN',
  },
];

const initialData: DenormalizedQuery = [
  {
    type: 'GROUP',
    value: 'AND',
    isNegated: false,
    children: [
      {
        field: 'STATE',
        operator: 'EQUAL',
        value: 'CZ',
        readOnly: true,
      },
      {
        field: 'IS_IN_EU',
        operator: 'EQUAL',
        value: true,
      },
    ],
  },
];

export const MyBuilder = () => {
  const [data, setData] = useState(initialData);

  return <Builder fields={fields} data={data} onChange={setData} />;
};

Text Mode

Builder can optionally switch between the visual query UI and a SQL text editor view.

<Builder
  fields={fields}
  data={data}
  textMode
  defaultMode="text"
  onChange={setData}
/>;

For advanced text editing, the package also exposes @vojtechportes/react-query-builder/monaco. The built-in editor is lightweight and works without extra dependencies, while the Monaco integration is the recommended path when locked query segments must stay protected in text mode.

• Documentation: Text Mode
• API: Builder
• API: Components

Read-only and Protected Editing

Rules and groups can be fully read-only or partially read-only through readOnly.targets.

• Rule targets: field, operator, value
• Group targets: combinator, negation

Targeted read-only controls stay visible but become non-editable. When using the Monaco text editor integration, protected SQL fragments remain locked while users can still edit the unlocked parts of the query.

By default, deleting a group is also blocked when that delete would indirectly remove read-only protected descendants. Set readOnlyProtectsDelete={false} on Builder if you want to disable that subtree delete protection.

• Documentation: Locking and Read-only
• Documentation: Text Mode
• API: Builder
• API: Data

Query Conversion

The library also provides parser and formatter helpers through subpath exports:

• @vojtechportes/react-query-builder/formatQuery
• @vojtechportes/react-query-builder/parseQuery

Supported formats are documented on the website:

• Parsing and Formatting
• Supported Formats
• formatQuery API
• parseQuery API

Responsive Behavior

The default builder components include a compact responsive layout for medium-width screens.

• Rule rows reflow to preserve field, operator, action, and value legibility when horizontal space gets tighter.
• Multi-select values use a summarized closed state to avoid chip overflow.
• The default responsive behavior applies automatically when you use the built-in components.
• If you replace layout containers such as components.Rule or components.Group, your custom components are responsible for their own responsive behavior.

Responsive behavior is documented in more detail on the website:

• Components
• API: Components