@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.5.0] - 2025-04-07

Added

• [#873] New prop autoSelectValue (documentation) behaves like autoSelectField/autoSelectOperator but for the value editor when it renders a select list.
  • The translations prop object has a new property values that accepts placeholderName, placeholderLabel, and placeholderGroupLabel properties (documentation). These translatable strings set the default values and labels when autoSelectValue is set to false.
  • A corresponding placeholderValueName option was added to formatQuery, which will now ignore rules where the value matches the placeholder value as long as placeholderValueName is defined (this behavior differs from placeholderFieldName and placeholderOperatorName, which do not need to be defined).
• [#876] Miscellaneous i18n enhancements for the "natural_language" export format:
  • translations option: Map of the words "and", "or", "true", and "false" to their translated equivalents. Also covers prefix and suffix options for rule groups.
  • wordOrder option: Based on the linguistic concept of constituent word order, this option accepts all permutations of "SVO" ("SOV", "VSO", etc.) and outputs the field, operator, and value in the corresponding order (S = field, V = operator, O = value).
  • operatorMap option: Map of operators to their natural language equivalents. If the result can differ based on the valueSource, the key should map to an array where the second element represents the string to be used when valueSource is "field". The first element will be used in all other cases.
  • Date/time formatting support: The @react-querybuilder/datetime package now supports the "natural_language" format for date-type rules. Formatting can be customized by passing locales, dateFormat, or dateTimeFormat as properties of the context parameter. These options are passed to a Intl.DateTimeFormat constructor.

Fixed

• [#877] Dynamic imports of react-dnd and related packages are now obfuscated to discourage bundlers like webpack from pre-processing those imports.