Simple, highly configurable query builder
for React written in TypeScript

Documentation · Demo

---

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.

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} />;
};

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