@react-querybuilder/material

@react-querybuilder/material

Official react-querybuilder compatibility package for MUI/Material Design.

• Demo
• Full documentation
• CodeSandbox / StackBlitz example projects

Installation

npm i react-querybuilder @react-querybuilder/material @mui/icons-material @mui/material
# OR yarn add / pnpm add / bun add

Usage

To configure the query builder to use Material-compatible components, place QueryBuilderMaterial above QueryBuilder and beneath MaterialProvider in the component hierarchy.

import { createTheme, ThemeProvider } from '@mui/material/styles';
import { QueryBuilderMaterial } from '@react-querybuilder/material';
import { useState } from 'react';
import { type Field, QueryBuilder, type RuleGroupType } from 'react-querybuilder';

const muiTheme = createTheme();

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

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

  return (
    <ThemeProvider theme={muiTheme}>
      <QueryBuilderMaterial>
        <QueryBuilder fields={fields} defaultQuery={query} onQueryChange={setQuery} />
      </QueryBuilderMaterial>
    </ThemeProvider>
  );
}

QueryBuilderMaterial is a React context provider that assigns the following props to all descendant QueryBuilder elements. The props can be overridden on the QueryBuilder or used directly without the context provider.

Export	QueryBuilder prop
materialControlElements	controlElements
materialTranslations	translations
MaterialActionElement	controlElements.actionElement
MaterialDragHandle	controlElements.dragHandle
MaterialNotToggle	controlElements.notToggle
MaterialShiftActions	controlElements.shiftActions
MaterialValueEditor	controlElements.valueEditor
MaterialValueSelector	controlElements.valueSelector

[!TIP]

By default, this package uses icons from @mui/icons-material for button labels. To reset button labels to their default strings, use defaultTranslations from react-querybuilder.

<QueryBuilderMaterial translations={defaultTranslations}>

[!IMPORTANT]

In environments based on React Server Components, preload the MUI components.

Changelog

[v8.7.1] - 2025-06-09

Added

• CSS/SCSS variable rqb-base-color. rqb-background-color is rqb-base-color with 20% opacity (effectively the same color as before, just calculated differently).
• maxLevels prop to limit the addition of new rule groups beyond the specified nesting level. Default is Infinity (allows unlimited levels), and values other than 1 or greater will be ignored.