Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Unreleased

v6.5.3 - 2023-10-20

Added

#574 transformQuery enhancements:
- rules properties are no longer retained unconditionally. The rules property can be copied or renamed like any other property using the propertyMap option.
- propertyMap keys can now have false values. Properties matching a propertyMap key with a value of false will be removed without further processing (including the rules property, which would avoid recursion through the hierarchy althogether).
- New boolean option omitPath. When true, a path property will not be added to each rule and group in the query hierarchy.

Fixed

paramsKeepPrefix was not applying to bind variables generated from rules with an operator of “between”, “notBetween”, “in”, or “notIn”.

v6.5.2 - 2023-10-19

Changed

The useValueEditor hook will now update all values that are arrays (Array.isArray(value)) to the first element of the array (value[0]) when operator is anything except “between”, “notBetween”, “in”, or “notIn”. Previously this logic only applied when inputType was “number”. (To bypass this logic, pass { skipHook: true }.)

Added

New paramsKeepPrefix option for formatQuery, which enables compatibility with SQLite. When used in conjunction with the "parameterized_named" export format, the params object keys will maintain the paramPrefix string as it appears in the sql string (e.g. { $param_1: 'val' } instead of { param_1: 'val' }).

Fixed

#523 parseMongoDB now properly handles objects in the form of { fieldName: { $not: { /* ...rule */ } } }. This problem was particularly evident for $regex operators that should have generated rules with "doesNot[Contain/BeginWith/EndWith]" operators, since formatQuery(query, 'mongodb') produces this structure and parseMongoDB was not handling the inverse operation.
isRuleGroup will not error when the argument is null.
#572 parseSQL now recognizes signed numeric values like -12 or +14.

v6.5.1 - 2023-06-26

Fixed

AntDValueEditor calls generatePicker from the correct import.
Packages no longer “masquerade as CJS” when imported from ESM under "node16" module resolution.

v6.5.0 - 2023-06-13

Changed

#529 Drag handle components will no longer be rendered unless drag-and-drop is enabled. Previously, drag handle components were rendered unconditionally. Accordingly, the default stylesheet no longer applies display: none to the queryBuilder-dragHandle class when drag-and-drop is disabled since the components will not be rendered anyway.

Added

#529 New props for several sub-components:
- The parent rule object will now be provided to fieldSelector, operatorSelector, valueSourceSelector, and valueEditor components.
- The parent ruleGroup object will now be provided to notToggle components.
- The parent ruleOrGroup object will now be provided to dragHandle components.

Fixed

#529 The full rule object will now be passed to field-based validator functions. Previously, the parameter object only included the field, operator, valueSource, and value properties of the rule.

v6.4.1 - 2023-05-23

Fixed

The custom JsonLogic operators startsWith and endsWith (properties of jsonLogicAdditionalOperators) now check the type of the first parameter before calling the respective methods. This avoids errors like “Uncaught TypeError: Cannot read properties of null (reading ‘startsWith’)” when a field in the object being evaluated is null.

v6.4.0 - 2023-05-20

Changed

#517 @react-querybuilder/mantine now requires Mantine v6. React Query Builder v6.3.0 is compatible with Mantine v5.

Added

#519 Extracted event default/propagation code from Rule and RuleGroup into a new useStopEventPropagation hook.

Fixed

transformQuery no longer reassigns or remaps properties that don’t already exist in the source query object.

v6.3.0 - 2023-05-03

Changed

#503 Merged @react-querybuilder/ctx and @react-querybuilder/ts back into the main react-querybuilder package.

Fixed

#503 Resolved dependency issues in some environments.
#503 Corrected query-builder.css.map “sources” path.

v6.2.0 - 2023-04-28

Changed

#499 @react-querybuilder/material no longer loads MUI components asynchronously. Therefore, the components no longer need to be preloaded to avoid a flash of unstyled content.

Fixed

transformQuery with the deleteRemappedProperties option set to true (which is the default) will not attempt to delete properties that do not exist on the object (per Object.hasOwn()).

v6.1.4 - 2023-03-27

Fixed

Subpath exports for utility functions (formatQuery, transformQuery, and the parse* functions) now map to their TypeScript types and work for all module resolution strategies.

v6.1.3 - 2023-03-24

Fixed

#491 Chakra UI components no longer have hardcoded style-related props like size, variant, and colorScheme.
#491 The schema prop will no longer be passed down to Ant Design and Chakra UI components.

v6.1.2 - 2023-03-21

Fixed

parseCEL now recognizes dot-separated identifiers correctly.

v6.1.0 - 2023-03-16

Fixed

#488 The formatQuery option quoteFieldNamesWith now applies to values that represent field names (i.e. valueSource: 'field') when exporting to a SQL-based format.

Added

#488 The formatQuery option ruleProcessor now applies to the “sql” format (though notably not the other SQL-based formats, “parameterized” and “parameterized_named”), allowing complete control over each rule’s translation to SQL. The default rule processor for “sql” is exported as defaultRuleProcessorSQL.

v6.0.7 - 2023-03-10

Fixed

#486 Custom, non-legacy valueProcessor functions called from formatQuery will now receive all relevant options, not only parseNumbers.

v6.0.6 - 2023-03-07

Fixed

#483 The regular expression behind parseSQL in the previous version was capturing too many characters when field names were wrapped in delimiters.

v6.0.5 - 2023-03-06

Fixed

#479 parseSQL is now much more permissive of valid characters within strings and identifiers (whether they are delimited or plain). (#478 only added recognition of spaces within delimited identifiers.)

v6.0.4 - 2023-03-05

Fixed

#478 parseSQL now recognizes field names wrapped in square brackets, like [field name]. (The corresponding update to formatQuery was made in #463 as part of v6.0.0).

v6.0.3 - 2023-03-02

Fixed

#472 All development-mode console error messages have been (temporarily) removed to avoid the process is not defined issue.
BulmaValueSelector now adds the "is-multiple" class to the wrapper div when the multiple prop is true.

v6.0.2 - 2023-02-25

Fixed

#470 parseSQL now handles escaped single quotes within strings

v6.0.1 - 2023-02-22

Added

Fluent UI compatibility package

v6.0.0 - 2023-02-18

Changed

#455 A UMD build is no longer provided. See new instructions for buildless environments using ESM).
#431 Major ValueEditor update–including the ValueEditors in the compatibility packages–for “between”/”notBetween” operators. When the operator for a rule is “between” or “notBetween”, two inputs will be displayed. Each will have the class “rule-value-list-item”. They will manage the value as a comma-separated list unless listsAsArrays is true, in which case a proper array will be used.
#431 The default border radius on rule groups and branch lines (SCSS variable $rqb-border-radius) is now 0.25rem (previously 4px). Visually, this should be the same for most users since 16px is the default font-size on most browsers, and $16 \times 0.25 = 4$.
#431 Utility function c has been removed. Use a package like clsx (what RQB uses internally) instead.
#431 Bulma compatibility components no longer specify the is-small class, so they will be rendered at their default size.

Fixed

#452 All packages now use the "exports" field in their package.json for better ESM compatibility.

Added

#452 New ValueEditor prop selectorComponent (optional) enables the replacement of only the selector component in the value editor without recreating the logic in the default value editor. E.g., const MyValueEditor = (props: ValueEditorProps) => (<ValueEditor {...props} selectorComponent={MyValueSelector} />) will use the default value editor logic and presentation except when it would normally display the default ValueSelector.
#452 New React Native-compatible package @react-querybuilder/native and associated example showcasing multiple UI libraries.
#452 New exports:
- useQueryBuilder: All logic and configuration formerly internal to the QueryBuilder component has been extracted into a custom Hook, making it easy to implement one’s own presentation layer without reproducing or copy-pasting the official component code.
- useRuleGroup: As useQueryBuilder is to the QueryBuilder component, the useRuleGroup Hook is to the RuleGroup component.
- useRule: As useRuleGroup is to the RuleGroup component, the useRule Hook is to the Rule component.
- RuleGroupHeaderComponents/RuleGroupBodyComponents: These JSX fragments have been extracted from the RuleGroup component and exposed as named exports, enabling the creation of a custom RuleGroup wrapper without recreating the “innards” of the default RuleGroup. (For example, the new @react-querybuilder/native package wraps these fragments in View elements from react-native).
#431 New props and Hook returns to support ValueEditors new behavior for “between”/”notBetween” operators.
- New QueryBuilder prop getValueEditorSeparator: Takes a field name and an operator name and should return a ReactNode (string, element, etc.) that will be placed between the two editors when operator is “between” or “notBetween”. E.g., getValueEditorSeparator={() => "and"}.
- New QueryBuilder prop parseNumbers: When true, the default ValueEditor will update its rule with an actual number instead of the string representation whenever possible.
- New ValueEditor prop skipHook: When true, the useValueEditor hook call within the default ValueEditor component will not make query updates. Enables safer rendering of the default ValueEditor as a fallback to a custom value editor.
- The useValueEditor hook now returns an object with valueAsArray and multiValueHandler properties. See ValueEditor code for usage.
#455 regenerateIDs works for any object, not just rule groups.
#455 Query tools (add, remove, update, and move) will fail gracefully and return the original query if the provided path or parentPath points to an invalid location in the query hierarchy.
#463 The formatQuery option quoteFieldNamesWith now accepts an array of strings with two elements. The first element will precede each field name and the second will succeed each field name. E.g., ['[', ']'] would result in `[Field name] ...`.

v5.4.1 - 2023-01-30

Fixed

#458 Fixed parseJsonLogic output when a negated “between”, “in”, “contains”, “beginsWith”, or “endsWith” rule is the only operation.

v5.4.0 - 2023-01-06

Changed

#443 Automatically generated ids are no longer prefixed with "g-" or "r-".
The default border color has changed from #7f81a2 to #8081a2. This difference will almost certainly be imperceptible.

Fixed

#443 generateID no longer tries to require('crypto') which should allow its use in more environments and build targets.

Added

#443 New prop idGenerator can be used to override the default generateID function.

v5.3.3 - 2022-12-27

Fixed

New jsonLogicOperations option was causing parseJsonLogic to return a rule instead of a group if only one JsonLogic rule was passed in.

v5.3.2 - 2022-12-26

Added

#434 Added jsonLogicOperations option to parseJsonLogic to enable parsing of custom operations.

v5.3.1 - 2022-12-23

Fixed

#432 The crypto package was used in a way that didn’t work in some Node environments.

v5.3.0 - 2022-12-23

Changed

New rule and group ids are now generated as valid v4 UUIDs using crypto.getRandomValues() instead of Math.random(). The generateID function used internally is exported.
#418 TypeScript interface NameLabelPair has been deprecated and is now an alias for the Option interface.

Fixed

#407 Drag-and-drop will now allow drops on locked rules (which places the dragged rule/group below the drop target) and above locked rules/groups.
#411 When showCombinatorsBetweenRules is enabled, a combinator selector immediately above a locked rule/group will no longer be locked unless the group it belongs to is locked.
jsonLogicAdditionalOperators is exported again (documentation).

Added

#422 Adding the class queryBuilder-branches displays “tree view” branch lines.
#426 Dynamic classnames based on the specific rule/group properties.
- New function props getRuleClassname and getRuleGroupClassname are passed the rule or group, and the return value will be added as a class to the surrounding div.
- Field, Operator, and new interface Combinator now have an optional className property that will be applied to rules or groups that specify the appropriate attribute.
#417 Optional arity property for operators. When arity is either “unary” or a number less than 2, the value editor will not render when that operator is selected (similar to the standard “null”/”notNull” operators).
#408 The interfaces Option (née NameLabelPair), Field, and ValueEditorProps now accept generics for name and other properties.
#418 A new OptionList type covers the options property for all standard selection lists (field, operator, combinator, etc.). Previously this was a union type: NameLabelPair[] | OptionGroup<NameLabelPair>[]. OptionList is equivalent to this type, but 1) doesn’t require typing the base type twice, and 2) uses the new Option name instead of the deprecated NameLabelPair.
#421 When independentCombinators is enabled, custom onAddRule and onAddGroup callbacks can add a combinatorPreceding property to the rule/group which will end up being the combinator inserted above the new rule/group (if the parent group is not empty).

v5.2.0 - 2022-11-26

Added

#403 Add onRemove prop and pass rule/group to all ActionElements (buttons).

v5.1.3 - 2022-11-23

Fixed

#387 Support antd version 5.

v5.1.2 - 2022-11-21

Fixed

#399/#401 When dragging a rule or group over a group header, the dndOver class is no longer applied to child group headers.

v5.1.1 - 2022-10-27

Fixed

parseMongoDB and parseJsonLogic now respect independentCombinators option.
Narrowed rule group types, like DefaultRuleGroupType and DefaultRuleGroupTypeIC, are respected by convertFromIC and convertToIC.

Miscellaneous

v3 documentation was migrated from dedicated README to website versioned docs

v5.1.0 - 2022-10-26

Fixed

#394 parseJsonLogic now handles null values correctly.

Added

#392 parseMongoDB utility for importing queries from MongoDB.

v5.0.0 - 2022-10-22

Changed

Internet Explorer is no longer supported.
The minimum TypeScript version is now 4.5.
When defaultQuery is defined, an id property will be added to each rule and group in the query hierarchy. This will be reflected in the onQueryChange callback parameter. In previous versions defaultQuery was not modified by the component itself, but id is now added because it is a required attribute internally.
Related to the previous bullet, the prepareRuleGroup utility function will no longer coerce the not property of groups to be a boolean type (or even defined at all).
#385 MongoDB output has been simplified: The $eq and $and operators are only used when necessary.
#343 Drag-and-drop functionality migrated
- In order to make the react-dnd dependency completely optional when the enableDragAndDrop prop was not set to true, drag-and-drop functionality was extracted from react-querybuilder into a new package called @react-querybuilder/dnd.
- The new package has peerDependencies of react-dnd and react-dnd-html5-backend (each of which can be any version >= 14, as long as they match), but no hard dependencies. The only external dependencies in the main package now are immer and clsx.
- Upgrade path: To enable drag-and-drop functionality in v5, nest <QueryBuilder /> within a <QueryBuilderDnD /> element. The enableDragAndDrop prop is implicitly true when using QueryBuilderDnD, so you no longer need to set it explicitly unless it should be false (which can be set on QueryBuilderDnD or QueryBuilder).
```
 export function App() {
   return (
-    <QueryBuilder enableDragAndDrop />
+    <QueryBuilderDnD>
+      <QueryBuilder />
+    </QueryBuilderDnD>
   );
 }
```
- If your application already uses react-dnd and renders DndProvider higher in the component tree, replace QueryBuilderDnD with QueryBuilderDndWithoutProvider.

Fixed

#324 The @react-querybuilder/material package now properly inherits the theme configuration from ancestor ThemeProviders. Note: the @mui/material components are now loaded asynchronously by default, so the query builder will initially be rendered with the default components. See the documentation or the README to find out how to render the MUI components immediately.
parseCEL now handles strings correctly (including multi-line strings).
#389 AntDValueSelector properly handles empty string values in multiselect mode.

Added

Each compatibility package now exports its own context provider that injects the appropriate controlElements and controlClassnames properties into any descendant QueryBuilder components (composition FTW!). This is now the recommended usage for all compatibility packages.
The onAddRule and onAddGroup callback props now receive an optional “context” parameter as the fourth argument. This parameter can be provided by a custom addRuleAction/addGroupAction component to its handleOnClick prop. This allows users to alter or replace the default rule based on arbitrary data. For example, the addRuleAction component could render two “add rule” buttons which add different rules depending on which one was clicked, as long as they provided a different context parameter.
When drag-and-drop is enabled, rules will be copied instead of moved if the user has a modifier key (Alt on Windows/Linux, Option ⌥ on Mac) pressed when the drop occurs.
formatQuery has a new ruleProcessor configuration option applicable to non-SQL query language formats. When provided, the entire rule output will be determined by the function. For the relevant formats, valueProcessor already behaved this way; the default “value” processors have been renamed to defaultRuleProcessor[Format] to clarify the behavior. The default processors’ original “value” names are deprecated but still available (with no immediate plans to remove them).
parseSQL will now ignore a leading WHERE keyword, e.g. parseSQL("WHERE firstName = 'Steve'") will not fail to produce a query rule like in v4.

Miscellaneous

The documentation site now has separate documentation for past versions.
The controlElements prop has a new option: inlineCombinator. By default, this is a small wrapper around the combinatorSelector component that is used when either showCombinatorsBetweenRules or independentCombinators is true. The inlineCombinator option was only added to support @react-querybuilder/dnd, so there is almost certainly no reason to use it directly.

v4.5.3 - 2022-09-28

Fixed

#364 The array passed to the fields prop was being mutated if it contained duplicates, whether they were duplicate field names or option group labels. The fields prop is now treated as immutable.
#374 RuleGroup was using unstable keys to render elements in the rules array. Keys are now stable based on id properties, which are auto-generated if not provided in the query/defaultQuery prop.

v4.5.2 - 2022-08-19

Fixed

Backslashes are now properly escaped when formatQuery generates JSON.parse-able strings (“mongodb” and “json_without_ids” formats).
The parse* import methods properly handle backslashes.
#353 The moment package is no longer included in the build for @react-querybuilder/antd.

Added

#333 When a rule has an operator of “between”/”notBetween” and either valueSource: "field" or valueEditorType: "select", the default ValueEditor will display two drop-down lists. The values of the drop-down lists will be joined with a comma when the rule’s value property is updated.
#337 In conjunction with the “between”-related enhancements above, a new Boolean prop has been added to <QueryBuilder /> called listsAsArrays. This prop works in a similar manner to the parse* option of the same name. When the prop is true, ValueEditor (and ValueSelector for multiple: true) will store lists of values, including “between” value pairs, as proper arrays instead of comma-separated strings.
- Existing, default format:
  - { field: "f1", operator: "between", value: "f2,f3", valueSource: "field" }
- listsAsArrays format:
  - { field: "f1", operator: "between", value: ["f2", "f3"], valueSource: "field" }

v4.5.1 - 2022-06-21

Fixed

The type ValueProcessor was incorrectly including the new ValueProcessorByRule type. ValueProcessor is now simply an alias for ValueProcessorLegacy, which should undo a breaking change from v4.5.0.

v4.5.0 - 2022-06-19

Changed

TL;DR: These are probably not breaking changes.

While a breaking change in a minor release technically violates semver, the change in question is only “breaking” in a very rare–possibly non-existent–case. The only case where this change will break anything is if you use formatQuery with a custom valueProcessor that accepts fewer than three (3) arguments. Click for details…

#319 formatQuery will now invoke custom valueProcessor functions with different arguments based on the function’s .length property, which is the number of arguments a function accepts excluding those with default values:
- If the valueProcessor function accepts fewer than three (3) arguments, it will be called like this:
```
valueProcessor(rule, { parseNumbers });
```
The first argument is the RuleType object directly from the query. The second argument is of type ValueProcessorOptions, which is a subset of FormatQueryOptions (currently { parseNumbers?: boolean; }).
- To maintain the current behavior (valueProcessor(field, operator, value, valueSource)), make sure the valueProcessor function accepts at least three arguments with no default values (do not use = for the first three arguments). For example, the following code will log length: 1:
```
const valueProcessor = (field: string, operator = '=', value = '') => '...';
console.log(`length: ${valueProcessor.length}`);
```
- If you use TypeScript, these conditions will be enforced automatically.

Added

#319 Invoking valueProcessor with the full RuleType object provides access to much more information about specific rules. Standard properties that were previously unavailable include path, id, and disabled, but any custom properties will also be accessible.
- The default value processors for “sql”, “parameterized”, “parameterized_named”, “mongodb”, “cel”, and “spel” formats have not changed, but alternate functions using the new fn(rule, options) signature are now available:
  - defaultValueProcessorByRule
  - defaultValueProcessorCELByRule
  - defaultValueProcessorMongoDBByRule
  - defaultValueProcessorSpELByRule
#320/#323 New parser functions (also available as standalone builds in the dist folder). Click the respective “Import from [format]” button in the demo to try them out.
- parseJsonLogic takes a JsonLogic object and converts it to RuleGroupType.
- parseCEL takes a CEL string and converts it to RuleGroupType. Click the “Import from CEL” button in the demo.
#328 New utility function transformQuery recursively processes rule groups and rules with the provided ruleProcessor, ruleGroupProcessor, and other options (documentation).

Fixed

#323 formatQuery outputs will now escape quotation marks when appropriate:
- For SQL (“sql”, “parameterized”, “parameterized_named”), single quotes will be doubled up, e.g. (firstName = 'Ra''s')
- For other formats, double or single quotes will be escaped with a backslash if necessary (firstName == 'Ra\'s' or firstName == "Ra\"s").
#323 The standalone builds of formatQuery and parseSQL no longer include React and are not minified.

v4.4.1 - 2022-06-03

Added

New export format options:
- JsonLogic (formatQuery docs, JsonLogic.com)
- Spring Expression Language (SpEL) (formatQuery docs, docs.spring.io)
MongoDB export format now supports RuleGroupTypeIC (independent combinators).

v4.4.0 - 2022-05-30

Changed

(This list may look long, but the breaking changes should only affect a small minority of users.)

Several utility functions that were trivial or only really useful internal to this package are no longer exported from react-querybuilder. To see which ones, check the internal folder. All exports from that folder were previously exported from the utils folder, which is re-exported in its entirety from the main entry point.
The RuleProps and RuleGroupProps interfaces have deprecated the props that were individual properties of rules/groups, and have added a prop containing the full rule or group object. This should only affect users that implement a custom <RuleGroup /> component but use the default <Rule /> component, since <Rule /> now expects a rule prop.
- In RuleProps: field, operator, value, and valueSource are deprecated and replaced by rule: RuleType.
- In RuleGroupProps: combinator, rules, and not are deprecated and replaced by ruleGroup: RuleGroupTypeAny.
Internal methods for immutably updating queries have been moved from the schema prop to the new actions prop on both RuleProps and RuleGroupProps. Custom <Rule /> and <RuleGroup /> components will need to adjust their prop declarations.

Fixed

vite-tsconfig-paths was mistakenly added to the dependencies list instead of devDependencies for the main package in v4.1.3.

Added

debugMode now triggers logging when the query or options are updated and when a query update fails for some reason (e.g. the path is disabled).
New onLog callback prop is used instead of console.log when debugMode is true.
As a consequence of the new properties on RuleProps and RuleGroupProps (rule and ruleGroup, respectively), custom <Rule /> and <RuleGroup /> components now have access to their full rule/group objects, including any non-standard properties. This can greatly simplify the use of customized query objects.
<QueryBuilder /> will detect potential problems with using the component in a controlled vs uncontrolled manner and will log errors to the console (in “development” mode only). This includes the following situations:
- Both query and defaultQuery props are defined (TypeScript will complain about this at compile time, errors will be logged at run time)
- query prop is undefined in one render and then defined in the next render
- query prop is defined in one render and then undefined in the next render

v4.3.1 - 2022-05-21

Changed

If using TypeScript, custom operatorSelector components will now need to accommodate OptionGroup<NameLabelPair>[] in addition to the normal NameLabelPair[].

Added

#304 Many compatibility components now accept the props of the rendered library component in addition to the standard props (see documentation), allowing customization specific to the style library.
#306 New prop autoSelectOperator (documentation) behaves like autoSelectField but for the operator selector.
- The fields and operators properties of the translations prop object now accept placeholderName, placeholderLabel, and placeholderGroupLabel properties (documentation). These translatable strings set the default field and operator values and labels when autoSelectField and/or autoSelectOperator are set to false.
- Corresponding options were also added to formatQuery, which will now ignore rules where the field or operator match the placeholder values for most export formats.
#303 Added support for wildcards concatenated to field names in parseSQL. Examples:

SQL	Generated `RuleType` object
`"lastName LIKE firstName \|\| '%'"`	{ "field": "lastName", "operator": "beginsWith", "value": "firstName", "valueSource": "field" }
`"lastName NOT LIKE '%' \|\| firstName \|\| '%'"`	{ "field": "lastName", "operator": "doesNotContain", "value": "firstName", "valueSource": "field" }

Fixed

#301 react-querybuilder and the compatibility packages are all built with React v18 now (the peerDependencies version is still ">=16.8.0"). Previous 4.x versions were usable within React 18 applications, but now the build and tests explicitly use it.
#308 The CodeSandbox CI template is now located within the repository, and several other CodeSandbox-compatible examples have been added as well (see examples folder).

v4.2.5 - 2022-05-12

Added

Added two options to the translations prop: fields.placeholderLabel and fields.placeholderGroupLabel. These will be used in place of the default "------" when the autoSelectField prop is set to false.
All translation properties are now optional.

v4.2.4 - 2022-05-12

Added

Added a parseNumbers option for formatQuery.
Added a debugMode prop on <QueryBuilder />.

v4.2.3 - 2022-04-05

Added

Common Expression Language (CEL) export format for formatQuery.

v4.2.2 - 2022-03-12

Fixed

This release fixes the “IC” aka “independent combinator” type exports (RuleGroupTypeIC, etc.).

v4.2.1 - 2022-03-03

Added

This release adds an operator parameter to the comparator function property of the Field interface.

v4.2.0 - 2022-02-02

Changed

When calling formatQuery with the “mongodb” format and a custom valueProcessor, the valueProcessor function will now need to return the full expression object and not just the operator/value portion. For example, defaultMongoDBValueProcessor('firstName', '=', 'Steve') previously returned {"$eq":"Steve"}, but now returns {"firstName":{"$eq":"Steve"}}.

Fixed

#276 When using react-querybuilder v4 within an application that already implemented react-dnd, an error would appear: “Cannot have two HTML5 backends at the same time.” This can now be resolved by using the <QueryBuilderWithoutDndProvider /> component instead of <QueryBuilder />. They are functionally the same, but the former allows (in fact, relies on) a react-dnd backend (e.g. react-dnd-html5-backend) to be implemented higher up in the component tree.
Previously, the parseSQL method would accept boolean comparison clauses with an identifier (field name) on the left or right of the operator, but not on both sides (at least one side had to be a primitive string, numeric, or boolean). If the identifier was on the right, parseSQL would flip the clause so that the field name was on the left and the value on the right, but it wouldn’t flip the operator (< should become >, etc.). The operator will now be flipped when appropriate.

Added

Compare fields to other fields. The default <ValueEditor /> component can now display a filterable list of fields from the fields prop given the right configuration. formatQuery and parseSQL have also been updated to support this feature.
Query tools: Several methods are now available to assist with manipulation of query objects outside the context of a <QueryBuilder /> element:
- add - appends a new rule or group (and a preceding independent combinator if appropriate) to the end of a rule group’s rules array
- remove - removes a rule or group (and the preceding independent combinator if one exists)
- update - updates a property of a rule or group, or updates an independent combinator
- move - moves (or clones, with new id and path) a rule or group to a new location in the query tree
Lock buttons: Use the showLockButtons prop to enable locking/unlocking (i.e. disabling/enabling) individual rules and groups (demo).
New valueEditorType and inputType options: In addition to the previously available options (“text”, “select”, “checkbox”, “radio”), the following new options are now officially implemented in the default <ValueEditor /> and all compatibility packages:
- valueEditorType
  - “textarea”
  - “multiselect”
- inputType
  - “date”
  - “datetime-local”
  - “time”
A UMD build is now available (demo).
The fields prop can now accept an object of type Record<string, Field>. (Field[] and OptionGroup<Field>[] are still supported.)
Each compatibility package now exports an object ready-made for the controlElements prop (as well as controlClassnames in the case of Bootstrap). No need to assign each component individually anymore.

v4.1.3 - 2022-01-18

Fixed

The path to the CommonJS build was wrong in package.json for the main package. This has been fixed.
The RuleGroupArray type (used for the rules property of RuleGroupType) has been simplified to (RuleType | RuleGroupType)[]. This should make it easier to extend and/or narrow RuleGroupType.

v4.1.2 - 2022-01-12

Fixed

parseSQL was returning conventional rule groups (combinators at the group level) in some situations even when the independentCombinators option was set to true. The option will now guarantee a return type of RuleGroupTypeIC.

Added

Added convertQuery method to toggle a query between the conventional structure with combinators at the group level (RuleGroupType) and the “independent combinator” structure (RuleGroupTypeIC, used with the independentCombinators prop). For unidirectional conversions, convertToIC and convertFromIC are also available.
The specific return type of the parseSQL method (RuleGroupType or RuleGroupTypeIC) is now inferred from the parameters.

v4.1.1 - 2022-01-10

Fixed

Improved recursive types RuleGroupType and RuleGroupTypeIC to pass down the R (rule) and C (combinator) generics to the rules array.

v4.1.0 - 2022-01-09

Fixed

Minimum TypeScript version has been lowered to 4.1.2, down from 4.5 in react-querybuilder v4.0.0.

Added

All ValueSelector-based components, including field selectors, operator selectors, combinator selectors, and value editors where the type is “select” now support option groups. Pass { label: string; options: NameLabelPair[] }[] instead of NameLabelPair[].
TypeScript types for rules and groups now use generics which can be used to narrow certain member types more easily.

v4.0.0 - 2021-12-28

Changed

Minimum TypeScript version is now 4.5.0.
The default styles (query-builder.css and query-builder.scss) now use flexbox. This should allow greater flexibility and more consistent styling, but you’ll need to use a different stylesheet for IE due to poor flexbox support. The new IE-compatible demo page uses styles more suitable for IE.
onAddRule and onAddGroup callbacks now pass a number[] (parentPath) as the second argument instead of a string (parentId).
The exported method findRule has been replaced by findPath, which is useful in conjunction with the previously mentioned onAddRule and onAddGroup callbacks.
A new drag handle element will always be rendered at the front of every rule and rule group header element, regardless of whether you enable the drag-and-drop feature (see Features section below). If drag-and-drop is disabled (the default setting), you should hide the drag handle by either 1) using the default stylesheet which hides it automatically when drag-and-drop is disabled, or 2) hiding it with a style rule like .queryBuilder-dragHandle { display: none; }.
Cloning a rule or group will insert the clone immediately after the original item instead of as the last item of the parent group.

Click to show internal changes (shouldn’t affect most users)

Dropped lodash dependency. Added immer and react-dnd.
Rule and RuleGroup props now include path: number[], and id may be undefined.
getLevel has been removed from the schema prop (internally we just use path.length now).
The following functions that are part of the schema prop have been refactored to use path or parentPath instead of id or parentId: onGroupAdd, onGroupRemove, onPropChange, onRuleAdd, onRuleRemove.

Fixed

The default ValueEditor component was calling the useEffect hook conditionally, which is way against the Rules of Hooks. It is now called unconditionally.
#258 When the formatQuery export format is “mongodb”, the resulting string can be parsed by JSON.parse (@mylawacad)

Added

Shiny new documentation site! https://react-querybuilder.js.org
We now provide official compatibility components for several popular style frameworks (as seen in the demo), with more to come! Check out the @react-querybuilder org on npm.
All props on the <QueryBuilder /> component are now optional
<QueryBuilder /> is now a properly controlled or uncontrolled component depending on which props are passed in. If you pass a query prop, the query will not change until a new query is passed in. You should use the parameter of the onQueryChange callback to update the query prop. Typically this involves using React’s useState hook. To render an uncontrolled component, don’t pass a query prop. You can set the initial query by using the new defaultQuery prop, and you can still listen for changes with onQueryChange.
The query-builder.scss file now uses variables instead of hard-coded colors and spacing. Feel free to import it and override the default values with your own theme’s colors/styles/etc.
Drag-and-drop! Pass the enableDragAndDrop prop to display a drag handle on each rule and group header. Users will be able to reorder and relocate rules and groups.
Independent combinators! Wait…what does that even mean? When the independentCombinators prop is true, <QueryBuilder /> will insert an independent “and/or” selector between each pair of sibling rules/groups. This new feature shouldn’t introduce any breaking changes since it’s opt-in, i.e. if independentCombinators is undefined or false, then the <QueryBuilder /> should behave basically the same as it did in v3.x.
New disabled prop to prevent changes to the query. All sub-components and form elements get the disabled prop as well. Pass true to disable the entire query, or pass an array of paths to disable specific rules/groups.
parseSQL method to import queries from SQL (documentation / demo – click the “Load from SQL” button).
formatQuery accepts a new format type: “parameterized_named” (documentation). This new format is similar to “parameterized”, but instead of anonymous ?-style bind variables, each parameter is given a unique name based on the field name and the order in the query. A corresponding paramPrefix option is available in order to use a different character than the default “:” within the sql string.

v4.0.0-beta.8 - 2021-12-24

Fixed

#255 Fix a couple of issues with the “mongodb” formatQuery export type (@mylawacad)

Added

#261 valueProcessor for “mongodb” export format
#252 Export RuleGroup component (@ZigZagT)
#250 Bulma compatibility package and demo
#248 disabled prop

v4.0.0-beta.7 - 2021-12-13

Fixed

#247 Fix drag-and-drop for independentCombinators

v4.0.0-beta.6 - 2021-11-27

Maintenance release focused on converting to a monorepo with Vite driving the build process.

Added

If using react-querybuilder with NodeJS, and you only want to use the formatQuery function, you no longer have to install React on the server as well. Just import formatQuery from 'react-querybuilder/dist/formatQuery'. Note: TypeScript types are not available for this export.

v4.0.0-beta.5 - 2021-11-12

Changed

Earlier 4.0 beta releases had an inlineCombinators prop. This has been renamed to independentCombinators.
Dropped lodash dependency. Added immer and react-dnd.

Styles

The default styles now use flexbox. This should allow greater flexibility and more consistent styling.
The query-builder.scss file now uses variables instead of hard-coded colors and spacing. Feel free to import it and override the default values with your own theme’s colors/styles/etc.

Structure

A new drag handle element sits at the front of every rule and rule group header element. If you are not using the drag-and-drop feature (see Features section below), you should hide the drag handle by using the default stylesheet which hides it automatically when enableDragAndDrop is false, or hide it with a rule like .queryBuilder-dragHandle { display: none; }.

Behavior

<QueryBuilder /> is now a properly controlled or uncontrolled component depending on which props are passed in. If you pass a query prop, the query will not change until a new query is passed in. You should use the parameter of the onQueryChange callback to update the query prop. Typically this involves using React’s useState hook. To render an uncontrolled component, don’t pass a query prop. You can set the initial query by using the new defaultQuery prop, and you can still listen for changes with onQueryChange.

Added

#235 Drag-and-drop! Pass the enableDragAndDrop prop to display a drag handle on each rule and group header. Users will be able to reorder rules and groups with the click (and drag) of a mouse.
New IE11-compatible demo page.

v4.0.0-beta.4 - 2021-11-03

Fixed

v4.0.0-beta.3 had an outdated build

Added

All props on the <QueryBuilder /> component are now optional

v4.0.0-beta.3 - 2021-11-03

Added

#231 inlineCombinators prop. When true, <QueryBuilder /> will insert an independent combinator (and/or) selector between each pair of sibling rules/groups. This new feature shouldn’t introduce any breaking changes, i.e. if inlineCombinators is undefined or false, then the <QueryBuilder /> should behave the same as it did in v4.0.0-beta.2. However, the TypeScript types are significantly more complex in this release so we’re going to leave this beta out for a while before releasing v4.0.0 properly.

v4.0.0-beta.2 - 2021-10-29

Added

#230 parseSQL method to import queries from SQL (try the demo).

v4.0.0-beta.1 - 2021-10-23

Changed

#229 Path-based query management
- Rule and RuleGroup props now include path: number[], and id may be undefined.
- getLevel has been removed from the schema prop.
- The following functions that are part of the schema prop have been refactored to use path or parentPath instead of id or parentId: onGroupAdd, onGroupRemove, onPropChange, onRuleAdd, onRuleRemove.
- onAddRule and onAddGroup callbacks now pass a number[] (parentPath) as the second argument instead of a string (parentId).
- The exported method findRule has been replaced by findPath, which is useful in conjunction with the previously mentioned, refactored onAddRule and onAddGroup callbacks.
- The onQueryChange callback’s argument, the current query object, will include a path for each rule and group. The formatQuery default output format, “json”, will also include paths.
- Rule and group divs now include a data-path attribute.

Added

formatQuery accepts a new format type: "parameterized_named". This new format is similar to "parameterized", but instead of anonymous ?-style bind variables, each parameter is given a unique name based on the field name and the order in the query. A corresponding option paramPrefix is available in order to use a different character than the default “:” within the sql string.
#228 CodeSandbox CI

v3.12.1 - 2021-10-06

Changed

The default ValueEditor will force the <input /> control to have type="text" if the field’s inputType is “number” and the operator is “between” or “notBetween”. When the operator changes to something else, the control will revert to type="number" and reset the value if the value included a comma (“,”).
The “parameterized” output of the formatQuery function will now include native numbers and boolean values in the params array if a rule’s value property is a number or boolean. Previously the array included "TRUE" or "FALSE" for boolean values, and numbers were converted to strings, e.g. old way -> params:["string","12","14","TRUE"], new way -> params:["string",12,14,true].

Fixed

Several bugs were squashed in the formatQuery function when dealing with the “in”, “notIn”, “between”, and “notBetween” operators.
A couple of bugs were fixed in the demo.

v3.12.0 - 2021-10-04

Changed

The only potentially breaking change in the main <QueryBuilder /> component is the addition of a <div> in the JSX output that wraps the child rules/groups of each group. It would only affect custom CSS rules like .ruleGroup > .rule, since .rule is no longer an immediate child of .ruleGroup. Now use something like .ruleGroup > .ruleGroup-body > .rule.
The formatQuery function will now ignore invalid rules for “sql”, “parameterized”, and “mongodb” output types. This includes rules that match one or more of the following criteria:
- The rule fails validation (see validation feature below) based on the validation map from the query validator or the result of the field validator.
- The rule’s operator is “in” or “notIn” and the value is neither a non-empty string nor an array with at least one element.
- The rule’s operator is “between” or “notBetween” and the value is neither an array of length two (rule.value.length === 2) nor a string with exactly one comma that isn’t the first or last character (rule.value.split(',').length === 2 and neither element is an empty string).
Cleaned up some internal stuff and dropped three dependencies! Lodash is now the only external dependency.

Added

#225 Validation: pass a validator prop to validate the entire query, or include a validator attribute on each field in the fields array to validate each rule based on the selected field.
- CSS classes will be added ("queryBuilder-valid" or "queryBuilder-invalid") to validated rules and groups, and all sub-components will receive the validation result as a prop.
- The formatQuery function has two new validation-related options: 1) validator (same signature as the prop mentioned earlier) and 2) fields (same shape as the fields prop). Rules and groups deemed invalid will be ignored if the output format is “sql”, “parameterized”, or “mongodb”.
#223 Rule/group cloning: pass the showCloneButtons prop to enable duplication of rules and groups. Associated controlElements properties are also available for custom clone button components.
#224 Add rule to new groups: pass the addRuleToNewGroups prop to add the default rule to all new groups automatically.
#224 Default operator: pass a getDefaultOperator function prop to determine which operator is set for new rules (or include a defaultOperator attribute on objects in the fields array to set the default operator for specific fields).
#224 Cancel or modify a new rule/group: use the onAddRule and onAddGroup callbacks to return a new rule/group that will be added instead of the default, or return false to cancel the addition of the new rule/group. (Note: to completely prevent the addition of new groups, you can also pass controlElements={{ addGroupAction: () => null }} which will hide the “+Group” button.)
New “between” and “not between” default operators: the formatQuantity function has also been updated to handle the new operators properly.
The demo has been updated with all the new features, and now includes tooltips on options and links to relevant documentation.

v3.11.1 - 2021-09-18

Changed

Relaxed and corrected types related to NameLabelPair
Simplified formatQuery for MongoDB

v3.11.0 - 2021-08-24

Added

#218 autoSelectField prop. When set to false, prevents automatic selection of the first field in new rules by adding an “empty” choice as the first option. When the “empty” option is selected, the operator and value components for that rule will not be displayed.

v3.10.1 - 2021-08-19

Added

#214 "mongodb" query export format (@CodMonk)

v3.10.0 - 2021-07-27

Added

New item in the translations prop object: notToggle.label
#210 Customizable label for “not” toggle component (@jakeboone02)

v3.9.9 - 2021-03-05

Changed

field, fieldData, and operator are now required in ValueEditorProps

v3.9.8 - 2021-02-22

Added

#190 Export default components ActionElement, NotToggle, ValueEditor, and ValueSelector (@jakeboone02)

v3.9.7 - 2021-02-18

Fixed

#188 Any extra attributes in the query prop will be persisted (@jakeboone02)

v3.9.6 - 2021-02-15

Fixed

Add base CSS to the package

v3.9.5 - 2021-02-08

Fixed

Updated README.md for npm

v3.9.4 - 2021-02-06

Fixed

Critical bug with v3.9.3 where React wasn’t in scope

v3.9.3 - 2021-02-05

Added

#179 Added enableMountQueryChange prop to allow disabling initial onQueryChange call (@saurabhnemade)

v3.9.2 - 2021-01-24

Added

#178 Export several default configuration options (@jakeboone02)
- defaultCombinators
- defaultOperators
- defaultTranslations
- defaultValueProcessor

v3.9.1 - 2021-01-17

Changed

#175 Replaced nanoid with Math.random() (@jakeboone02)

Fixed

This release removes the requirement to re-map the window.msCrypto object to window.crypto for IE11. Woohoo!

v3.9.0 - 2020-12-07

Added

#171 Add context prop to pass arbitrary data to custom components (@jakeboone02)

v3.8.4 - 2020-11-16

Added

#167 placeholder support for text fields (@eddie-xavi)

v3.8.3 - 2020-11-04

Fixed

Bug with using false as defaultValue

v3.8.2 - 2020-11-03

Fixed

#164 Fixed setting of default values (@jakeboone02)

v3.8.1 - 2020-10-23

Fixed

Gets correct default operator when using field-level config

v3.8.0 - 2020-10-09

Changed

The default operators list has been rearranged so that "=" is first in the list and therefore the default for new rules. Previously it was "null".

Added

Several options that required the use of functions at the query level can now be configured at the field level:
- Operators: use the operators property on a field instead of the getOperators prop
- Value editor type: use the valueEditorType property on a field instead of the getValueEditorType prop
- Input type: use the inputType property on a field instead of the getInputType prop
- Values: if the value editor type is select or radio, use the values property on a field instead of the getValues prop
- Default value: use the defaultValue property on a field instead of the getDefaultValue prop
#160 Added field-level configuration options (@jakeboone02)

v3.7.1 - 2020-10-07

Fixed

#158 createRule was setting name to undefined when fields are empty (@saurabhnemade)

v3.7.0 - 2020-10-04

Added

#157 getDefaultField and getDefaultValue props (@jakeboone02)

Fixed

Allow nulls to be returned from getOperators and getValueEditorType

v3.6.0 - 2020-10-01

Changed

#155 Refactored formatQuery options (@jakeboone02)
- valueProcessor is no longer the third argument of formatQuery. To use a custom valueProcessor, pass an options object as the second parameter and include valueProcessor as a key in that object.
- When the formatQuery format is set to sql (either by formatQuery(query, 'sql') or formatQuery(query, { format: 'sql' })), the values will be quoted with single quotes instead of double quotes, e.g. (name = 'Peter Parker').

v3.5.1 - 2020-06-22

Fixed

Prevent lodash from assigning global _ variable 74ee1ca

v3.5.0 - 2020-06-20

Changed

#145 Convert source to TypeScript (@jakeboone02)
#135 Reset value on operator change (@artenator)

Added

Option to reset rule on operator change
#144 IE11 support (@jakeboone02)

v3.4.0 - 2020-06-15

Added

#142 Customizable Rule component (@jakeboone02)

v3.3.0 - 2020-06-12

Added

#141 RuleGroup can now be replaced with a custom component (@rbalaine)

Changed

Some TypeScript type names have changed, e.g. Rule is now RuleType since Rule is an exported React component.

v3.2.0 - 2020-05-28

Added

#139 "parameterized" option for formatQuery (@jakeboone02)

v3.1.2 - 2020-03-19

Added

"json_without_ids" option for formatQuery

v3.1.1 - 2020-02-18

Fixed

v3.1.0 published files were outdated

v3.1.0 - 2020-02-18

Added

#122 resetOnFieldChange prop to control value and operator reset functionality on field change (@lakk1)

v3.0.2 - 2019-12-09

Fixed

v3.0.1 published files were outdated

v3.0.1 - 2019-12-06

Fixed

#117 Rule default value on add/change (@xxsnakerxx)

v3.0.0 - 2019-11-29

Added

#115 Add div.ruleGroup-header (@jakeboone02)
- A div with class ruleGroup-header now wraps around the rule group header elements to assist with styling those elements as a group. This may affect some custom CSS rules that depend on the particular HTML arrangement in versions earlier than 3.0.0.

v2.5.1 - 2019-11-11

Fixed

#113 Passing not property to rule groups below root (@RomanLamsal1337)

v2.5.0 - 2019-11-10

Changed

Lowercase operator labels

Fixed

#111, #112 formatQuery handle more operators (@oumar-sh)

v2.4.0 - 2019-09-23

Added

#107 fieldData prop for custom OperatorSelector and ValueEditor components (@jakeboone02)

v2.3.0 - 2019-09-16

Added

#104 Inversion ("not") toggle switch for rule groups (@jakeboone02)
#103 Added level and rule id to DOM elements (@srinivasdamam)

Changed

#102 Replace uuid with nanoid (@srinivasdamam)

v2.2.1 - 2019-08-29

Fixed

TypeScript definitions

v2.2.0 - 2019-08-29

Added

#96 showCombinatorsBetweenRules prop
#95 formatQuery function

Fixed

Added missing props to new ValueEditor types
Added title prop and completed ValueEditor props

v2.1.0 - 2019-08-27

Added

Enhanced default ValueEditor to handle multiple input types (#94)

v2.0.1 - 2019-08-27

Added

#93 Pass in new root to _notifyQueryChange (@pumbor)
#84 Add className prop to ValueEditor, pass it on to input element (@kkkrist)

v2.0.0 - 2019-08-18

Changed

#87 Hooks rewrite and increased test coverage (@jakeboone02)

Fixed

#82 Removed type restrictions on rule values (@jakeboone02)

v1.4.3 - 2018-04-08

Fixed

#60 Fixed TypeScript function parameter definitions (@jakeboone02)

v1.4.2 - 2018-03-02

Added

#55 Add optional id information in README (@CharlyJazz)

v1.4.1 - 2018-03-02

Added

#53 Add optional id property to fields (@CharlyJazz)

v1.4.0 - 2017-12-11

Fixed

#46 Types: Added id attribute to RuleGroup (@jakeboone02)

Added

#47 Add translations prop to be able to set translatable texts (@bubenkoff)
#44 Add TypeScript typings (@jakeboone02)
#42 Converted Rule subcomponents to SFCs (@jakeboone02)

v1.3.8 - 2017-07-14

Fixed

#37 package updates and making it compatible with codesandbox.io (@pavanpodila)

v1.3.6 - 2017-03-13

Added

#28 Add field to operator selector control element (@SamLoy)
#27 Added more context information to controlElements (@SamLoy)

v1.3.5 - 2017-02-06

Fixed

#24 README: Update live demo link to use v1.3.4 and React 15 (@mreishus)
#23 README.md Usage - destructuring removed from import (@mreishus)

v1.3.4 - 2017-01-23

Added

#18 Add code coverage & TravisCI (@maniax89)
#17 Add npm-based changelog generator (@maniax89)

v1.3.0 - 2016-10-12

Fixed

#15 Fix test setup (@maniax89)
#11 Move ‘this’ binding to componentWillMount (@maniax89)
#9 Remove unnecessary imports (@maniax89)

Added

#13 Rule group tests (@maniax89)
#12 Add ActionElement tests to <Rule /> (@maniax89)
#10 WIP: Add <Rule /> Tests (@maniax89)
#8 WIP: Added CHANGELOG.md (@maniax89)
#7 Add in ActionElement for custom <button /> elements (@maniax89)
#6 Custom rule controls (@maniax89)

v1.2.0 - 2016-07-11

Fixed

#1 fix missing field (@vitorhsb)

v1.1.0 - 2016-06-27

Added

controlClassnames prop
Documentation update

v1.0.10 - 2016-06-26

Fixed

Stop event propagation for buttons
Proper dist path

v1.0.9 - 2016-06-20

Added

Documentation update

v1.0.8 - 2016-06-19

Added

Documentation update

v1.0.7 - 2016-06-19

Added

Live demo URL to README

v1.0.6 - 2016-06-19

Added

react and react-dom to devDependencies

v1.0.5 - 2016-06-19

Fixed

Documentation update

v1.0.4 - 2016-06-19

Added

Documentation and demo

v1.0.3 - 2016-06-19

Added

Include query-builder.scss in dist

v1.0.2 - 2016-06-19

Added

“Pending” documentation note

v1.0.1 - 2016-06-19

Changed

Build artifacts moved from lib to dist

v1.0.0 - 2016-06-19

Added

Initial publish