@react-querybuilder/material

@react-querybuilder/material

Official react-querybuilder components for MUI/Material Design.

To see them in action, check out the react-querybuilder demo or load the example in CodeSandbox.

Full documentation

Installation

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

Usage

To render MUI-compatible components in the query builder, wrap the <QueryBuilder /> element in <QueryBuilderMaterial />.

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

const muiTheme = createTheme();

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

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

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

Notes

• This package exports materialControlElements which can be assigned directly to the controlElements prop on <QueryBuilder /> (and also exports each component individually), but wrapping <QueryBuilder /> in <QueryBuilderMaterial /> is the recommended method.
• In an environment based on React Server Components, preloading the MUI components may be necessary.

Changelog

[v7.7.0] - 2024-10-08

Changed

• The useValueEditor hook now requires the entire ValueEditorProps object instead of only requiring a subset of the props.

Added

• [#755] New controlElements properties ruleGroupHeaderElements and ruleGroupBodyElements, enabling customization/replacement/augmentation of the subcomponents within the rule group header and body wrappers without needing to reimplement the entire RuleGroup component.
• [#785] New prop suppressStandardClassnames. When true, no classes will be added automatically to any elements (custom classes defined in controlClassnames will still be applied). This includes conditional and event-based classes for validation, drag-and-drop, etc.
• [#785] A "dndCopy" class will be added when drag-and-drop is enabled and the modifier key (Alt or Option ⌥) is pressed while the drag phase begins. When using the default styles, the drag-and-drop indicator line will be green (#669933) instead of rebeccapurple (#663399).
• [#755] New useQueryBuilderNative hook. Works the same as useQueryBuilder, but tailored for React Native implementations.
• [#769] The parseNumbers prop now accepts an optional "-limited" suffix on existing string config values "enhanced", "strict", and "native". When the "-limited" suffix is used (e.g., parseNumbers="strict-limited"), values will only be parsed for numericity when the inputType is "number".
• [#769] formatQuery now accepts an optional concatOperator parameter to support non-standard concatenation methods in the various SQL dialects. The default is the ANSI standard "||", which is supported by PostgreSQL, Oracle, SQLite, and various others, while SQL Server uses "+". A value of "CONCAT" will enable MySQL compatibility by using the CONCAT function (do not use this for Oracle as its CONCAT function is limited).
• [#769] The toArray method now accepts an optional configuration parameter. If the retainEmptyStrings property of that object is true, the function will not filter out string elements that are empty or purely whitespace.
• [#769] The object returned from useValueEditor now includes a parseNumberMethod property, which is a processed version of the parseNumbers prop.
• [#769] formatQuery now accepts an optional preset option as a shortcut to configure the output for improved compatibility with different query language dialects. Options include "ansi", "mssql", "mysql", "oracle", "postgres", and "sqlite".
• [#769] formatQuery now accepts an optional fieldIdentifierSeparator string. When used in conjunction with the quoteFieldNamesWith option, field names will be separated by this string and bracketed individually per the quoteFieldNamesWith configuration (e.g., [table name].[field name] = 'value' instead of [table name.field name] = 'value').
• [#786] New formatQuery export format "natural_language", similar to the "sql" or "cel" formats but with English-language operators.

Fixed

• [#769] On rules using a "between"/"notBetween" operator, the second value no longer shifts into the first input when the first value is removed.
• [#769] Type ParseNumbersMethod renamed to ParseNumberMethod (singular) to better reflect its assocation with the parseNumber method as opposed to the parseNumbers prop.
• [#769] Internally, the default MongoDB rule processor for formatQuery uses actual JSON objects instead of manually constructing JSON.parse-able strings. This should lead to more reliably valid results.
• [#769] When generating SQL for a rule where (1) the operator is "between" or "notBetween", (2) the values are numeric, and (3) parseNumbers is true, formatQuery will place the smaller value first and the larger value second, regardless of their order in the rule's value property.
• [#779] When parseJSONata encounters an expression group where only two conditions exist for the same field, one greater-than and one less-than, a single "between"/"notBetween" rule will be generated. Previously a rule group with two separate rules would be generated.
• [#783] MantineValueSelector no longer sets the value to "" when clicking the selected option again.