` around the "Shift up"/"Shift down" buttons)
* `.undoRedoActions` (the wrapper `
` around the ["undo"/"redo" buttons](/docs/tips/undo-redo.md))
* `.rule-hasSubQuery` (applied to rules that render a subquery)
* `.queryBuilder-loading` (applied to rules/groups while an [async promise is pending](/docs/tips/async-option-lists.md))
* `.dndDragging` (applied to "preview" element while dragging)
* `.dndOver` (applied to "hovered over" element while dragging)
* `.dndCopy` (applied to "hovered over" element while dragging and the ["copy" modifier key is pressed](/docs/dnd.md#cloning-and-grouping))
* `.dndGroup` (applied to "hovered over" element while dragging and the ["group" modifier key is pressed](/docs/dnd.md#cloning-and-grouping))
* `.dndPreviewPosition` (applied to elements at the preview position during [update-while-dragging](/docs/dnd.md#updatewhiledragging))
* `.dndHidden` (applied to hide elements during [update-while-dragging](/docs/dnd.md#updatewhiledragging))
A full list of standard classnames is [below](#standard-classnames).
tip
Disable application of all standard classnames with the [`suppressStandardClassnames`](/docs/components/querybuilder.md#suppressstandardclassnames) prop.
.ruleGroup-combinators (and)\[ ].ruleGroup-notToggle.ruleGroup-addRule.ruleGroup-addGroup.ruleGroup-lock
.undoRedoActions-undo.undoRedoActions-redo
˄˅
.rule-fields (f1).rule-operators (=).rule-value.rule-cloneRule.rule-lock.rule-remove
˄˅
.ruleGroup-combinators (and)\[ ].ruleGroup-notToggle.ruleGroup-addRule.ruleGroup-addGroup.ruleGroup-cloneGroup.ruleGroup-lock.ruleGroup-remove
˄˅
.rule-fields (f1).rule-operators (=)This rule is valid.rule-cloneRule.rule-lock.rule-remove
˄˅
.rule-fields (f2).rule-operators (=)This rule is invalid.rule-cloneRule.rule-lock.rule-remove
˄˅
.ruleGroup-combinators (and).ruleGroup-notToggle.ruleGroup-addRule.ruleGroup-addGroup.ruleGroup-cloneGroup.ruleGroup-lock.ruleGroup-remove
˄˅
.rule-fields (f1).rule-operators (=).rule-cloneRule.rule-lock.rule-remove
˄˅
.rule-valueSource (f3).rule-operators (=)valuef1.rule-cloneRule.rule-lock.rule-remove
˄˅
Value list (fb1)betweenfield.rule-value-list-item (fb2).rule-value-list-item (fb2).rule-cloneRule.rule-lock.rule-remove
## Standard classnames[](#standard-classnames "Direct link to Standard classnames")
```
export const standardClassnames = {
queryBuilder: 'queryBuilder',
ruleGroup: 'ruleGroup',
header: 'ruleGroup-header',
body: 'ruleGroup-body',
combinators: 'ruleGroup-combinators',
addRule: 'ruleGroup-addRule',
addGroup: 'ruleGroup-addGroup',
cloneRule: 'rule-cloneRule',
cloneGroup: 'ruleGroup-cloneGroup',
removeGroup: 'ruleGroup-remove',
notToggle: 'ruleGroup-notToggle',
rule: 'rule',
fields: 'rule-fields',
matchMode: 'rule-matchMode',
matchThreshold: 'rule-matchThreshold',
operators: 'rule-operators',
value: 'rule-value',
removeRule: 'rule-remove',
betweenRules: 'betweenRules',
valid: 'queryBuilder-valid',
invalid: 'queryBuilder-invalid',
shiftActions: 'shiftActions',
undoRedoActions: 'undoRedoActions',
undoAction: 'undoRedoActions-undo',
redoAction: 'undoRedoActions-redo',
dndDragging: 'dndDragging',
dndOver: 'dndOver',
dndCopy: 'dndCopy',
dndGroup: 'dndGroup',
dndDropNotAllowed: 'dndDropNotAllowed',
dndPreviewPosition: 'dndPreviewPosition',
dndHidden: 'dndHidden',
dragHandle: 'queryBuilder-dragHandle',
disabled: 'queryBuilder-disabled',
muted: 'queryBuilder-muted',
lockRule: 'rule-lock',
lockGroup: 'ruleGroup-lock',
muteRule: 'rule-mute',
muteGroup: 'ruleGroup-mute',
valueSource: 'rule-valueSource',
valueListItem: 'rule-value-list-item',
branches: 'queryBuilder-branches',
justified: 'queryBuilder-justified',
responsive: 'queryBuilder-responsive',
hasSubQuery: 'rule-hasSubQuery',
loading: 'queryBuilder-loading',
valueDateTimeRelative: 'rule-value-dateTimeRelative',
} as const;
```
> *Source: [/packages/core/src/defaults.ts#L326-L374](https://github.com/react-querybuilder/react-querybuilder/blob/main/packages/core/src/defaults.ts#L326-L374)*
---
# Styling overview
React Query Builder has a [flexible structure with specific classes](/docs/styling/classnames.md) assigned to each element in the component hierarchy, enabling wide-ranging styling possibilities.
tip
Check out the [customization showcase](/docs/tips/showcase.md) for styling tips.
The default stylesheet is available in both CSS and SCSS formats, allowing you to override default values without replicating the entire rule set.
For layout-only styles (structural properties like `flex-direction`, `gap`, alignment—excluding decorative styles), import `query-builder-layout.css` (or `.scss`).
* CSS
* SCSS
```
@import 'react-querybuilder/dist/query-builder.css';
/* OR, for layout only: */
@import 'react-querybuilder/dist/query-builder-layout.css';
```
```
@use 'react-querybuilder/dist/query-builder.scss';
// OR, for layout only:
@use 'react-querybuilder/dist/query-builder-layout.scss';
```
## CSS variables[](#css-variables "Direct link to CSS variables")
Customize the default stylesheet by overriding CSS or SCSS variables.
info
CSS variables were introduced in **v8.3.0** and [SCSS variables](#scss-variables) have been available since **v4.0.0**. Both methods will continue to be supported.
Default variables:
* CSS
* SCSS
```
:root {
--rqb-spacing: 0.5rem;
--rqb-border-width: 1px;
--rqb-base-color: #004bb8;
--rqb-background-color: #004bb833;
--rqb-border-color: #8081a2;
--rqb-border-style: solid;
--rqb-border-radius: 0.25rem;
}
```
```
$rqb-spacing: 0.5rem;
$rqb-border-width: 1px;
$rqb-base-color: #004bb8;
$rqb-background-color: #004bb833;
$rqb-border-color: #8081a2;
$rqb-border-style: solid;
$rqb-border-radius: 0.25rem;
```
Example:
* CSS
* SCSS
```
@import 'react-querybuilder/dist/query-builder.css';
:root {
--rqb-spacing: 0.8rem; /* a little roomier than the default 0.5rem */
--rqb-background-color: #ccc3; /* gray, semi-transparent background */
}
```
```
@use 'react-querybuilder/dist/query-builder' with (
$rqb-spacing: 0.8rem, /* a little roomier than the default 0.5rem */
$rqb-background-color: #ccc3 /* gray, semi-transparent background */
);
```
### SCSS variables[](#scss-variables "Direct link to SCSS variables")
SCSS variables begin with `$` instead of `--`, but otherwise have the same name as their CSS counterpart (e.g., `$rqb-spacing` corresponds to `--rqb-spacing`).
SCSS allows you to customize the CSS variable prefix (`rqb-` by default) by setting `$rqb-var-prefix`.
```
@use 'react-querybuilder/dist/query-builder' with (
$rqb-var-prefix: myprefix-,
$rqb-spacing: 0.8rem
);
:root {
--myprefix-background-color: #ccc3;
}
```
## Branch lines[](#branch-lines "Direct link to Branch lines")
To add branch lines to the left side of rule groups, add the `queryBuilder-branches` class using the [`controlClassnames` prop](/docs/components/querybuilder.md#controlclassnames) or to any ancestor element.
```
```
https\://example.com
AND (and)+ Rule+ Group
First name (firstName)begins with (beginsWith)Stev⨯
OR (or)+ Rule+ Group⨯
Last name (lastName)=Vai⨯
Last name (lastName)=Vaughan⨯
The branch lines are colored red in the example above to stand out, but by default use the same color, width, and style as group borders. These variables can be overridden to customize branch lines:
* CSS
* SCSS
```
:root {
--rqb-branch-indent: var(--rqb-spacing);
--rqb-branch-width: var(--rqb-border-width);
--rqb-branch-color: var(--rqb-border-color);
--rqb-branch-radius: var(--rqb-border-radius);
--rqb-branch-style: var(--rqb-border-style);
}
```
```
$rqb-branch-indent: $rqb-spacing;
$rqb-branch-width: $rqb-border-width;
$rqb-branch-color: $rqb-border-color;
$rqb-branch-radius: $rqb-border-radius;
$rqb-branch-style: $rqb-border-style;
```
## Justified layout[](#justified-layout "Direct link to Justified layout")
For a "justified" layout, add the `queryBuilder-justified` class using the [`controlClassnames` prop](/docs/components/querybuilder.md#controlclassnames) or to any ancestor element.
Justified layout styles augment the default styles by pushing "+ Rule", "+ Group", clone, lock, and remove buttons to the right edge of their containers.
```
```
https\://example.com
AND (and)+ Rule+ Group
First name (firstName)begins with (beginsWith)Stev⨯
OR (or)+ Rule+ Group⨯
Last name (lastName)=Vai⨯
Last name (lastName)=Vaughan⨯
## Responsive layout[](#responsive-layout "Direct link to Responsive layout")
For a layout that adapts to narrow containers (e.g. mobile), add the `queryBuilder-responsive` class using the [`controlClassnames` prop](/docs/components/querybuilder.md#controlclassnames) or to any ancestor element.
Responsive layout styles augment the default styles so that rule and group header rows wrap onto multiple lines when they run out of horizontal space instead of overflowing. No media or container queries are involved, so the layout reflows based on the actual available width—even for deeply nested groups.
These styles are intentionally minimal and only lightly opinionated; think of them as a convenient starting point for responsive behavior rather than a canonical or prescribed approach. Override or replace them freely to suit your design.
```
```
https\://example.com
AND (and)+ Rule+ Group
First name (firstName)begins with (beginsWith)Stev⨯
OR (or)+ Rule+ Group⨯
Last name (lastName)=Vai⨯
Last name (lastName)=Vaughan⨯
## Drag-and-drop[](#drag-and-drop "Direct link to Drag-and-drop")
When [drag-and-drop is enabled](/docs/dnd.md), these variables control styles for dragged and hovered elements:
* CSS
* SCSS
```
:root {
--rqb-dnd-drop-indicator-color: rebeccapurple;
--rqb-dnd-drop-indicator-copy-color: #669933;
--rqb-dnd-drop-indicator-style: dashed;
--rqb-dnd-drop-indicator-width: 2px;
}
```
```
$rqb-dnd-drop-indicator-color: rebeccapurple;
$rqb-dnd-drop-indicator-copy-color: #669933;
$rqb-dnd-drop-indicator-style: dashed;
$rqb-dnd-drop-indicator-width: 2px;
// Deprecated variable names (still work)
// $rqb-dnd-hover-border-bottom-color: rebeccapurple;
// $rqb-dnd-hover-copy-border-bottom-color: #669933;
// $rqb-dnd-hover-border-bottom-style: dashed;
// $rqb-dnd-hover-border-bottom-width: 2px;
```
You can also assign styles to these classes:
* `dndDragging`: Assigned to the clone of the dragged element (the "ghost" that follows the mouse cursor)
* `dndOver`: Assigned to a drop target when the cursor hovers over it
* `dndCopy`: Assigned to a drop target when the cursor hovers over it while the "copy" modifier key is pressed (`Alt` on Windows/Linux, `⌥ Option` on macOS; see [Drag-and-drop § Cloning and grouping](/docs/dnd.md#cloning-and-grouping))
* `dndGroup`: Assigned to a drop target when the cursor hovers over it while the "group" modifier key is pressed (`Ctrl`; see [Drag-and-drop § Cloning and grouping](/docs/dnd.md#cloning-and-grouping))
---
# Adding and removing query properties
## Adding properties[](#adding-properties "Direct link to Adding properties")
To enhance a query object with additional properties, iterate through the `rules` array recursively. The [`transformQuery`](/docs/utils/misc.md#transformquery) utility function simplifies this process.
The example below (inspired by [issue #226](https://github.com/react-querybuilder/react-querybuilder/issues/226)) demonstrates adding the `inputType` property from the `fields` array to each rule in the query object.
```
import type { Field, RuleGroupType, RuleType } from 'react-querybuilder';
import { transformQuery } from 'react-querybuilder';
const fields: Field[] = [
{ name: 'description', label: 'Description', inputType: 'string' },
{ name: 'price', label: 'Price', inputType: 'number' },
];
const ruleProcessor: RuleProcessor = (r, { fieldData }): RuleType & { inputType?: string } => ({
...r,
inputType: fieldData?.inputType,
});
const result = transformQuery(query, { ruleProcessor });
```
Manual recursion
This example (taken directly from [issue #226](https://github.com/react-querybuilder/react-querybuilder/issues/226)) shows how to use manual recursion to achieve the same result as the `transformQuery` example above.
```
import type { Field, RuleGroupType, RuleType } from 'react-querybuilder';
const fields: Field[] = [
{ name: 'description', label: 'Description', inputType: 'string' },
{ name: 'price', label: 'Price', inputType: 'number' },
];
const processRule = (r: RuleType): RuleType & { inputType?: string } => ({
...r,
inputType: fields.find(f => f.name === r.field)?.inputType,
});
const processGroup = (rg: RuleGroupType): RuleGroupType => ({
...rg,
rules: rg.rules.map(r => {
if ('field' in r) {
return processRule(r);
}
return processGroup(r);
}),
});
const result = processGroup(query);
```
## Removing properties[](#removing-properties "Direct link to Removing properties")
To create a JSON string from a query object containing only specific properties, use the `replacer` parameter (second argument) of the [`JSON.stringify` function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).
```
const query: RuleGroupType = {
id: 'root',
combinator: 'and',
rules: [
{
field: 'firstName',
operator: '=',
value: 'Steve',
},
],
};
// This omits all properties except those specified in the replacer array:
console.log(JSON.stringify(query, ['rules', 'field', 'operator', 'value']));
// '{"rules":[{"field":"firstName","operator":"=","value":"Steve"}]}'
```
Alternatively, the `formatQuery` function provides a convenient method to generate a JSON string containing all query properties except `id` and `path`:
```
console.log(formatQuery(query, 'json_without_ids'));
// '{"combinator":"and","rules":[{"field":"firstName","operator":"=","value":"Steve"}]}'
```
---
# Arbitrary updates
Sometimes standard component actions don't meet specific requirements. React Query Builder provides tools to extend or replace the default behavior with custom implementations.
## Multiple action elements[](#multiple-action-elements "Direct link to Multiple action elements")
The default `addRuleAction` component always creates rules using the default configuration. However, you might need to provide multiple buttons that add rules with different pre-selected fields based on which button is clicked.
This example demonstrates a custom component that renders two buttons in place of the standard `addRuleAction`. Each button corresponds to a specific field. The click handler uses `props.schema.getQuery()` to retrieve the current query and `props.schema.dispatchQuery()` to update the query with the appropriate field selection.
## Custom query properties[](#custom-query-properties "Direct link to Custom query properties")
While the standard query structure works well, it may not contain all the information you need. You might require additional properties in the query hierarchy and want to manage these properties through custom controls within the query builder. This example adds a `caseSensitive` property to each rule, using a checkbox alongside the default value editor to toggle this setting.
This example also demonstrates how the `caseSensitive` property integrates with a custom [rule processor](/docs/utils/export.md#rule-processor) for `formatQuery`. When `caseSensitive` is false, the processor wraps the field with SQL's `LOWER` function and converts the value to lowercase before passing it to the default rule processor.
The example displays both the generated SQL query and the raw query object below the query builder interface.
> *Related: [Adding and removing query properties](/docs/tips/adding-removing-query-properties.md)*
---
# Async option list loading
To load option lists asynchronously for a value selector or editor, use the `useAsyncOptionList` hook imported from `"react-querybuilder/async"`.
This opt-in feature enables dynamic loading of options based on rule/group context, with intelligent caching for performance optimization.
tip
For more information about option list props, see [Working with option lists](/docs/tips/option-lists.md).
## Basic usage[](#basic-usage "Direct link to Basic usage")
1. Create a component that accepts `ValueSelectorProps` or `ValueEditorProps`.
2. Pass the props directly to `useAsyncOptionList` along with the async configuration options.
3. After any custom logic, pass the object returned from `useAsyncOptionList` as the props to a standard selector/editor component.
4. Assign the component in the [`controlElements` prop](/docs/components/querybuilder-controlelements.md).
```
import { type UseAsyncOptionListParams, useAsyncOptionList } from 'react-querybuilder/async';
const useAsyncOptionListParams: UseAsyncOptionListParams
= {
getCacheKey: 'field',
loadOptionList: async (value, { ruleOrGroup }) => {
const response = await fetch(`/api/operators?field=${ruleOrGroup.field}`);
return response.json();
},
};
// Step 1
const AsyncOperatorSelector = (props: ValueSelectorProps) => {
// Step 2
const asyncProps = useAsyncOptionList(props, useAsyncOptionListParams);
// Step 3
return handleOnChange(v)}
disabled={props.disabled}
renderInput={params => (
=> {
// Simulate network delay
await new Promise(resolve => setTimeout(resolve, 500));
// Filter based on input value if provided
if (value && value.length > 0) {
return words.filter(word => word.toLowerCase().includes(value.toLowerCase()));
}
// Otherwise return no results
return [];
};
const getCacheKey = ({ value }: ValueEditorProps) => value;
```
## Error handling[](#error-handling "Direct link to Error handling")
Async loading errors can be managed within your `loadOptionList` function or by checking the `errors` property on the object returned from `useAsyncOptionList`, which will contain an error message when the promise is rejected.
Internal error handling:
```
const loadOptionList = async (value, { ruleOrGroup }) => {
try {
const response = await fetch('/api/options');
if (!response.ok) throw new Error('Failed to load options');
return response.json();
} catch (error) {
// Log the error and return fallback options
console.error('Failed to load options:', error);
return [{ name: 'error', value: 'error', label: 'Error loading options' }];
}
};
```
Promise rejection detection:
```
const AsyncOperatorSelector = (props: ValueSelectorProps) => {
const asyncProps = useAsyncOptionList(props, useAsyncOptionListParams);
// If `errors` is truthy, the promise was rejected
if (asyncProps.errors) {
const fallbackOptions = [{ name: 'error', value: 'error', label: 'Error loading options' }];
return setQuery(q)}
controlElements={{
valueEditor: CustomValueEditor,
}}
/>
);
};
```
This pattern causes issues like input fields losing focus after each keystroke because `CustomValueEditor` is recreated on every `App` render. Instead, declare custom components outside the parent function:
App.jsx
```
const CustomValueEditor = props => {
// Custom logic here ...
return setQuery(q)}
controlElements={{
valueEditor: CustomValueEditor,
}}
/>
);
};
```
Another common mistake involves creating wrapper arrow functions in JSX. In this example, `CustomValueEditor` is correctly defined outside `App`, but assigning an arrow function that renders it (instead of the component itself) creates a new function component on every render:
App.jsx
```
const CustomValueEditor = props => {
// Custom logic here ...
return setQuery(q)}
controlElements={{
// Don't do this:
valueEditor: props =>
props.handleOnChange(d ? format(d, dateFormat) : null)}
/>
);
} else if (props.fieldData.datatype === 'dateRange') {
const [startDate, endDate] = props.value.split(',');
return (
{
const [s, e] = update;
props.handleOnChange(
[!s ? '' : format(s, dateFormat), !e ? '' : format(e, dateFormat)].join(',')
);
}}
/>
);
}
return (props.level === 0 ? false}
/>
```
---
# Managing fields
The [`fields`](/docs/components/querybuilder.md#fields) array forms the foundation of React Query Builder configuration, defining which data fields users can include in a query.
tip
For more information about option list props like `fields`, see [Working with option lists](/docs/tips/option-lists.md).
## Updating `fields` at runtime[](#updating-fields-at-runtime "Direct link to updating-fields-at-runtime")
The `fields` prop is fully reactive — when it changes, the query builder re-normalizes the field list and updates all selectors automatically. This means you can let users add, remove, or edit fields at runtime with standard React state:
```
import { useState } from 'react';
import { QueryBuilder } from 'react-querybuilder';
import type { Field, RuleGroupType } from 'react-querybuilder';
const initialFields: Field[] = [
{ name: 'firstName', label: 'First Name' },
{ name: 'lastName', label: 'Last Name' },
];
export function App() {
const [fields, setFields] = useState(initialFields);
const [query, setQuery] = useState({ combinator: 'and', rules: [] });
const addField = () =>
setFields(prev => [...prev, { name: 'email', label: 'Email', inputType: 'email' }]);
const removeField = (name: string) => setFields(prev => prev.filter(f => f.name !== name));
return (
<>
Add Email Field
removeField('email')}>Remove Email Field
setQuery(q)}
//
// ❌ Inline definition of an array that doesn't change over time.
fields={[
{ name: 'firstName', label: 'First Name' },
{ name: 'lastName', label: 'Last Name' },
]}
//
// This function is not defined inline in the JSX, but it does not have a stable
// reference since it's recreated on each render (see its declaration above).
getOperators={getOperators}
//
controlElements={{
// ❌ Component function is defined inline and will be recreated during each render.
// This can also cause bugs like "input loses focus after each keystroke."
actionElement: props => {props.label} ,
}}
/>
);
}
```
### "Good" example[](#good-example "Direct link to \"Good\" example")
Use these patterns to optimize `QueryBuilder` performance:
✓
```
// ✅ Fields array that never changes defined outside the component.
const fields: Field[] = [
{ name: 'firstName', label: 'First Name' },
{ name: 'lastName', label: 'Last Name' },
];
// ✅ Custom subcomponent defined outside the main component render function.
const MyActionElement = (props: ActionProps) => (
{props.label}
);
// ✅ Default query, which is only access once, defined outside the component.
const defaultQuery: RuleGroupType = { combinator: 'and', rules: [] };
function App() {
const { t } = useTranslation(); // (<-- third-party i18n library)
// ✅ `useState` parameter (the initial value of `query`) defined outside the component.
const [query, setQuery] = useState(defaultQuery);
// ✅ Function defined inside the component memoized with `useCallback`. Since `t`
// _probably_ has a stable reference, this function will rarely, if ever, be recreated.
const getOperators = useCallback((field: Field) => t(defaultOperators), [t]);
return (
`, a `renderBuilder` callback, and ``, and keeps the query in an immutable.js tree that must be converted before it can be saved. RQB renders a single element and stores the query as plain JSON.
Before (RAQB)
```
import { useCallback, useState } from 'react';
import type {
BuilderProps,
Config,
ImmutableTree,
JsonGroup,
} from '@react-awesome-query-builder/ui';
import { BasicConfig, Builder, Query, Utils as QbUtils } from '@react-awesome-query-builder/ui';
import '@react-awesome-query-builder/ui/css/styles.css';
const config: Config = {
...BasicConfig,
fields: {
price: { label: 'Price', type: 'number' },
color: {
label: 'Color',
type: 'select',
fieldSettings: {
listValues: [
{ value: 'yellow', title: 'Yellow' },
{ value: 'green', title: 'Green' },
],
},
},
},
settings: {
...BasicConfig.settings,
showNot: true,
showLock: true,
maxNesting: 3,
addRuleLabel: 'New rule',
},
};
const initialTree: JsonGroup = { id: QbUtils.uuid(), type: 'group' };
export const App = () => {
const [tree, setTree] = useState(() => QbUtils.loadTree(initialTree));
const onChange = useCallback((immutableTree: ImmutableTree) => {
setTree(immutableTree);
// Convert before saving — the state itself is an immutable.js tree
console.log(QbUtils.getTree(immutableTree));
}, []);
const renderBuilder = useCallback(
(props: BuilderProps) => (
),
[]
);
return (
<>
{QbUtils.sqlFormat(tree, config)}
);
};
```
After (RQB)
```
import { useState } from 'react';
import type { Field, RuleGroupType } from 'react-querybuilder';
import { formatQuery, QueryBuilder } from 'react-querybuilder';
import 'react-querybuilder/dist/query-builder.css';
const fields: Field[] = [
{ name: 'price', label: 'Price', inputType: 'number' },
{
name: 'color',
label: 'Color',
valueEditorType: 'select',
values: [
{ name: 'yellow', label: 'Yellow' },
{ name: 'green', label: 'Green' },
],
},
];
const initialQuery: RuleGroupType = { combinator: 'and', rules: [] };
export const App = () => {
// Already plain JSON — save it as-is
const [query, setQuery] = useState(initialQuery);
return (
<>
{formatQuery(query, 'sql')}
);
};
```
Notable differences:
* Configuration is spread across discrete props instead of one `Config` object, so there's no base config to spread (no `BasicConfig`) and nothing to keep in state alongside the query.
* `onQueryChange` receives the query object directly, so it can be passed straight to a `useState` setter and saved without conversion.
* There is no `renderBuilder` indirection or required wrapper markup. Use [`controlClassnames`](/docs/components/querybuilder.md#controlclassnames) and [`controlElements`](/docs/components/querybuilder.md#controlelements) to customize markup and styling.
* Export functions take the query object, not a tree plus a config.
### Settings[](#settings "Direct link to Settings")
RAQB's `config.settings` correspond to individual ``): Additional or overriding operator name mappings. Should match the `operatorMap` passed to `parseRAQB`.
* `includeHidden` (`boolean`): Include fields marked `hideForSelect`. Defaults to `false`.
* `onUnsupported` (`(info: RAQBUnsupportedInfo) => void`): Called for each construct that could not be fully translated.
## Converting queries[](#converting-queries "Direct link to Converting queries")
`parseRAQB` accepts RAQB's **plain-JSON** tree — the output of `Utils.getTree(immutableTree)` — or a JSON string of the same. Immutable.js trees are not accepted; passing one throws an error explaining the fix.
```
// In your RAQB app, save the plain JSON form:
const jsonTree = QbUtils.getTree(immutableTree);
```
```
import { parseRAQB } from '@react-querybuilder/migrate-raqb';
const query = parseRAQB(jsonTree);
```
Example
```
parseRAQB({
type: 'group',
properties: { conjunction: 'AND' },
children1: [
{
type: 'rule',
properties: { field: 'price', operator: 'greater', value: [10], valueSrc: ['value'] },
},
{
type: 'rule',
properties: { field: 'color', operator: 'select_any_in', value: [['yellow', 'green']] },
},
],
});
```
Result
```
{
"combinator": "and",
"rules": [
{ "field": "price", "operator": ">", "value": 10 },
{ "field": "color", "operator": "in", "value": "yellow,green" }
]
}
```
Both `children1` shapes are supported: the default array form and the keyed-object form produced when `children1AsArray` is `false`.
### Operator mapping[](#operator-mapping "Direct link to Operator mapping")
| RAQB | RQB |
| -------------------------------------------------------------- | --------------------------------------------------------------- |
| `equal` / `not_equal` | `=` / `!=` |
| `less` / `less_or_equal` | `<` / `<=` |
| `greater` / `greater_or_equal` | `>` / `>=` |
| `like` / `not_like` | `contains` / `doesNotContain` |
| `starts_with` / `ends_with` | `beginsWith` / `endsWith` |
| `between` / `not_between` | `between` / `notBetween` |
| `is_null` / `is_not_null` | `null` / `notNull` |
| `is_empty` / `is_not_empty` | `=` / `!=` with an empty string |
| `select_equals` / `select_not_equals` | `=` / `!=` |
| `select_any_in` / `select_not_any_in` | `in` / `notIn` |
| `multiselect_equals` / `multiselect_not_equals` | `=` / `!=` (array value kept) |
| `multiselect_contains` / `multiselect_not_contains` | `contains` / `doesNotContain` |
| `some` / `all` / `none` | Match modes `some` / `all` / `none` |
| `!group` counts `equal` / `greater_or_equal` / `less_or_equal` | Match modes `exactly` / `atLeast` / `atMost` with a `threshold` |
Add to or override this map with the `operatorMap` option.
### `parseRAQB` options[](#parseraqb-options "Direct link to parseraqb-options")
Beyond the standard [import configuration](/docs/utils/import.md#configuration) options (`fields`, `listsAsArrays`, `generateIDs`, `independentCombinators`, etc.), `parseRAQB` accepts:
* `operatorMap` (`Record`): Additional or overriding RAQB-to-RQB operator mappings, merged over the defaults.
* `functionMap` (`Record`): Additional or overriding RAQB-to-`expr` function name mappings, merged over the defaults.
* `funcArgOrder` (`Record`): Explicit argument order per RAQB function name. By default, argument order follows the key order of the serialized function object.
* `relativeDateTimes` (`boolean`): Convert RAQB's built-in date/time functions to relative date/time values instead of expressions. Defaults to `true`. See [Date and time functions](#date-and-time-functions).
* `onUnsupported` (`(info: RAQBUnsupportedInfo) => void`): Called for each construct that could not be converted.
As with other parsers, passing `fields` restricts the output to rules whose fields exist in the list.
## Functions and expressions[](#functions-and-expressions "Direct link to Functions and expressions")
RAQB's `valueSrc: "func"` operands convert to RQB [expressions](/docs/expr.md). Right-hand side functions become `valueSource: "expression"` with an expression object as the value; a function on the *left* side (`fieldSrc: "func"`) becomes the rule's `lhs` property.
Example
```
parseRAQB({
type: 'group',
properties: { conjunction: 'AND' },
children1: [
{
type: 'rule',
properties: {
field: 'name',
operator: 'equal',
valueSrc: ['func'],
value: [{ func: 'LOWER', args: { str: { value: 'Steve', valueSrc: 'value' } } }],
},
},
],
});
```
Result
```
{
"combinator": "and",
"rules": [
{
"field": "name",
"operator": "=",
"valueSource": "expression",
"value": { "kind": "func", "fn": "lower", "args": [{ "kind": "value", "value": "Steve" }] }
}
]
}
```
caution
Queries containing expressions require [`@react-querybuilder/expr`](/docs/expr.md) to render, validate, or serialize. Wrap your query builder in `QueryBuilderExpressions` and register the export processor as described in the [expressions documentation](/docs/expr.md). Without that package, expression values will not display or export correctly.
RAQB's `LOWER` and `UPPER` map to `expr`'s `lower` and `upper`, and `LINEAR_REGRESSION` is expanded to the equivalent arithmetic expression. Every other RAQB function—apart from the date/time functions described below—is passed through under its original name and reported to `onUnsupported`. To render or export those, either register matching function metadata with `@react-querybuilder/expr` or map them to existing functions with `functionMap`.
## Date and time functions[](#date-and-time-functions "Direct link to Date and time functions")
RAQB's built-in date/time functions don't really compute anything—they describe a date relative to "now". RQB represents that concept as a *value* rather than an expression, so `parseRAQB` converts them to [`@react-querybuilder/datetime`](/docs/datetime.md)'s relative date/time value shape (`{ mode: "relative", anchor, offset, unit }`), which every date/time rule processor serializes symbolically (e.g. `current_timestamp - interval '7 days'`).
| RAQB | RQB value |
| ----------------------------------------- | -------------------------------------------------- |
| `NOW()` | `{ anchor: 'now', offset: 0 }` |
| `TODAY()` / `START_OF_TODAY()` | `{ anchor: 'startOfDay', offset: 0 }` |
| `TRUNCATE_DATETIME(NOW(), dim)` | `{ anchor: 'startOf', offset: 0 }` |
| `RELATIVE_DATE(TIME)(date, op, val, dim)` | `{ anchor: , offset: ±val, unit: dim }` |
Example
```
parseRAQB({
type: 'group',
properties: { conjunction: 'AND' },
children1: [
{
type: 'rule',
properties: {
field: 'created',
operator: 'between',
valueSrc: ['func', 'func'],
value: [
{
func: 'RELATIVE_DATETIME',
args: { op: { value: 'minus' }, val: { value: 7 }, dim: { value: 'day' } },
},
{ func: 'NOW', args: {} },
],
},
},
],
});
```
Result
```
{
"combinator": "and",
"rules": [
{
"field": "created",
"operator": "between",
"value": [
{ "mode": "relative", "anchor": "now", "offset": -7, "unit": "day" },
{ "mode": "relative", "anchor": "now", "offset": 0, "unit": "day" }
]
}
]
}
```
With `@react-querybuilder/datetime`'s SQL rule processor, that query exports as `"created" between current_timestamp - interval '7 days' and current_timestamp`.
A few RAQB calls fall outside what relative values can express, and are converted to expressions instead (and reported to `onUnsupported`):
* A `"second"` dimension. RQB's smallest relative unit is `minute`.
* Truncation to `hour`, `minute`, or `second`. RQB truncates only to day, week, month, or year.
* Truncation applied *after* an offset, e.g. `TRUNCATE_DATETIME(RELATIVE_DATETIME(NOW(), 'minus', 3, 'day'), 'month')`. RQB applies the anchor first and the offset second, so only the reverse nesting is representable.
Pass `relativeDateTimes: false` to convert date/time functions to expressions like any other function.
## Unsupported constructs[](#unsupported-constructs "Direct link to Unsupported constructs")
`parseRAQB` never throws on unrecognized content (aside from immutable.js input). Anything it can't convert is skipped, and a partial query is always returned. Use `onUnsupported` to log or surface what was dropped.
```
const unsupported: RAQBUnsupportedInfo[] = [];
const query = parseRAQB(jsonTree, {
onUnsupported: info => unsupported.push(info),
});
```
Reported constructs include:
* **`switch_group` / `case_group`** (RAQB's ternary mode). RQB has no equivalent; consider [`@react-querybuilder/rules-engine`](/docs/rules-engine.md) for conditional logic.
* **`proximity`** and its `operatorOptions`, which have no RQB counterpart.
* **`!group` strict-inequality count operators** (`less`, `greater`), since RQB match modes cover only `exactly`, `atLeast`, and `atMost`.
* **Functions with no `@react-querybuilder/expr` equivalent**, which pass through by name.
## Putting it together[](#putting-it-together "Direct link to Putting it together")
```
import { QueryBuilder } from 'react-querybuilder';
import { parseRAQB, parseRAQBFields } from '@react-querybuilder/migrate-raqb';
import raqbConfig from './raqbConfig';
import savedTree from './savedQuery.json';
const fields = parseRAQBFields(raqbConfig);
const defaultQuery = parseRAQB(savedTree, { fields });
export const App = () => ` elements, which can contain either `` elements directly or ` ` elements with nested `` lists.
## An incorrect assumption[](#an-incorrect-assumption "Direct link to An incorrect assumption")
You may have found this page after seeing a TypeScript error message similar to this:
```
Property 'name' does not exist on type 'FullOption | OptionGroup>'.
Property 'name' does not exist on type 'OptionGroup>'. ts(2339)
```
This typically occurs when treating option list elements as guaranteed `Option` types. For example, mapping through the list to access the `name` property:
```
const ListAllOptionNames = (props: ValueSelectorProps) => {
return {props.options.map(opt => opt.name).join(', ')}
;
// ^^^^ error
};
```
While it seems logical that an option list passed to `QueryBuilder` as `Option[]` would remain `Option[]` in subcomponents, React Query Builder's type generics only infer the option types within the list, not the list structure itself.
tip
All options in subcomponent props are guaranteed to include both `name` and `value` properties, even if the original `QueryBuilder` prop omitted one of them.
As an example, consider this `fields` array:
```
const fields: Field[] = [
{ name: 'firstName', label: 'First Name' },
{ name: 'lastName', label: 'Last Name' },
];
```
When this array is assigned to the [`fields` prop](/docs/components/querybuilder.md#fields), the `fieldSelector` component will receive the same array but with each option object augmented with a `value` property equivalent to the original `name`:
```
const MyFieldSelector = (props: FieldSelectorProps) => {
console.log(props.options); // =>
// [
// { name: 'firstName', value: 'firstName', label: 'First Name' },
// { name: 'lastName', value: 'lastName', label: 'Last Name' }],
// ]
return {(props.options as Option[]).map(opt => opt.name).join(', ')}
;
// ^^^^^^^^^^^ avoids TypeScript error; may have issues during execution
};
```
info
All [default option lists](/docs/utils/misc.md#defaults) (`defaultCombinators`, `defaultOperators`, etc.) are type `Option[]`.
A better solution uses the [`isOptionGroupArray`](#isoptiongrouparray) type guard to determine the option list type. This approach avoids the deception of type casting while enabling different behaviors for `Option[]` versus `OptionGroup[]` arrays.
```
const MyComponent(props: ValueSelectorProps) => {
if (isOptionGroupArray(props.options)) {
return {props.options.flatMap(og => og.options).map(opt => opt.name).join(', ')}
;
}
return {(props.options).map(opt => opt.name).join(', ')}
;
};
```
## Utilities[](#utilities "Direct link to Utilities")
Several utility functions simplify working with option list props without requiring type guards or `as` casting.
### `getOption`[](#getoption "Direct link to getoption")
```
function getOption(arr: OptionList, identifier: string): Option;
```
Retrieves the complete option object from an option list using the given identifier (`name` or `value`), working with both `Option[]` and `OptionGroup[]` formats.
#### Examples[](#examples "Direct link to Examples")
```
getOption(
[
{ name: 'firstName', label: 'First Name' },
{ name: 'lastName', label: 'Last Name' },
],
'lastName'
);
// => { name: 'lastName', label: 'Last Name' }
getOption(
[
{ label: 'First', options: [{ name: 'firstName', label: 'First Name' }] },
{ label: 'Last', options: [{ name: 'lastName', label: 'Last Name' }] },
],
'lastName'
);
// => { name: 'lastName', label: 'Last Name' }
```
### `getFirstOption`[](#getfirstoption "Direct link to getfirstoption")
```
function getFirstOption(arr: OptionList): Option;
```
Returns the identifier value (`name` or `value`) of the first `Option` in the list, supporting both `Option[]` and `OptionGroup[]` formats.
`QueryBuilder` uses this function to establish default values for option lists in new rules and groups when no other default determination method is available.
#### Examples[](#examples-1 "Direct link to Examples")
```
getFirstOption([
{ name: 'firstName', label: 'First Name' },
{ name: 'lastName', label: 'Last Name' },
]);
// => 'firstName'
getFirstOption([
{ label: 'First', options: [{ name: 'firstName', label: 'First Name' }] },
{ label: 'Last', options: [{ name: 'lastName', label: 'Last Name' }] },
]);
// => 'firstName'
```
### `toOptions`[](#tooptions "Direct link to tooptions")
```
function toOptions(arr: OptionList): ReactElement;
```
Creates `` elements for `Option` arrays or ` ` elements for `OptionGroup` arrays. Designed for use as the `children` prop of `` elements, as implemented in [`ValueSelector`](/docs/components/valueselector.md).
info
Some of the [compatibility packages](/docs/compat.md) implement their own `toOptions` method that generates "option" elements appropriate for their respective style library.
#### Usage[](#usage "Direct link to Usage")
```
const MyComponent(props: ValueSelectorProps) => {
return (
props.handleOnChange(e.target.value)}>
{toOptions(props.options)}
)
}
```
Examples
#### `Option[]` example[](#option-example "Direct link to option-example")
```
toOptions([
{ value: 'firstName', label: 'First Name' },
{ value: 'lastName', label: 'Last Name' },
]);
// yields (approximately):
[
First Name
,
Last Name
,
];
```
#### `OptionGroup[]` example[](#optiongroup-example "Direct link to optiongroup-example")
```
toOptions([
{ label: 'First', options: [{ value: 'firstName', label: 'First Name' }] },
{ label: 'Last', options: [{ value: 'lastName', label: 'Last Name' }] },
]);
// yields (approximately):
[
First Name
,
Last Name
,
];
```
### `toFlatOptionArray`[](#toflatoptionarray "Direct link to toflatoptionarray")
```
function toFlatOptionArray(arr: any): boolean;
```
Converts `OptionGroup` arrays to flattened `Option` arrays using [`Array.prototype.flatMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flatMap) when grouped structures are unsuitable, while leaving `Option` arrays unchanged. The result is deduplicated using [`uniqByIdentifier`](#uniqbyidentifier).
### `isOptionGroupArray`[](#isoptiongrouparray "Direct link to isoptiongrouparray")
```
function isOptionGroupArray(arr: any): boolean;
```
A type guard that distinguishes between the two array types in `OptionList`. When this returns `true`, the array is `OptionGroup[]`, meaning actual options are nested within each group's `options` property.
Examples
```
isOptionGroupArray([
{ value: 'firstName', label: 'First Name' },
{ value: 'lastName', label: 'Last Name' },
]);
// => false
isOptionGroupArray([
{ label: 'First', options: [{ value: 'firstName', label: 'First Name' }] },
{ label: 'Last', options: [{ value: 'lastName', label: 'Last Name' }] },
]);
// => true
```
### `uniqOptList`[](#uniqoptlist "Direct link to uniqoptlist")
```
function uniqOptList(arr: any): boolean;
```
Removes duplicate options from an `OptionList` by comparing identifier properties (`name` or `value`), working with both `Option[]` and `OptionGroup[]` formats.
### `uniqByIdentifier`[](#uniqbyidentifier "Direct link to uniqbyidentifier")
```
function uniqByIdentifier(arr: any): boolean;
```
Removes duplicate options from an `Option` array by comparing identifier properties (`name` or `value`).
## String option lists[](#string-option-lists "Direct link to String option lists")
Option list props also accept `string[]`. Each string becomes an option with `name`, `value`, and `label` all set to that string.
```
// These are equivalent:
[]`** - Array of objects with custom labels (e.g., `[{ name: 'all', label: 'Every' }]`)
```
const fields: Field[] = [
{
name: 'nestedStringArray',
label: 'Nested String Array',
// Enable all match modes with default labels
matchModes: true,
},
{
name: 'nestedNumberArray',
label: 'Nested Number Array',
// Enable specific match modes with custom labels
matchModes: [
{ name: 'all', label: 'Every' },
{ name: 'none', label: 'Not one' },
{ name: 'some', label: 'Several' },
],
},
{
name: 'nestedObjectArray',
label: 'Nested Object Array',
// Enable specific match modes with default labels
matchModes: ['all', 'none', 'some'],
// Define properties of objects in the nested array
subproperties: [
{ name: 'firstName', label: 'First Name' },
{ name: 'lastName', label: 'Last Name' },
],
},
];
```
### Dynamic match mode configuration[](#dynamic-match-mode-configuration "Direct link to Dynamic match mode configuration")
Configure match modes dynamically using the `getMatchModes` prop at the query builder level. This function executes for each field, enabling conditional match mode configuration based on field properties:
```
const getMatchModes = (field: string, misc: { fieldData: Field }) => {
// Return true to enable all match modes for any field
if (field === 'flexibleArray') return true;
// Return specific match modes based on field type
if (misc.fieldData.datatype === 'array') {
return ['all', 'some', 'none'];
}
// Return false or undefined to disable subqueries for this field
return false;
};
);
```
That's the whole setup. `QueryBuilderHistory` records changes for descendant query builders and defaults their [`showUndoRedo`](/docs/components/querybuilder.md#showundoredo) prop to `true`, which displays undo/redo controls at the end of the outermost group's header. Pass `showUndoRedo={false}` to a particular `QueryBuilder`, or to `QueryBuilderHistory` itself, to opt out while still recording history.
tip
Unlike most undo/redo recipes, this works in [uncontrolled mode](/docs/components/querybuilder.md#defaultquery)—you don't need to lift the query into your own state.
## How it works[](#how-it-works "Direct link to How it works")
Every query change—no matter which button, editor, or drag-and-drop interaction caused it—flows through a single action in React Query Builder's internal Redux store. The history recorder listens for that action, so recording requires no instrumentation of individual controls.
Because query updates use [Immer](https://immerjs.github.io/immer/), snapshots share structure with one another: an undo entry is a reference to a previous query object, not a deep copy, so keeping many of them is inexpensive. Snapshots also retain rule `id`s, which means undo preserves React keys and drag-and-drop state.
## Options[](#options "Direct link to Options")
Both options can be set on `QueryBuilderHistory`:
```
```
### `maxHistory`[](#maxhistory "Direct link to maxhistory")
`number` (default `50`)
Maximum number of undo steps to retain. Older entries are discarded.
### `coalesceMs`[](#coalescems "Direct link to coalescems")
`number` (default `500`)
Consecutive changes to the same property of the same rule within this many milliseconds are merged into a single undo step. Typing `hello` into a value editor therefore produces one undo entry that restores the original value, rather than five entries that remove one character at a time.
Set to `0` to record every change separately.
Structural changes—adding, removing, moving, or reordering rules and groups—never merge with each other, so each one is always its own undo step.
note
Coalescing relies on the structural sharing that Immer guarantees: nodes that didn't change keep their identity. If your application rebuilds the query wholesale between changes—deep-cloning it, round-tripping it through JSON, or re-parsing it from a string—then no two consecutive queries share any identity and every change becomes its own history entry. Undo/redo still works correctly; it's just less granular.
## Custom controls[](#custom-controls "Direct link to Custom controls")
`useQueryBuilderHistory` gives you the same controls that power the default buttons. It takes a query builder's [`qbId`](/docs/components/querybuilder.md#qbid) and can be used anywhere—including *outside* the query builder's component tree, which is what makes external toolbars possible.
```
import { QueryBuilder } from 'react-querybuilder';
import { QueryBuilderHistory, useQueryBuilderHistory } from 'react-querybuilder/history';
const Toolbar = ({ qbId }: { qbId: string }) => {
const { undo, redo, clear, canUndo, canRedo, past, future } = useQueryBuilderHistory(qbId);
return (
Undo
Redo
Clear history
{past.length} undo / {future.length} redo
);
};
const App = () => (
);
```
Note the explicit `qbId` on both components. Without it, the query builder generates an identifier internally that outside code has no way to discover.
### `useQueryBuilderHistory`[](#usequerybuilderhistory "Direct link to usequerybuilderhistory")
```
useQueryBuilderHistory(qbId: string, options?: { maxHistory?: number; coalesceMs?: number })
```
| Property | Type | Description |
| --------- | -------------------- | ------------------------------------------------------------- |
| `undo` | `() => void` | Restores the previous query. No-op when `canUndo` is `false`. |
| `redo` | `() => void` | Restores the most recently undone query. |
| `clear` | `() => void` | Discards all history without changing the current query. |
| `canUndo` | `boolean` | Whether there is anything to undo. |
| `canRedo` | `boolean` | Whether there is anything to redo. |
| `past` | `RuleGroupTypeAny[]` | Previous queries, oldest first. |
| `future` | `RuleGroupTypeAny[]` | Undone queries, newest first. |
Options passed here override those from the nearest `QueryBuilderHistory` ancestor.
info
Rendering this hook is what opts a query builder in to history recording. A query builder that neither uses the hook nor renders undo/redo controls retains no history at all, which is what keeps the feature free for everyone else.
## Keyboard shortcuts[](#keyboard-shortcuts "Direct link to Keyboard shortcuts")
Keyboard shortcuts aren't built in, because a library-level listener would hijack the browser's native text undo inside the query builder's own inputs and could conflict with your application's shortcuts. Wiring them up yourself is straightforward:
```
import { useEffect } from 'react';
import { useQueryBuilderHistory } from 'react-querybuilder/history';
const useUndoRedoShortcuts = (qbId: string) => {
const { undo, redo } = useQueryBuilderHistory(qbId);
useEffect(() => {
const onKeyDown = (event: KeyboardEvent) => {
if (!(event.metaKey || event.ctrlKey) || event.key.toLowerCase() !== 'z') return;
// Leave text inputs alone so native undo keeps working while editing a value
const target = event.target as HTMLElement | null;
if (target?.tagName === 'INPUT' || target?.tagName === 'TEXTAREA') return;
event.preventDefault();
if (event.shiftKey) {
redo();
} else {
undo();
}
};
document.addEventListener('keydown', onKeyDown);
return () => document.removeEventListener('keydown', onKeyDown);
}, [redo, undo]);
};
```
## Multiple query builders[](#multiple-query-builders "Direct link to Multiple query builders")
Each query builder has its own independent history, keyed by `qbId`. Undoing in one has no effect on any other.
## History lifetime[](#history-lifetime "Direct link to History lifetime")
History belongs to the query builder, not to whichever component displays it. Several consumers can share one `qbId`—the built-in undo/redo buttons alongside an external toolbar, for example—and one of them unmounting leaves the history intact for the rest.
When the last query builder using a given `qbId` unmounts, both its query and its history are discarded. To preserve them—so that remounting a query builder with the same `qbId` resumes where it left off—use [`preserveQueryStateOnUnmount`](/docs/components/querybuilder.md#preservequerystateonunmount), which retains the history along with the query.
## Alternative: controlled mode[](#alternative-controlled-mode "Direct link to Alternative: controlled mode")
If your application already keeps the query in its own state, you can implement undo/redo without this entry point by maintaining `past`/`present`/`future` stacks and snapshotting the previous query on each `onQueryChange`. Because query update functions return the *same* object reference when an operation is a no-op, you can skip recording those by comparing references.
This approach requires [controlled mode](/docs/components/querybuilder.md#query) and doesn't benefit from coalescing, so `QueryBuilderHistory` is generally the better option unless you have lifted the query into your own state for other reasons.
---
# TypeScript reference
Here are the key [TypeScript](https://www.typescriptlang.org/) types and interfaces used throughout React Query Builder. Even if you're using JavaScript, this reference helps you understand the expected shape of props and function parameters.
note
Some definitions below have been simplified from their actual implementations for legibility and ease of comprehension.
The **[API documentation](/api)** is generated from source code and provides complete type definitions with repository links for detailed reference.
## Fields[](#fields "Direct link to Fields")
```
interface Field {
id?: string; // The field identifier (if not provided, `name` will be used)
name: string; // The field name (REQUIRED)
label: string; // The field label (REQUIRED)
operators?: OptionList[]; // Array of operators (if not provided, `getOperators()` will be used)
valueEditorType?: ValueEditorType; // Value editor type for this field (if not provided, `getValueEditorType()` will be used)
inputType?: string | null; // @type attribute for the ;
getOperators?: (
field: string,
misc: { fieldData: FullField }
) => FlexibleOptionList | null;
fallbackExpression?: string;
paramPrefix?: string;
paramsKeepPrefix?: boolean;
numberedParams?: boolean;
parseNumbers?: ParseNumberMethod;
placeholderFieldName?: string;
placeholderOperatorName?: string;
concatOperator?: string;
preset?: SQLPreset;
context?: Record;
}
type RuleProcessor = (rule: RuleType, options?: ValueProcessorOptions) => any;
type ValueProcessor = (field: string, operator: string, value: any) => string;
interface ValueProcessorOptions extends FormatQueryOptions {
escapeQuotes?: boolean;
fieldData?: Field;
fieldParamNames?: Record;
getNextNamedParam?: (field: string) => string;
wrapValueWith?: [string, string];
}
interface ParameterizedSQL {
sql: string;
params: any[];
}
interface ParameterizedNamedSQL {
sql: string;
params: { [p: string]: any };
}
type ParseNumberMethod = boolean | 'enhanced' | 'native' | 'strict';
```
## Import[](#import "Direct link to Import")
```
interface ParserCommonOptions {
fields?: OptionList[] | Record;
getValueSources?: (field: string, operator: string) => ValueSources;
listsAsArrays?: boolean;
independentCombinators?: boolean;
}
interface ParseSQLOptions extends ParserCommonOptions {
paramPrefix?: string;
params?: any[] | Record;
}
interface ParseCELOptions extends ParserCommonOptions {
customExpressionHandler?: (expr: CELExpression) => RuleType | RuleGroupType | null;
}
type ParseSpELOptions = ParserCommonOptions;
type ParseJsonLogicOptions = ParserCommonOptions;
interface ParseMongoDbOptions extends ParserCommonOptions {
preventOperatorNegation?: boolean;
additionalOperators?: Record<
string,
(operator: string, value: any, otherOptions: ParserCommonOptions) => RuleType | RuleGroupType
>;
}
```
## Validation[](#validation "Direct link to Validation")
```
interface ValidationResult {
valid: boolean;
reasons?: any[];
}
interface ValidationMap {
[id: string]: boolean | ValidationResult;
}
type QueryValidator = (query: RuleGroupTypeAny) => boolean | ValidationMap;
type RuleValidator = (rule: RuleType) => boolean | ValidationResult;
```
## Option lists[](#option-lists "Direct link to Option lists")
*As of version 7, options and lists can use `name` **or** `value` as the item identifier. Both `name` and `value` are passed down to subcomponents, so `name` is available even if `value` is used in props and vice versa. `name` is used in the documentation for brevity and backwards compatibility. [Click here for more information](/docs/tips/option-lists.md).*
```
interface Option {
name: string;
label: string;
[x: string]: any;
}
interface OptionGroup {
label: string;
options: Option[];
}
type OptionList = Option[] | OptionGroup[];
interface Combinator extends Option {
className?: Classname; // Assigned to groups where this combinator is selected
}
interface Operator extends Option {
arity?: number | 'unary' | 'binary' | 'ternary';
className?: Classname; // Assigned to rules where this operator is selected
}
```
## Value editor[](#value-editor "Direct link to Value editor")
See [`ValueEditor` component documentation here](/docs/components/valueeditor.md).
```
type ValueEditorType =
| 'text'
| 'select'
| 'checkbox'
| 'radio'
| 'textarea'
| 'multiselect'
| 'date'
| 'datetime-local'
| 'time'
| null;
type ValueSource = 'value' | 'field';
type ValueSources = ['value'] | ['value', 'field'] | ['field', 'value'] | ['field'];
```
## Miscellaneous[](#miscellaneous "Direct link to Miscellaneous")
```
interface Schema {
qbId: string;
fields: OptionList;
fieldMap: Record;
classNames: Classnames;
combinators: OptionList;
controls: Controls;
createRule(): RuleType;
createRuleGroup(): RuleGroupTypeAny;
dispatchQuery(query: RuleGroupTypeAny): void;
getQuery(): RuleGroupTypeAny | undefined;
getOperators(field: string): OptionList;
getValueEditorType(field: string, operator: string): ValueEditorType;
getValueEditorSeparator(field: string, operator: string): ReactNode;
getValueSources(field: string, operator: string): ValueSources;
getInputType(field: string, operator: string): string | null;
getValues(field: string, operator: string): OptionList;
getRuleClassname(rule: RuleType): Classname;
getRuleGroupClassname(ruleGroup: RuleGroupTypeAny): Classname;
showCombinatorsBetweenRules: boolean;
showNotToggle: boolean;
showShiftActions: boolean;
showCloneButtons: boolean;
showLockButtons: boolean;
autoSelectField: boolean;
autoSelectOperator: boolean;
addRuleToNewGroups: boolean;
enableDragAndDrop: boolean;
validationMap: ValidationMap;
independentCombinators: boolean;
listsAsArrays: boolean;
parseNumbers: ParseNumbersMethod;
disabledPaths: Path[];
}
interface QueryActions {
onGroupAdd(group: RuleGroupTypeAny, parentPath: Path, context?: any): void;
onGroupRemove(path: Path): void;
onPropChange(
prop: Exclude,
value: any,
path: Path
): void;
onRuleAdd(rule: RuleType, parentPath: Path, context?: any): void;
onRuleRemove(path: Path): void;
moveRule(oldPath: Path, newPath: Path, clone?: boolean): void;
}
```
---
# Export
> *Refer to the [TypeScript reference](/docs/typescript.md) page for information about the types and interfaces referenced below.*
Use the `formatQuery` function to export queries in various formats. The function has this signature:
```
function formatQuery(
query: RuleGroupTypeAny,
options?: ExportFormat | FormatQueryOptions
): string | ParameterizedSQL | ParameterizedNamedSQL | RQBJsonLogic | Record;
```
`formatQuery` converts query objects to these formats:
* Formatted `JSON.stringify` result
* Unformatted `JSON.stringify` result with all `id` and `path` properties removed
* SQL `WHERE` clause
* Parameterized with anonymous parameters
* Parameterized with named parameters
* ORM query objects for Drizzle, Prisma, Sequelize, and TanStack DB
* MongoDB query object
* ~~MongoDB query object as string~~ [*(deprecated)*](#mongodb)
* Common Expression Language (CEL)
* Spring Expression Language (SpEL)
* JsonLogic
* ElasticSearch
* JSONata
* LDAP
* Natural language
The following sections use this example `query`:
```
const query: RuleGroupType = {
id: 'root',
combinator: 'and',
not: false,
rules: [
{
id: 'rule1',
field: 'firstName',
operator: '=',
value: 'Steve',
},
{
id: 'rule2',
field: 'lastName',
operator: '=',
value: 'Vai',
},
],
};
```
tip
For best results, use [default combinators and operators](/docs/utils/misc.md#defaults) or map custom ones to defaults with [`transformQuery`](/docs/utils/misc.md#transformquery).
More information...
`formatQuery` accepts `RuleGroupTypeAny` queries but only guarantees correct processing of `DefaultRuleGroupTypeAny` queries.
All query `combinator` and `operator` properties must match [`defaultCombinators` or `defaultOperators`](/docs/utils/misc.md#defaults) names (case-insensitive). Use [`transformQuery`](/docs/utils/misc.md#transformquery) to map custom names to defaults before calling `formatQuery`.
For example, replacing the default "between" operator with `{ name: "b/w", label: "b/w" }` creates rules with `operator: "b/w"`. For this query:
```
{
"combinator": "and",
"rules": [{ "field": "someNumber", "operator": "b/w", "value": "12,14" }]
}
```
Transform it using `transformQuery` with `operatorMap`:
```
const newQuery = transformQuery(query, { operatorMap: { 'b/w': 'between' } });
/*
{
"combinator": "and",
"rules": [{ "field": "someNumber", "operator": "between", "value": "12,14" }]
}
*/
```
The `newQuery` is ready for `formatQuery`, including special "between" operator handling.
## Basic usage[](#basic-usage "Direct link to Basic usage")
### JSON[](#json "Direct link to JSON")
Export the internal query representation (from `onQueryChange` callback) as formatted JSON:
```
formatQuery(query);
// or
formatQuery(query, 'json');
```
Output is multi-line JSON with 2-space indentation:
```
`{
"id": "root",
"combinator": "and",
"not": false,
"rules": [
{
"id": "rule1",
"field": "firstName",
"value": "Steve",
"operator": "="
},
{
"id": "rule2",
"field": "lastName",
"value": "Vai",
"operator": "="
}
]
}`;
```
### JSON without IDs[](#json-without-ids "Direct link to JSON without IDs")
Export unformatted (single-line) JSON without `id` or `path` attributes using "json\_without\_ids". This format is useful for persistent storage:
```
formatQuery(query, 'json_without_ids');
```
Output (string):
```
{"combinator":"and","not":false,"rules":[{"field":"firstName","value":"Steve","operator":"="},{"field":"lastName","value":"Vai","operator":"="}]}
```
### SQL[](#sql "Direct link to SQL")
Export SQL `WHERE` clauses using the "sql" format. This format is compatible with major RDBMS engines, though some cases require [configuration](#configuration). See [presets](#presets) for compatibility details.
```
formatQuery(query, 'sql');
```
Output (string):
```
(firstName = 'Steve' and lastName = 'Vai')
```
#### Parameterized SQL[](#parameterized-sql "Direct link to Parameterized SQL")
Export SQL with bind variables instead of inline values using the "parameterized" format. This returns an object with `sql` and `params` properties:
```
formatQuery(query, 'parameterized');
```
Output (JSON object):
```
{
"sql": "(firstName = ? and lastName = ?)",
"params": ["Steve", "Vai"]
}
```
#### Named parameters[](#named-parameters "Direct link to Named parameters")
When anonymous parameters aren't suitable, use "parameterized\_named" to name parameters based on field names. This is similar to "parameterized" but `params` is an object instead of an array:
```
formatQuery(query, 'parameterized_named');
```
Output (JSON object):
```
{
"sql": "(firstName = :firstName_1 and lastName = :lastName_1)",
"params": {
"firstName_1": "Steve",
"lastName_1": "Vai"
}
}
```
See also: [`paramPrefix`](#parameter-prefix) and [generating parameter names](#generating-parameter-names).
### ORMs[](#orms "Direct link to ORMs")
#### Prisma ORM[](#prisma-orm "Direct link to Prisma ORM")
Generate objects for Prisma ORM `where` properties using the "prisma" format:
> *Note: Prisma does not support field-to-field comparisons, so rules with `valueSource: "field"` will always be invalid.*
```
const where = formatQuery(query, 'prisma');
console.log(where);
// { AND: [{ firstName: 'Steve' }, { lastName: 'Vai' }] }
const users = await prisma.users.findMany({ where });
```
#### Drizzle ORM[](#drizzle-orm "Direct link to Drizzle ORM")
##### Relational Queries API[](#relational-queries-api "Direct link to Relational Queries API")
Generate functions for Drizzle's [relational queries API](https://orm.drizzle.team/docs/rqb) `where` property:
```
const where = formatQuery(query, 'drizzle');
// typeof where === 'function'
// where.length === 2
const results = db.query.users.findMany({ where });
```
##### Query Builder API[](#query-builder-api "Direct link to Query Builder API")
For Drizzle's [query builder API](https://orm.drizzle.team/docs/select), pass table definition and operators to the `formatQuery`-generated function:
```
import { getOperators } from 'drizzle-orm';
const whereFn = formatQuery(query, 'drizzle');
const whereObj = whereFn(table, getOperators());
const query = db.select().from(table).where(whereObj);
```
tip
Query builder API objects work with other Drizzle operators, letting you add conditions not in the original query:
```
import { and, ne, getOperators } from 'drizzle-orm';
// Conditions from the React Query Builder query object:
const whereFn = formatQuery(query, 'drizzle');
const whereObj = whereFn(table, getOperators());
// All conditions from the original query object _and_ `id != 123`:
const augmentedWhere = and(whereObj, ne(table.id, 123));
const query = db.select().from(table).where(augmentedWhere);
```
`@react-querybuilder/drizzle` *(deprecated)*
The [`@react-querybuilder/drizzle`](https://npmjs.com/package/@react-querybuilder/drizzle) package previously provided `generateDrizzleRuleGroupProcessor` and `generateDrizzleRuleProcessor` for integration with Drizzle's [query builder API](https://orm.drizzle.team/docs/select). This package is now deprecated.
To achieve the same result, inline the following functions in your project:
```
import type { RuleGroupProcessor, RuleProcessor } from '@react-querybuilder/core';
import {
defaultRuleGroupProcessorDrizzle,
defaultRuleProcessorDrizzle,
} from '@react-querybuilder/core';
import type { Column, SQL, Table } from 'drizzle-orm';
import * as drizzleOperators from 'drizzle-orm';
import { getOperators } from 'drizzle-orm';
export const generateDrizzleRuleGroupProcessor =
(columns: Record | Table): RuleGroupProcessor =>
(ruleGroup, options) =>
defaultRuleGroupProcessorDrizzle(ruleGroup, options)(
columns as Record,
getOperators()
);
export const generateDrizzleRuleProcessor =
(table: Table | Record): RuleProcessor =>
(rule, options) =>
defaultRuleProcessorDrizzle(rule, { ...options, context: { table, drizzleOperators } });
```
Usage:
```
import { sqliteTable, text } from 'drizzle-orm/sqlite-core';
import { formatQuery } from 'react-querybuilder';
const db = drizzle(process.env.DB_FILE_NAME!);
const table = sqliteTable('musicians', {
firstName: text(),
lastName: text(),
});
const ruleGroupProcessor = generateDrizzleRuleGroupProcessor(table);
// Tip: `format` is not required when `ruleGroupProcessor` is provided
const where = formatQuery(query, { ruleGroupProcessor });
const query = db.select().from(table).where(where);
console.log(query.toSQL());
// {
// sql: 'select "firstName", "lastName" from "musicians" where ("musicians"."firstName" = ? and "musicians"."lastName" = ?)',
// params: ['Steve', 'Vai']
// }
console.log(query.all());
// [{ firstName: 'Steve', lastName: 'Vai' }]
```
#### Sequelize[](#sequelize "Direct link to Sequelize")
Generate objects for Sequelize `findAll` `where` properties using the "sequelize" format. Requirements:
* Sequelize uses `Symbol`s for operator keys, so they must be provided through the `context` option as `sequelizeOperators` (see example below).
* If any rules have `valueSource: "field"`, then the Sequelize `col` function must be provided as `sequelizeCol`.
* If any rules have `valueSource: "field"` and use one of the `doesNot*` operators, then the Sequelize `fn` function must be provided as `sequelizeFn`.
```
import { col, fn, Op } from 'sequelize';
const where = formatQuery(query, {
format: 'sequelize',
context: { sequelizeOperators: Op, sequelizeCol: col, sequelizeFn: fn },
});
const users = await Users.findAll({ where });
```
#### TanStack DB[](#tanstack-db "Direct link to TanStack DB")
Generate a `WhereCallback` for [TanStack DB](https://tanstack.com/db)'s `.where()` method using the "tanstack\_db" format. The processor does not import any executable code from `@tanstack/db` — operators are passed in through the `context` option.
Pass the full `@tanstack/db` module or individual operators as `tanStackDbOperators`:
```
import * as tsdb from '@tanstack/db';
const where = formatQuery(query, {
format: 'tanstack_db',
context: { tanStackDbOperators: tsdb },
});
const results = useLiveQuery(q => q.from({ users: usersCollection }).where(where));
```
Or with cherry-picked operators:
```
import { eq, gt, gte, lt, lte, like, inArray, isNull, not, and, or } from '@tanstack/db';
const where = formatQuery(query, {
format: 'tanstack_db',
context: {
tanStackDbOperators: { eq, gt, gte, lt, lte, like, inArray, isNull, not, and, or },
},
});
```
tip
TanStack DB does not expose `ne`, `between`, `notBetween`, `notInArray`, `notLike`, or `isNotNull` — these are composed automatically using `not(...)`. For example, `!=` becomes `not(eq(...))` and `between` becomes `and(gte(...), lte(...))`.
##### Joins (multi-collection queries)[](#joins-multi-collection-queries "Direct link to Joins (multi-collection queries)")
When querying across joined collections, fields from non-primary collections must use dotted notation (`"alias.fieldName"`) to target the correct ref. Bare (unprefixed) fields always resolve to the primary collection (the first key in the `refs` object).
```
import * as tsdb from '@tanstack/db';
const query = {
combinator: 'and',
rules: [
// Bare field → resolves to the primary collection (su)
{ field: 'firstName', operator: '=', value: 'Bruce' },
// Dotted field → resolves to the nicknames collection (nn)
{ field: 'nn.nickname', operator: 'contains', value: 'Dark' },
],
};
const where = formatQuery(query, {
format: 'tanstack_db',
context: { tanStackDbOperators: tsdb },
});
const results = useLiveQuery(q =>
q
.from({ su: superUsersCollection })
.leftJoin({ nn: nicknamesCollection }, refs => eq(refs.su.id, refs.nn.userId))
.where(where)
);
```
caution
Bare fields cannot be disambiguated across collections at export time because TanStack DB refs are proxies that accept any property name. Always use dotted notation for fields on joined (non-primary) collections.
### MongoDB[](#mongodb "Direct link to MongoDB")
Generate MongoDB queries as JSON objects or strings. Use the "mongodb\_query" format (recommended) for JSON objects. The "mongodb" format is the stringified version.
info
The "mongodb" format was deprecated when the "mongodb\_query" export format was introduced in version 8.1.0.
```
formatQuery(query, 'mongodb_query');
```
Output (JSON object):
```
{ "$and": [{ "firstName": "Steve" }, { "lastName": "Vai" }] }
```
### Common Expression Language[](#common-expression-language "Direct link to Common Expression Language")
For [Common Expression Language (CEL)](https://cel.dev) output, use the "cel" format.
```
formatQuery(query, 'cel');
```
Output (string):
```
firstName = "Steve" && lastName = "Vai"
```
### Spring Expression Language[](#spring-expression-language "Direct link to Spring Expression Language")
For [Spring Expression Language (SpEL)](https://docs.spring.io/spring-framework/reference/core/expressions.html) output, use the "spel" format.
```
formatQuery(query, 'spel');
```
Output (string):
```
firstName == 'Steve' and lastName == 'Vai'
```
### JsonLogic[](#jsonlogic "Direct link to JsonLogic")
Generate objects for JsonLogic `apply` function (see = (ruleGroup, options) => {
if (ruleGroup.rules.length === 0) {
// Normally, empty rule groups are ignored, but here they evaluate to false
return '(1 = 0)';
}
// Defer to the default rule group processor for all other operators
return defaultRuleGroupProcessorSQL(ruleGroup, options);
};
formatQuery(query, { ruleGroupProcessor: customRuleGroupProcessor });
/*
"((1 = 0) and firstName LIKE 'S%')"
*/
```
## Validation[](#validation "Direct link to Validation")
Validation options (`validator` and `fields` – see [Validation](/docs/utils/validation.md)) only affect output when `format` is not "json" or "json\_without\_ids". If the `validator` function returns `false`, the `fallbackExpression` is returned. Otherwise, groups and rules marked as invalid (by the validation map from the `validator` function or field-based `validator` function) are ignored.
Example:
```
const query: RuleGroupType = {
id: 'root',
rules: [
{ id: 'r1', field: 'firstName', value: '', operator: '=' },
{ id: 'r2', field: 'lastName', value: 'Vai', operator: '=' },
],
combinator: 'and',
not: false,
};
// Example 1
// Query is invalid based on the validator function
formatQuery(query, {
format: 'sql',
validator: () => false,
});
/*
"(1 = 1)" <-- see `fallbackExpression` option
*/
// Example 2
// Rule "r1" is invalid based on the validation map
formatQuery(query, {
format: 'sql',
validator: () => ({ r1: false }),
});
/*
"(lastName = 'Vai')" <-- skipped `firstName` rule with `id === 'r1'`
*/
// Example 3
// Rule "r1" is invalid based on the field validator for `firstName`
formatQuery(query, {
format: 'sql',
fields: [{ name: 'firstName', validator: () => false }],
});
/*
"(lastName = 'Vai')" <-- skipped `firstName` rule because field validator returned `false`
*/
```
### Muted rules and groups[](#muted-rules-and-groups "Direct link to Muted rules and groups")
Rules and groups with the `muted` property set to `true` are excluded from output for all formats except "json" and "json\_without\_ids", similar to invalid rules and groups. This allows temporary exclusion of conditions without removing them from the query structure.
```
const query: RuleGroupType = {
combinator: 'and',
rules: [
{ field: 'firstName', operator: '=', value: 'Steve' },
{ field: 'lastName', operator: '=', value: 'Vai', muted: true },
],
};
formatQuery(query, 'sql');
// "(firstName = 'Steve')" - lastName rule is excluded
```
When a group is muted, it's replaced with the [fallback expression](#fallback-expression):
```
const query: RuleGroupType = {
combinator: 'and',
rules: [
{ field: 'firstName', operator: '=', value: 'Steve' },
{
combinator: 'or',
rules: [
{ field: 'lastName', operator: '=', value: 'Vai' },
{ field: 'instrument', operator: '=', value: 'Guitar' },
],
muted: true,
},
],
};
formatQuery(query, 'sql');
// "(firstName = 'Steve' and (1 = 1))" - muted group becomes fallback
```
tip
Enable mute functionality in the UI by setting [`showMuteButtons`](/docs/components/querybuilder.md#showmutebuttons) to `true` on the main `QueryBuilder` component.
### Automatic validation[](#automatic-validation "Direct link to Automatic validation")
To minimize invalid syntax, `formatQuery` performs basic validation for "in", "notIn", "between", and "notBetween" operators for all formats except "json" and "json\_without\_ids", even without specified validator functions or field validators.
* Rules with "in" or "notIn" operators are invalid if the `value` is neither an array with at least one element (`value.length > 0`) nor a non-empty string.
* Rules with "between" or "notBetween" operators are invalid if the `value` is neither an array with at least two elements (`value.length >= 2`) nor a string with at least one comma not at the first or last position (`value.split(',').length >= 2`, and neither element is empty).
* Rules where `field`, `operator`, or `value` match their respective placeholder are invalid:
```
field === placeholderFieldName ||
operator === placeholderOperatorName ||
(placeholderValueName !== undefined && value === placeholderValueName)
```
---
# Framework adapter API
> *Refer to the [TypeScript reference](/docs/typescript.md) page for information about the types and interfaces referenced below.*
`@react-querybuilder/core` contains every derivation the `(
manager: QueryManager
): [RG, QueryManager];
function useQueryManager(
query?: RG,
options?: QueryManagerOptions
): [RG, QueryManager];
```
Unlike every other hook in this section, `useQueryManager` does *not* use Redux and does not need to be rendered beneath a `QueryBuilder`. `QueryManager` maintains its own state, so queries managed this way are invisible to [`useQueryBuilderQuery`](#usequerybuilderquery), [`useQueryBuilderSelector`](#usequerybuilderselector), [`useQueryBuilderHistory`](#usequerybuilderhistory), and [`getDispatchQueryById`](#getdispatchquerybyid). Use it to build a headless or fully custom interface; it is not a replacement for the [`QueryBuilder`](/docs/components/querybuilder.md) component.
Pass an existing manager to control its lifetime yourself:
```
const qm = useMemo(() => new QueryManager(initialQuery, { fields }), []);
const CustomUI = () => {
const [query] = useQueryManager(qm);
// ...
};
```
Or let the hook create one. The manager is created on the first render and never recreated, so `query` is an *initial* value and `options` are captured once—later changes to either argument are ignored:
```
const CustomUI = () => {
const [query, qm] = useQueryManager(initialQuery, { fields });
return (
<>
qm.add(qm.createRule())}>Add rule
{JSON.stringify(query, null, 2)}
);
};
```
Since the manager is stable, its methods are safe to call from event handlers and to use in dependency arrays. A [batch](/docs/utils/query-management.md#batching) triggers a single re-render regardless of how many changes it contains, and mutations that resolve to a no-op trigger none.
To change the configuration after the first render, call [`reconfigure`](/docs/utils/query-management.md#reconfiguration) on the manager. The hook subscribes to the manager's config version in addition to its query, so a reconfiguration re-renders the component even though the query object is unchanged. A `reconfigure` call that changes nothing is a no-op, so an effect like the one below is safe to run on every render of a component whose `translations` object is rebuilt each time.
```
useEffect(() => {
qm.reconfigure({ translations });
}, [qm, translations]);
```
## Component logic[](#component-logic "Direct link to Component logic")
The core logic of each component is encapsulated in a reusable hook. Each main component is little more than a call to its respective hook plus the JSX that uses the properties returned from that hook. This enables creating a custom presentation layer without copying logic code from the default components.
tip
The `@react-querybuilder/native` package demonstrates this concept well. It calls the hooks from its own query builder, rule group, and rule components, but nests the sub-components within React Native `View` elements instead of HTML `div` elements used by `react-querybuilder` components.
### `useRule`[](#userule "Direct link to userule")
Called by the [`Rule`](/docs/components/rule.md) component. See [source code](https://github.com/react-querybuilder/react-querybuilder/blob/main/packages/react-querybuilder/src/hooks/useRule.ts) for returned properties.
```
function useRule(props: RuleProps): {
// See source code for returned properties
};
```
The configuration-dependent half of its result—field data, operators, value editor type, value list, value sources, match modes, and validation result—is derived by the framework-agnostic `deriveRuleContext` utility from `@react-querybuilder/core`. [`QueryManager.getRuleContext()`](/docs/utils/query-management.md#rule-configuration) calls the same utility, so non-React implementations resolve rules identically. Its `classNames` and `outerClassName` come from the equally framework-agnostic [`deriveRuleClassNames`/`deriveRuleOuterClassName`](/docs/utils/query-management.md#classnames).
### `useRuleGroup`[](#userulegroup "Direct link to userulegroup")
Called by the [`RuleGroup`](/docs/components/rulegroup.md) component. See [source code](https://github.com/react-querybuilder/react-querybuilder/blob/main/packages/react-querybuilder/src/hooks/useRuleGroup.ts) for returned properties.
```
function useRuleGroup(props: RuleGroupProps): {
// See source code for returned properties
};
```
Its `classNames` and `outerClassName` come from [`deriveRuleGroupClassNames`/`deriveRuleGroupOuterClassName`](/docs/utils/query-management.md#classnames), and its combinator resolution from `getRuleGroupCombinator` (see [`QueryManager.getRuleGroupContext()`](/docs/utils/query-management.md#rule-configuration)).
### `useValueEditor`[](#usevalueeditor "Direct link to usevalueeditor")
Called by the [`ValueEditor`](/docs/components/valueeditor.md) component. Accepts the same `ValueEditorProps` as the component and returns an object with these properties: the value as an array, a multi-value handler, a processed version of the `parseNumbers` prop, and the classname(s) to be applied to each editor in editor series.
```
function useValueEditor(props: ValueEditorProps): {
valueAsArray: any[];
multiValueHandler: (val: string, idx: number) => void;
parseNumberMethod: ParseNumberMethod;
valueListItemClassName: string;
};
```
This hook updates the `value` as a side effect when these conditions are true:
* `skipHook` is `false` (the value editors in the [compatibility packages](/docs/compat.md) set this to `true` to avoid infinite loops)
* `inputType` is `"number"`
* `operator` is something other than `"between"`, `"notBetween"`, `"in"`, or `"notIn"`
* `valueEditorType` is not "multiselect"
* `value` is an array or a string containing a comma (`,`) and at least one non-whitespace character on either side.
If all of these conditions are met, `handleOnChange` will be called with the first element of the array, or any characters before the first comma if `value` is a string.
Everything except that side effect is derived by the framework-agnostic [value editor utilities](/docs/utils/query-management.md#value-editors) from `@react-querybuilder/core`, so an implementation in another framework can reuse the logic without reimplementing it.
### `useValueSelector`[](#usevalueselector "Direct link to usevalueselector")
Called by the [`ValueSelector`](/docs/components/valueselector.md) component. Returns the given value as an array (unchanged if already an array) and a memoized change handler.
```
function useValueSelector(
props: Pick
): {
onChange: (v: string | string[]) => void;
val?: string | any[];
};
```
### `useSelectElementChangeHandler`[](#useselectelementchangehandler "Direct link to useselectelementchangehandler")
Used by the [`ValueSelector`](/docs/components/valueselector.md) component. Returns a memoized change handler designed specifically for HTML `) => void;
```
### `useShiftActions`[](#useshiftactions "Direct link to useshiftactions")
Used by the [`ShiftActions`](/docs/components/shiftactions.md) component. Generates `shiftUp` and `shiftDown` methods to move a rule/group up or down in the query hierarchy, plus `shiftUpDisabled`/`shiftDownDisabled` to indicate whether either button should be disabled (`shiftUpDisabled` is `true` for the first rule/group in the root group; `shiftDownDisabled` is `true` for the last rule/group in the root group).
```
function useShiftActions(
props: { path: Path } & Pick
): {
shiftDown: () => void;
shiftDownDisabled: boolean;
shiftUp: () => void;
shiftUpDisabled: boolean;
};
```
### `useStopEventPropagation`[](#usestopeventpropagation "Direct link to usestopeventpropagation")
Used by the default [`Rule`](/docs/components/rule.md) and [`RuleGroup`](/docs/components/rulegroup.md) components to prevent default behavior and stop event propagation (e.g., a `MouseEvent` after clicking a ``). Takes a function that accepts a `MouseEvent` and context parameters, then returns a new function that calls `event.preventDefault()` and `event.stopPropagation()` before calling the original function with the same arguments.
```
function useStopEventPropagation(
method: (event: React.MouseEvent, context: any) => void
): (event: React.MouseEvent, context: any) => void;
```
This hook is *not* used in `RuleNative` and `RuleGroupNative`—the `Rule` and `RuleGroup` components for `@react-querybuilder/native`.
### `useQueryBuilder`[](#usequerybuilder "Direct link to usequerybuilder")
Returns everything needed to render a [`QueryBuilder`](/docs/components/querybuilder.md) component. Internally, this hook passes the result of [`useQueryBuilderSetup`](#usequerybuildersetup) to [`useQueryBuilderSchema`](#usequerybuilderschema) and returns the result of `useQueryBuilderSchema`. The returned object combines the results of `useQueryBuilderSchema` and `useQueryBuilderSetup` (see below).
As with `useQueryBuilderSchema`, this Hook must be called from a descendant component of `QueryBuilderStateProvider`. See [`QueryBuilder` source code](https://github.com/react-querybuilder/react-querybuilder/blob/main/packages/react-querybuilder/src/components/QueryBuilder.tsx) for an example.
info
This hook is unlikely to be necessary unless you're reimplementing the *entire* `QueryBuilder` component structure.
### `useQueryBuilderSetup`[](#usequerybuildersetup "Direct link to usequerybuildersetup")
Called by the internal component rendered by [`QueryBuilder`](/docs/components/querybuilder.md). Merges props and context values with the defaults and generates actions.
info
This hook is unlikely to be necessary unless you're reimplementing the *entire* `QueryBuilder` component structure.
```
function useQueryBuilderSetup(props: QueryBuilderProps): {
qbId: qbId.current;
rqbContext: ReturnType;
fields: OptionList;
fieldMap: Record;
combinators: OptionList;
getOperatorsMain: (field: string) => OptionList;
getRuleDefaultOperator: (field: string) => string;
getValueEditorTypeMain: (field: string, operator: string) => ValueEditorType;
getValueSourcesMain: (field: string, operator: string) => ValueSources;
getValuesMain: (field: string, operator: string) => OptionList;
getRuleDefaultValue: (rule: RuleType) => any;
getInputTypeMain: (field: string, operator: string) => string;
createRule: () => RuleType;
createRuleGroup: () => RuleGroupTypeAny;
};
```
### `useQueryBuilderSchema`[](#usequerybuilderschema "Direct link to usequerybuilderschema")
Called by the internal component rendered by [`QueryBuilder`](/docs/components/querybuilder.md). Returns everything needed to render a wrapper element (e.g., ``) and the root [`RuleGroup`](/docs/components/rulegroup.md) element based on the provided props and the result from [`useQueryBuilderSetup`](#usequerybuildersetup).
This Hook must be called from a descendant component of `QueryBuilderStateProvider`. See [`QueryBuilder` source code](https://github.com/react-querybuilder/react-querybuilder/blob/main/packages/react-querybuilder/src/components/QueryBuilder.tsx) for an example.
info
This hook is unlikely to be necessary unless you're reimplementing the *entire* `QueryBuilder` component structure.
```
function useQueryBuilderSchema(
props: QueryBuilderProps,
setup: ReturnType
): QueryBuilderProps & {
actions: QueryActions;
rootGroup: RuleGroupTypeAny;
rootGroupDisabled: RuleGroupTypeAny;
queryDisabled: boolean;
rqbContext: ReturnType;
schema: Schema;
translations: TranslationsFull;
wrapperClassName: string;
dndEnabledAttr: 'enabled' | 'disabled';
inlineCombinatorsAttr: 'enabled' | 'disabled';
combinatorPropObject: Pick;
};
```
## Other utilities[](#other-utilities "Direct link to Other utilities")
### `useAsyncOptionList`[](#useasyncoptionlist "Direct link to useasyncoptionlist")
Augments a `ValueSelectorProps` or `ValueEditorProps` object with [async option loading](/docs/tips/async-option-lists.md).
```
import { type UseAsyncOptionListParams, useAsyncOptionList } from 'react-querybuilder';
const useAsyncOptionListParams: UseAsyncOptionListParams = {
getCacheKey: 'field',
loadOptionList: async (value, { ruleOrGroup }) => {
const response = await fetch(`/api/operators?field=${ruleOrGroup.field}`);
return response.json();
},
};
const AsyncOperatorSelector = (props: ValueSelectorProps) => {
const asyncProps = useAsyncOptionList(props, useAsyncOptionListParams);
return (prop: T): T | null;
```
## Internal[](#internal "Direct link to Internal")
These hooks log error messages to the console in certain situations (only in "development" mode). They encourage correct usage of React Query Builder and aren't intended for use in custom components.
### `useControlledOrUncontrolled`[](#usecontrolledoruncontrolled "Direct link to usecontrolledoruncontrolled")
Logs an error to the console if any of the following are true:
* Both `query` and `defaultQuery` props are defined.
* The `query` prop is defined during one render and undefined in a subsequent render.
* The `query` prop is undefined during one render and defined in a subsequent render.
### `useDeprecatedProps`[](#usedeprecatedprops "Direct link to usedeprecatedprops")
Logs an error to the console if any of the following are true:
* `QueryBuilder` is rendered with `independentCombinators` prop (see [Independent combinators](/docs/components/querybuilder.md#independent-combinators))
* `RuleGroup` is rendered with `combinator` or `rules` props (deprecated in favor of `ruleGroup`)
* `Rule` is rendered with `field`, `operator`, or `value` props (deprecated in favor of `rule`)
### `useReactDndWarning`[](#usereactdndwarning "Direct link to usereactdndwarning")
Logs an error to the console if the `enableDragAndDrop` prop is `true` but the `react-dnd` and `react-dnd-html5-backend` dependencies are not loaded.
---
# Import
> *Refer to the [TypeScript reference](/docs/typescript.md) page for information about the types and interfaces referenced below.*
Import/parser functions convert query strings or objects from specific languages to query objects for ``): An array of parameter values or a parameter-to-value mapping object.
* `paramPrefix` (`string`): Ignores this string at the beginning of parameter identifiers when matching to parameter names in the `params` object.
* `parseParameters` (`boolean | { prefix?: string | string[]; positional?: boolean }`): Preserves unresolved bind variables as parameter rules (`valueSource: 'parameter'`) instead of resolving them via `params`. Pass `true` to accept the default named prefix `':'` and positional `?`, or an object to configure one or more named `prefix`es (e.g. `'@'`, `'$'`) and toggle `positional` (default enabled). Positional `?` placeholders are named by 1-based ordinal (`?` → `1`). `params` substitution takes precedence when both are set.
* `getExpression` (`(node, ctx) => ExpressionNode | null`): A handler that converts an arithmetic/function operand subtree into an [expression](/docs/expr.md) node (`valueSource: 'expression'`, or a `lhs` when on the left of a comparison). Returning `null` drops the rule. Use [`expressionParserSQL`](/docs/expr.md#import-parsing) from `@react-querybuilder/expr` for the built-in SQL inverse, or `getExpressionParserSQL` to add custom functions/operators.
### Usage[](#usage "Direct link to Usage")
All these statements produce the same result:
```
parseSQL(`SELECT * FROM t WHERE firstName = 'Steve' AND lastName = 'Vai'`);
parseSQL(`SELECT * FROM t WHERE firstName = ? AND lastName = ?`, {
params: ['Steve', 'Vai'],
});
parseSQL(`SELECT * FROM t WHERE firstName = :p1 AND lastName = :p2`, {
params: { p1: 'Steve', p2: 'Vai' },
});
parseSQL(`SELECT * FROM t WHERE firstName = $p1 AND lastName = $p2`, {
params: { p1: 'Steve', p2: 'Vai' },
paramPrefix: '$',
});
```
Output (`RuleGroupType`):
```
{
"combinator": "and",
"rules": [
{
"field": "firstName",
"operator": "=",
"value": "Steve"
},
{
"field": "lastName",
"operator": "=",
"value": "Vai"
}
]
}
```
tip
Since v5.0, `parseSQL` detects `XOR` operators and converts them to rule groups with the "xor" combinator. Since "xor" isn't in `defaultCombinators`, specify `defaultCombinatorsExtended` in your `,
options?: ParseMongoDbOptions
): RuleGroupTypeAny;
```
`parseMongoDB` accepts a MongoDB query as either a JSON object or `JSON.parse`-able string.
Click the "Import MongoDB" button in [the demo](/demo) to try it out.
### Usage[](#usage-1 "Direct link to Usage")
```
parseMongoDB(`{ "firstName": "Steve", "lastName": { $eq: "Vai" } }`);
// OR
parseMongoDB({ firstName: 'Steve', lastName: { $eq: 'Vai' } });
```
Output (`RuleGroupType`):
```
{
"combinator": "and",
"rules": [
{
"field": "firstName",
"operator": "=",
"value": "Steve"
},
{
"field": "lastName",
"operator": "=",
"value": "Vai"
}
]
}
```
### Custom operators[](#custom-operators "Direct link to Custom operators")
`parseMongoDB` identifies and processes custom operators with the `additionalOperators` option. This option maps operators to their processing functions. Functions receive the operator, associated value, and other options, then should return `RuleType` or `RuleGroupType`. (Don't return `RuleGroupTypeIC`, even with [independent combinators](/docs/components/querybuilder.md#independent-combinators). If `independentCombinators` is `true`, `parseMongoDB` converts the final query to `RuleGroupTypeIC` before returning.)
Example:
```
parseMongoDB(
{
$myCustomOp: ['Vai', 'Vaughan'],
},
{
additionalOperators: {
$myCustomOp: (_op, val) => ({
field: 'lastName',
operator: 'in',
value: val,
}),
},
}
);
```
Output (`RuleGroupType`):
```
{
"combinator": "and",
"rules": [
{
"field": "lastName",
"operator": "in",
"value": ["Vai", "Vaughan"]
}
]
}
```
tip
Valid MongoDB query strings may not strictly conform to JSON. To handle extended formats, pre-parse query strings with a library like [mongodb-query-parser](https://www.npmjs.com/package/mongodb-query-parser) before passing them to `parseMongoDB`.
### Expressions[](#expressions "Direct link to Expressions")
`parseMongoDB` accepts a `getExpression` option (`(node, ctx) => ExpressionNode | null`) that converts a MongoDB `$expr` aggregation-expression operand into an [expression](/docs/expr.md) node. An expression on the right of a comparison becomes the rule's `value` with `valueSource: 'expression'`; an expression on the left sets `field: ''` and stores the tree in `lhs`; inclusive-`between`/`notBetween` bounds become a two-element `value`. Only `$expr` operands are routed through this handler; bare field references and literals fall through to the stock logic. Returning `null` drops the rule. Use [`expressionParserMongoDB`](/docs/expr.md#import-parsing) from `@react-querybuilder/expr` for the built-in MongoDB inverse, or `getExpressionParserMongoDB` to add custom operations.
```
import { parseMongoDB } from '@react-querybuilder/core/parseMongoDB';
import { expressionParserMongoDB } from '@react-querybuilder/expr';
const query = parseMongoDB(mongoDbQuery, { getExpression: expressionParserMongoDB });
```
## JsonLogic[](#jsonlogic "Direct link to JsonLogic")
```
import { parseJsonLogic } from '@react-querybuilder/core/parseJsonLogic';
function parseJsonLogic(
jsonLogic: string | JsonLogic,
options?: ParseJsonLogicOptions
): RuleGroupTypeAny;
```
`parseJsonLogic` accepts a [JsonLogic](https://jsonlogic.com/) object or `JSON.parse`-able string.
Click the "Import JsonLogic" button in [the demo](/demo) to try it out.
### Usage[](#usage-2 "Direct link to Usage")
```
parseJsonLogic(
`{ "and": [{ "===": [{ "var": "firstName" }, "Steve"] }, { "===": [{ "var": "lastName" }, "Vai"] }] }`
);
// OR
parseJsonLogic({
and: [{ '===': [{ var: 'firstName' }, 'Steve'] }, { '===': [{ var: 'lastName' }, 'Vai'] }],
});
```
Output (`RuleGroupType`):
```
{
"combinator": "and",
"rules": [
{
"field": "firstName",
"operator": "=",
"value": "Steve"
},
{
"field": "lastName",
"operator": "=",
"value": "Vai"
}
]
}
```
### Expressions[](#expressions-1 "Direct link to Expressions")
`parseJsonLogic` accepts a `getExpression` option (`(node, ctx) => ExpressionNode | null`) that converts an arithmetic/function operand subtree into an [expression](/docs/expr.md) node. An expression on the right of a comparison becomes the rule's `value` with `valueSource: 'expression'`; an expression on the left sets `field: ''` and stores the tree in `lhs`; inclusive-`between`/`notBetween` bounds become a two-element `value`. Returning `null` drops the rule. Use [`expressionParserJsonLogic`](/docs/expr.md#import-parsing) from `@react-querybuilder/expr` for the built-in JsonLogic inverse, or `getExpressionParserJsonLogic` to add custom operations.
```
import { parseJsonLogic } from '@react-querybuilder/core/parseJsonLogic';
import { expressionParserJsonLogic } from '@react-querybuilder/expr';
const query = parseJsonLogic(jsonLogic, { getExpression: expressionParserJsonLogic });
```
### Custom operations[](#custom-operations "Direct link to Custom operations")
By default, `parseJsonLogic` handles standard JsonLogic operations that correspond to default React Query Builder operators. Use the `jsonLogicOperations` option to handle custom operations.
`jsonLogicOperations` is `Record RuleType | RuleGroupTypeAny>`. Keys are custom operations; values are functions returning a rule or group.
note
Including standard JsonLogic operations as keys in `jsonLogicOperations` overrides the default `parseJsonLogic` behavior for those operations.
This example uses a custom "regex" operation to produce a rule with the "contains" operator, using the regular expression's `source` property as the `value`.
```
parseJsonLogic(
{ regex: [{ var: 'firstName' }, /^Stev/] },
{
jsonLogicOperations: {
regex: val => ({ field: val[0].var, operator: 'contains', value: val[1].source }),
},
}
);
```
Output (`RuleGroupType`):
```
{
"combinator": "and",
"rules": [
{
"field": "firstName",
"operator": "contains",
"value": "^Stev"
}
]
}
```
## Spring Expression Language (SpEL)[](#spring-expression-language-spel "Direct link to Spring Expression Language (SpEL)")
```
import { parseSpEL } from '@react-querybuilder/core/parseSpEL';
function parseSpEL(spelQuery: string, options?: ParseSpELOptions): RuleGroupTypeAny;
```
`parseSpEL` accepts a [SpEL](https://docs.spring.io/spring-framework/docs/3.0.x/reference/expressions.html) string.
Click the "Import SpEL" button in [the demo](/demo) to try it out.
### Usage[](#usage-3 "Direct link to Usage")
```
parseSpEL(`firstName == "Steve" && lastName == "Vai"`);
```
Output (`RuleGroupType`):
```
{
"combinator": "and",
"rules": [
{
"field": "firstName",
"operator": "=",
"value": "Steve"
},
{
"field": "lastName",
"operator": "=",
"value": "Vai"
}
]
}
```
### Expressions[](#expressions-2 "Direct link to Expressions")
`parseSpEL` accepts a `getExpression` option (`(node, ctx) => ExpressionNode | null`) that converts an arithmetic, method call, or function call operand subtree into an [expression](/docs/expr.md) node. An expression on the right of a comparison becomes the rule's `value` with `valueSource: 'expression'`; an expression on the left sets `field: ''` and stores the tree in `lhs`; inclusive-`between`/`notBetween` bounds become a two-element `value`. Returning `null` drops the rule. Use [`expressionParserSpEL`](/docs/expr.md#import-parsing) from `@react-querybuilder/expr` for the built-in SpEL inverse, or `getExpressionParserSpEL` to add custom operators, functions, and methods. Infix arithmetic, `T(java.lang.Math).abs/min/max(...)` static calls, and `.toUpperCase()`/`.toLowerCase()` instance methods are all invertible; see the [expr docs](/docs/expr.md#spel) for details.
```
import { parseSpEL } from '@react-querybuilder/core/parseSpEL';
import { expressionParserSpEL } from '@react-querybuilder/expr';
const query = parseSpEL(spelQuery, { getExpression: expressionParserSpEL });
```
## Common Expression Language (CEL)[](#common-expression-language-cel "Direct link to Common Expression Language (CEL)")
```
import { parseCEL } from '@react-querybuilder/core/parseCEL';
function parseCEL(celQuery: string, options?: ParseCELOptions): RuleGroupTypeAny;
```
`parseCEL` accepts a [CEL](https://cel.dev) string.
Click the "Import CEL" button in [the demo](/demo) to try it out.
### Usage[](#usage-4 "Direct link to Usage")
```
parseCEL(`firstName == "Steve" && lastName == "Vai"`);
```
Output (`RuleGroupType`):
```
{
"combinator": "and",
"rules": [
{
"field": "firstName",
"operator": "=",
"value": "Steve"
},
{
"field": "lastName",
"operator": "=",
"value": "Vai"
}
]
}
```
### Custom expressions[](#custom-expressions "Direct link to Custom expressions")
Provide a `customExpressionHandler` function to process any AST fragments not recognized by the default parser.
Example:
```
parseCEL('opted_in_at.isBirthday(-1)', {
customExpressionHandler: expr => ({
field: expr.left.value,
operator: expr.right.value,
value: expr.list.value[0].value,
}),
});
```
Output (`RuleGroupType`):
```
{
"combinator": "and",
"rules": [
{
"field": "opted_in_at",
"operator": "isBirthday",
"value": -1
}
]
}
```
To assist with processing the AST fragments, all types, type guard functions, and other utilities used internally by `parseCEL` are exported.
### Expressions[](#expressions-3 "Direct link to Expressions")
`parseCEL` accepts a `getExpression` option (`(node, ctx) => ExpressionNode | null`) that converts an arithmetic/function operand subtree into an [expression](/docs/expr.md) node. An expression on the right of a comparison becomes the rule's `value` with `valueSource: 'expression'`; an expression on the left sets `field: ''` and stores the tree in `lhs`; inclusive-`between`/`notBetween` bounds become a two-element `value`. Returning `null` drops the rule. Use [`expressionParserCEL`](/docs/expr.md#import-parsing) from `@react-querybuilder/expr` for the built-in CEL inverse, or `getExpressionParserCEL` to add custom functions. Note that `abs`/`upper`/`lower` are not invertible on the CEL side—see the [expr docs](/docs/expr.md#cel) for details.
```
import { parseCEL } from '@react-querybuilder/core/parseCEL';
import { expressionParserCEL } from '@react-querybuilder/expr';
const query = parseCEL(celQuery, { getExpression: expressionParserCEL });
```
## JSONata[](#jsonata "Direct link to JSONata")
```
import { parseJSONata } from '@react-querybuilder/core/parseJSONata';
function parseJSONata(jsonataQuery: string, options?: ParseJSONataOptions): RuleGroupTypeAny;
```
`parseJSONata` accepts a [JSONata](https://jsonata.org/) string.
Click the "Import JSONata" button in [the demo](/demo) to try it out.
### Usage[](#usage-5 "Direct link to Usage")
```
parseJSONata(`firstName = "Steve" and lastName in ["Vai", "Vaughan"]`);
```
Output (`RuleGroupType`):
```
{
"combinator": "and",
"rules": [
{
"field": "firstName",
"operator": "=",
"value": "Steve"
},
{
"field": "lastName",
"operator": "in",
"value": ["Vai", "Vaughan"]
}
]
}
```
JSONata lists are always translated to arrays. The [`listsAsArrays` option](#lists-as-arrays) is ignored (effectively always `true`).
### Expressions[](#expressions-4 "Direct link to Expressions")
`parseJSONata` accepts a `getExpression` option (`(node, ctx) => ExpressionNode | null`) that converts an arithmetic/function operand subtree into an [expression](/docs/expr.md) node. An expression on the right of a comparison becomes the rule's `value` with `valueSource: 'expression'`; an expression on the left sets `field: ''` and stores the tree in `lhs`; inclusive-`between`/`notBetween` bounds become a two-element `value`. Returning `null` drops the rule. Use [`expressionParserJSONata`](/docs/expr.md#import-parsing) from `@react-querybuilder/expr` for the built-in JSONata inverse, or `getExpressionParserJSONata` to add custom functions.
```
import { parseJSONata } from '@react-querybuilder/core/parseJSONata';
import { expressionParserJSONata } from '@react-querybuilder/expr';
const query = parseJSONata(jsonataQuery, { getExpression: expressionParserJSONata });
```
## Cypher[](#cypher "Direct link to Cypher")
```
import { parseCypher } from '@react-querybuilder/core/parseCypher';
function parseCypher(cypherQuery: string, options?: ParseCypherOptions): RuleGroupTypeAny;
```
`parseCypher` accepts a [Cypher](https://neo4j.com/docs/cypher-manual/) query string, a `WHERE` clause, or a bare boolean expression. MATCH and RETURN clauses are consumed but discarded — only WHERE conditions are returned.
A `parseGQL` function is also exported since [GQL](https://www.iso.org/standard/76120.html) uses the same expression syntax.
note
`parseCypher` requires the `chevrotain` package (optional peer dependency).
### Usage[](#usage-6 "Direct link to Usage")
```
// Full query — extracts WHERE conditions only
parseCypher('MATCH (n:Person) WHERE n.age > 30 AND n.name CONTAINS "Alice" RETURN n');
// WHERE clause only
parseCypher('WHERE n.age > 30');
// Bare expression
parseCypher('n.age > 30 AND n.name CONTAINS "Alice"');
```
Output (`RuleGroupType`):
```
{
"combinator": "and",
"rules": [
{ "field": "n.age", "operator": ">", "value": 30 },
{ "field": "n.name", "operator": "contains", "value": "Alice" }
]
}
```
## SPARQL[](#sparql "Direct link to SPARQL")
```
import { parseSPARQL } from '@react-querybuilder/core/parseSPARQL';
function parseSPARQL(sparqlQuery: string, options?: ParseSPARQLOptions): RuleGroupTypeAny;
```
`parseSPARQL` accepts a [SPARQL](https://www.w3.org/TR/sparql11-query/) query string or a bare `FILTER` expression. Triple patterns (BGPs) are consumed but discarded — only FILTER conditions are returned.
note
`parseSPARQL` requires the `@traqula/parser-sparql-1-2` package (optional peer dependency).
### Usage[](#usage-7 "Direct link to Usage")
```
// Full query — extracts FILTER conditions only
parseSPARQL('SELECT ?x WHERE { ?x foaf:name ?name . FILTER(?age > 30) }');
// Bare FILTER expression (auto-wrapped in a stub query)
parseSPARQL('?age > 30 && ?name != "Alice"');
```
Output (`RuleGroupType`):
```
{
"combinator": "and",
"rules": [
{ "field": "?age", "operator": ">", "value": 30 },
{ "field": "?name", "operator": "!=", "value": "Alice" }
]
}
```
## Gremlin[](#gremlin "Direct link to Gremlin")
```
import { parseGremlin } from '@react-querybuilder/core/parseGremlin';
function parseGremlin(gremlinQuery: string, options?: ParseGremlinOptions): RuleGroupTypeAny;
```
`parseGremlin` accepts a [Gremlin](https://tinkerpop.apache.org/) traversal string or a chain of `.has()` steps. Pattern steps (`.hasLabel()`, `.out()`, `.in()`, `.as()`) are consumed but discarded — only `.has()` filter predicates are returned.
### Usage[](#usage-8 "Direct link to Usage")
```
// Full traversal — extracts .has() conditions only
parseGremlin("g.V().hasLabel('Person').has('age', gt(30)).has('name', 'Alice')");
// Bare .has() chain
parseGremlin(".has('age', gt(30)).has('name', 'Alice')");
```
Output (`RuleGroupType`):
```
{
"combinator": "and",
"rules": [
{ "field": "age", "operator": ">", "value": 30 },
{ "field": "name", "operator": "=", "value": "Alice" }
]
}
```
## react-awesome-query-builder[](#react-awesome-query-builder "Direct link to react-awesome-query-builder")
`parseRAQB` converts a [react-awesome-query-builder](https://github.com/ukrbublik/react-awesome-query-builder) (RAQB) query tree to an RQB query. It is *not* part of this package—since most projects need it exactly once, it lives in the separate [`@react-querybuilder/migrate-raqb`](https://github.com/react-querybuilder/migrate-raqb) package.
* npm
* Bun
* Yarn
* pnpm
```
npm i @react-querybuilder/migrate-raqb
```
```
bun add @react-querybuilder/migrate-raqb
```
```
yarn add @react-querybuilder/migrate-raqb
```
```
pnpm add @react-querybuilder/migrate-raqb
```
```
import { parseRAQB, parseRAQBFields } from '@react-querybuilder/migrate-raqb';
const fields = parseRAQBFields(raqbConfig.fields);
const query = parseRAQB(Utils.getTree(immutableTree), { fields });
```
Output (`RuleGroupType`):
```
{
"combinator": "and",
"rules": [{ "field": "price", "operator": ">", "value": 10 }]
}
```
See [Migrating from react-awesome-query-builder](/docs/tips/migrate-from-raqb.md) for the full concept mapping, operator translation table, and options.
## Configuration[](#configuration "Direct link to Configuration")
### Lists as arrays[](#lists-as-arrays "Direct link to Lists as arrays")
To generate arrays instead of comma-separated strings for "in"- and "between"-type operator values, use the `listsAsArrays` option.
```
parseSQL(`SELECT * FROM t WHERE lastName IN ('Vai', 'Vaughan') AND age BETWEEN 20 AND 100`, {
listsAsArrays: true;
});
```
Output:
```
{
"combinator": "and",
"rules": [
{
"field": "lastName",
"operator": "in",
"value": ["Vai", "Vaughan"]
},
{
"field": "age",
"operator": "between",
"value": [20, 100]
}
]
}
```
### Independent combinators[](#independent-combinators "Direct link to Independent combinators")
When `independentCombinators` is `true`, `parse*` functions output queries with combinator identifiers *between* sibling rules/groups instead of at the group level.
```
parseSQL(`SELECT * FROM t WHERE firstName = 'Steve' AND lastName = 'Vai'`, {
independentCombinators: true,
});
```
Output (`RuleGroupTypeIC`):
```
{
"rules": [
{
"field": "firstName",
"operator": "=",
"value": "Steve"
},
"and",
{
"field": "lastName",
"operator": "=",
"value": "Vai"
}
]
}
```
### Fields as value source[](#fields-as-value-source "Direct link to Fields as value source")
When the `fields` option is provided (accepting the same types as the [`fields` prop](/docs/components/querybuilder.md#fields)), `parse*` functions validate clauses with field identifiers to the right of the operator instead of primitive values. A `getValueSources` function (same signature as the [prop](/docs/components/querybuilder.md#getvaluesources)) can also help validate rules.
For such rules to be valid, one of these must be an array including "field": (1) the `getValueSources` return value, (2) the field's `valueSources` function return value, or (3) the field's `valueSources` property. The code below demonstrates all three methods.
```
parseSQL(`SELECT * FROM t WHERE firstName = lastName`, {
fields: [
{ name: 'firstName', label: 'First Name', valueSources: ['value', 'field'] },
{ name: 'lastName', label: 'Last Name', valueSources: () => ['value', 'field'] },
],
getValueSources: () => ['value', 'field'],
});
```
Output:
```
{
"combinator": "and",
"rules": [
{
"field": "firstName",
"operator": "=",
"value": "lastName",
"valueSource": "field"
}
]
}
```
### Generating `id`s[](#generating-ids "Direct link to generating-ids")
When `generateIDs` is `true`, `parse*` functions generate a unique `id` property for the output query object and each nested rule and group using `prepareRuleGroup`.
note
`parse*` functions only validate clauses where "field" is the *only* detected value source. Operators like "between" and "in" must have either only field names or only scalar values to the right of the operator—not mixed. See examples below.
#### Invalid clauses[](#invalid-clauses "Direct link to Invalid clauses")
```
// 1 is a scalar value and `iq` is a field name
parseSQL(`SELECT * FROM tbl WHERE age between 1 and iq`);
// List contains a mix of scalar values and field names
parseSQL(`SELECT * FROM tbl WHERE firstName IN (lastName, 'Steve', 'Stevie')`);
```
#### Valid clauses[](#valid-clauses "Direct link to Valid clauses")
```
// Both are field names
parseSQL(`SELECT * FROM tbl WHERE age between numChildren and iq`);
// Both are scalar values
parseSQL(`SELECT * FROM tbl WHERE age between 26 and 52`);
// All items are field names
parseSQL(`SELECT * FROM tbl WHERE firstName IN (lastName, middleName)`);
// All items are scalar values
parseSQL(`SELECT * FROM tbl WHERE firstName IN ('Steve', 'Stevie')`);
```
---
# Miscellaneous
> *Refer to the [TypeScript reference](/docs/typescript.md) page for information about the types and interfaces referenced below.*
A partial list of exports from `react-querybuilder`.
## Utilities[](#utilities "Direct link to Utilities")
### `transformQuery`[](#transformquery "Direct link to transformquery")
```
function transformQuery(query: RuleGroupTypeAny, options: QueryTransformerOptions): any;
```
This function recursively processes a query object (`RuleGroupType` or `RuleGroupTypeIC`), passing each `RuleType` object to a provided `ruleProcessor` function. Available options include:
* `ruleProcessor`: Custom processing function for each rule.
* `ruleGroupProcessor`: Custom processing function for each rule group. Each group's `rules` property is retained and recursively processed regardless of other mutations.
* `propertyMap`: Keys in rule or group objects that match keys in this object are renamed to the corresponding value.
* `combinatorMap`: Translates combinators; for example, `{and: "&&", or: "||"}` would convert "and"/"or" combinators to "&&"/"||", respectively.
* `operatorMap`: Converts operators that match keys in this object to corresponding values, e.g., `{"=": "=="}`.
* `deleteRemappedProperties`: Defaults to `true`; pass `false` to retain both remapped properties *and* original properties in the resulting object.
See the [test suite](https://github.com/react-querybuilder/react-querybuilder/blob/main/packages/core/src/utils/transformQuery.test.ts) for example usage.
### `defaultValidator`[](#defaultvalidator "Direct link to defaultvalidator")
```
function defaultValidator(query: RuleGroupTypeAny): {
[id: string]: { valid: boolean; reasons?: string[] };
};
```
Pass `validator={defaultValidator}` to automatically validate groups (rules are ignored). A group is marked invalid when either of these conditions are true:
1. The group has no child rules or groups (`query.rules.length === 0`)
2. The group has a missing/invalid `combinator` property and more than one child rule or group (`rules.length >= 2`)
You can see the default validator in action in the [demo](/demo) by checking the ['Use validation' option](/demo#validateQuery=true). Empty groups display bold text on their "+ Rule" button and a description where rules normally appear.
### `findPath`[](#findpath "Direct link to findpath")
```
function findPath(path: Path, query: RuleGroupTypeAny): RuleType | RuleGroupTypeAny | null;
```
`findPath` finds the rule or group within the query hierarchy that has a given `path`. This is useful in custom [`onAddRule`](/docs/components/querybuilder.md#onaddrule) and [`onAddGroup`](/docs/components/querybuilder.md#onaddgroup) functions.
More extensive documentation on the `path` property is [here](/docs/tips/path.md).
### `findID`[](#findid "Direct link to findid")
```
function findID(id: string, query: RuleGroupTypeAny): RuleType | RuleGroupTypeAny | null;
```
`findID` finds the rule or group within the query hierarchy that has a given `id`.
### `convertQuery`[](#convertquery "Direct link to convertquery")
```
function convertQuery(query: RuleGroupType): RuleGroupTypeIC;
// OR
function convertQuery(query: RuleGroupTypeIC): RuleGroupType;
```
`convertQuery` toggles a query between the conventional `RuleGroupType` structure (with combinators at the group level) and the "independent combinators" structure `RuleGroupTypeIC` (with combinators between every other rule/group).
`convertToIC` and `convertFromIC` perform the same function as `convertQuery` but only in the directions indicated by their names.
## Number parsing[](#number-parsing "Direct link to Number parsing")
HTML ` | BaseOptionMap;
/** The operators available for rules. Accepts the same shapes as the `operators` prop. */
operators?: FlexibleOptionListProp | BaseOptionMap;
/** The combinators available for groups. Defaults to `defaultCombinators`. */
combinators?: FlexibleOptionListProp | BaseOptionMap;
/** Properties applied to every field in `fields`. */
baseField?: Record;
/** Properties applied to every operator in `operators`. */
baseOperator?: Record;
/** Properties applied to every combinator in `combinators`. */
baseCombinator?: Record;
/** When `false`, an empty placeholder option is prepended to the field list. */
autoSelectField?: boolean;
/** When `false`, an empty placeholder option is prepended to each operator list. */
autoSelectOperator?: boolean;
/** When `false`, an empty placeholder option is prepended to each value list. */
autoSelectValue?: boolean;
/**
* Translations, accepting the same shape as the `translations` prop. Only the placeholder
* properties of `fields`, `operators`, and `values` are used, and only when the corresponding
* `autoSelect*` option is `false`; the remaining keys describe UI elements that have no
* meaning outside the `QueryBuilder` component. Labels are typed as `unknown` so the React
* `Translations` type, whose labels are `ReactNode`, can be passed as-is.
*/
translations?: Partial>;
/** The default `field` for rules created by {@link QueryManager.createRule}. */
getDefaultField?: DefaultFieldProp;
/** The default `operator` for a given field. */
getDefaultOperator?: DefaultOperatorProp;
/** Overrides the computed default `value` for a new rule. */
getDefaultValue?: (rule: RuleType, misc: { fieldData: F }) => unknown;
/** The operators available for a given field. */
getOperators?: (field: string, misc: { fieldData: F }) => FlexibleOptionList | null;
/** The value editor type for a given field/operator, which informs the default value. */
getValueEditorType?: (field: string, operator: string, misc: { fieldData: F }) => ValueEditorType;
/** The value list for a given field/operator, which informs the default value. */
getValues?: (
field: string,
operator: string,
misc: { fieldData: F }
) => FlexibleOptionList;
/** The valid value sources for a given field/operator. */
getValueSources?: (
field: string,
operator: string,
misc: { fieldData: F }
) => ValueSources | ValueSourceFlexibleOptions;
/** The valid match modes for a given field. */
getMatchModes?: (
field: string,
misc: { fieldData: F }
) => boolean | MatchMode[] | FlexibleOption[];
/** The named parameters available for a given field/operator. */
getParameters?: (
field: string,
operator: string,
misc: { fieldData: F }
) => FlexibleOptionList | null;
/** When `true`, multi-value defaults are arrays instead of comma-joined strings. */
listsAsArrays?: boolean;
/** When `true`, groups created by {@link QueryManager.createRuleGroup} contain one new rule. */
addRuleToNewGroups?: boolean;
/**
* When updating a rule's `field`, reset its `operator`, `value`, and `valueSource` to their
* defaults. Defaults to `true`, matching the `QueryBuilder` prop of the same name.
*/
resetOnFieldChange?: boolean;
/**
* When updating a rule's `operator`, reset its `value` to the default. Defaults to `false`,
* matching the `QueryBuilder` prop of the same name.
*/
resetOnOperatorChange?: boolean;
/**
* The maximum depth at which groups may be added. As with the `QueryBuilder` prop of the same
* name, a non-positive value means unlimited. Defaults to `Infinity`.
*/
maxLevels?: number;
/**
* Honor `disabled` properties within the query, so mutations targeting a disabled rule or
* group (or a descendant of a disabled group) are aborted. Updating a node's own `disabled`
* property is always permitted. Defaults to `true`, matching the `QueryBuilder` component;
* pass `false` to mutate freely regardless of the property.
*/
respectDisabled?: boolean;
/**
* Paths that are disabled without the corresponding rule or group carrying a `disabled`
* property. This mirrors the array form of the `QueryBuilder` `disabled` prop
* (e.g. `disabled={[[2]]}`), which disables nodes by position rather than by data.
*
* A path is treated as disabled if it appears here or descends from a path that does. Honored
* only when `respectDisabled` is `true`; as with the `disabled` property, a node's own
* `disabled` can always be changed so it is never permanently locked.
*/
disabledPaths?: Path[];
/** Abort every mutation, as though the entire query were disabled. Defaults to `false`. */
queryDisabled?: boolean;
/** The input type for a given field/operator, surfaced by {@link QueryManager.getRuleContext}. */
getInputType?: (field: string, operator: string, misc: { fieldData: F }) => InputType | null;
/** Extra props for a subquery builder, surfaced by {@link QueryManager.getRuleContext}. */
getSubQueryBuilderProps?: (field: string, misc: { fieldData: F }) => Record;
/**
* Enables undo/redo recording. Pass `true` for the defaults, or an object to configure
* `maxHistory` and/or `coalesceMs`. Disabled by default, so instances that never undo
* retain no extra references.
*/
history?: boolean | QueryHistoryOptions;
/**
* Throw a {@link QueryManagerError} when a mutation is aborted because its target could not
* be used. Disabled by default, in which case such mutations are silent no-ops. Can be
* overridden per call.
*/
strict?: boolean;
/**
* Called whenever a mutation is aborted, including for the non-error reasons
* `"same-location"` and `"no-change"`. Can be overridden per call.
*/
onInvalidTarget?: (info: AbortInfo) => void;
/**
* Deep-freeze everything the manager hands out—the query, the field list, the field map, and
* the combinator list—so accidental mutation throws in strict mode. Defaults to `true`.
*
* Pass `false` when the manager's output is handed to a framework that wraps objects in
* proxies (Vue `reactive`, Solid stores) or otherwise needs to mutate them. This also disables
* immer's auto-freeze for mutations made through the manager.
*
* The shallow copy returned by {@link QueryManager.getOptions} is frozen either way: it is a
* one-level copy that no framework proxy is placed inside, so freezing it costs nothing and
* still prevents callers from mutating the options snapshot they were handed.
*/
freeze?: boolean;
/** Validates the query. Defaults to {@link defaultValidator}. */
validator?: QueryValidator;
/** Generates `id` properties for new rules and groups. Defaults to {@link generateID}. */
idGenerator?: () => string;
/**
* Clock used to time history coalescing. Defaults to `Date.now`.
*
* @internal Test seam. Exists so that history recording can be compared against the
* `react-querybuilder/history` implementation without depending on wall-clock timing.
*/
now?: () => number;
}
```
> *Source: [/packages/core/src/utils/QueryManager.ts#L174-L321](https://github.com/react-querybuilder/react-querybuilder/blob/main/packages/core/src/utils/QueryManager.ts#L174-L321)*
The constructor also accepts the [guard options](#guards) `respectDisabled` (defaulting to **`true`** here, matching the `QueryBuilder` component), `queryDisabled`, and `maxLevels`, plus `resetOnFieldChange` (default `true`) and `resetOnOperatorChange` (default `false`), which mirror the props of the same names.
### Freezing (manager)[](#freezing-manager "Direct link to Freezing (manager)")
Everything the manager hands out directly—the query, the field list, the field map, and the combinator list—is deep-frozen. Pass `freeze: false` to disable that, along with immer's auto-freeze for mutations made through the manager:
```
const q = new QueryManager(query, { fields, freeze: false });
Object.isFrozen(q.getQuery()); // false
```
This is what makes a manager's output usable with a framework that wraps objects in proxies. The one exception is `getOptions()`, which is a one-level copy that no proxy is placed inside; it stays frozen either way, so callers can't mutate the options snapshot they were handed.
Note that under `freeze: false`, "a query previously handed out by `getQuery` is never modified" remains true—mutations still go through the non-`InPlace` tools—but it is a convention rather than a runtime-enforced guarantee.
### State access[](#state-access "Direct link to State access")
* `getQuery(): RuleGroupTypeAny` — The current query. The returned object is structurally shared, so it's safe to retain and compare by reference to detect changes. It's also frozen unless the [`freeze` option](#freezing-manager) is `false`.
* `setQuery(query: RuleGroupTypeAny)` — Replaces the current query, assigning `id`s as needed.
### Factories[](#factories "Direct link to Factories")
* `createRule(): RuleType` — Creates a rule using the configured fields, operators, and defaults, applying the same precedence rules as the `, config?: { replace?: boolean })` updates the manager's configuration in place, keeping the current query, the undo/redo history, and every subscriber. Use it to propagate new `translations`, `fields`, `operators`, and so on without discarding state:
```
q.reconfigure({ translations: { fields: { placeholderLabel: 'Choisir un champ' } } });
```
The incoming options are shallow-merged over the current ones, so keys left out are preserved. Passing a key explicitly as `undefined` resets it to its default. Object-valued options like `translations` are replaced wholesale rather than deep-merged—spread the current value in yourself to patch a single key. Pass `{ replace: true }` to discard the existing options entirely and start from the incoming set.
Related methods:
* `getOptions(): QueryManagerOptions` — The options currently in effect, as a frozen shallow copy. This one is frozen even under `freeze: false`; see [Freezing](#freezing-manager).
* `getConfigVersion(): number` — A counter incremented only when a `reconfigure` call changes the effective configuration; calls that resolve to the options already in effect leave it unchanged. Bound to the instance, so it can be passed directly to React's `useSyncExternalStore` alongside `subscribe`. The [`useQueryManager`](/docs/utils/hooks.md#usequerymanager) hook already does this.
note
`reconfigure` never rewrites the query, even when the new options no longer describe it—a rule whose `field` is not in the new `fields` list is left as-is. Call [`validate()`](#validation-and-export) to detect that, or `setQuery(getQuery())` to re-normalize.
A call that resolves to the configuration already in effect is a **no-op**: nothing is re-derived, `getConfigVersion()` does not change, and subscribers are not notified. Equality is structural for data and by identity for functions (see [`optionsEqual`](/docs/utils/framework-adapters.md#configuration)), so rebuilding the options object on every render—which every framework adapter does—does not force a reconfigure as long as the data is the same. Rebuilding a callback per render *does* count as a change; memoize it to avoid that. The comparison is against the merged options, or against the replacement under `{ replace: true }`, so `reconfigure({})` behaves like `reconfigure(getOptions())`.
Otherwise subscribers are notified once and `getConfigVersion()` is incremented. Inside a [batch](#batching) the options are applied immediately—configuration is not part of a batch's rollback—but the notification is deferred and merged into the batch's single notification. History options are honored immediately: lowering `maxHistory` trims the undo stack, and turning history off clears both stacks.
### Subscriptions[](#subscriptions "Direct link to Subscriptions")
`subscribe(listener: (change: SubscriptionChange) => void)` registers a listener called after every change to the query or the configuration, and returns a function that unregisters it. Mutations that resolve to a no-op do not notify, and a [batch](#batching) notifies once no matter how many changes it contains.
The listener receives a `SubscriptionChange`—`{ query: boolean; config: boolean }`, at least one of which is always `true`—describing what changed. A framework adapter can use it to skip work a given change does not affect (re-deriving option lists on a query-only change, say) instead of diffing the manager's output to find out. The argument is optional: a zero-argument listener, including `useSyncExternalStore`'s `onStoreChange`, is a valid listener.
| Notification source | `change` |
| ---------------------------------------- | -------------------------------- |
| Any mutation, `setQuery`, `undo`, `redo` | `{ query: true, config: false }` |
| `reconfigure` | `{ query: false, config: true }` |
| A batch containing both | `{ query: true, config: true }` |
The method is bound to the instance, so it is a stable reference across renders and can be passed directly to React's `useSyncExternalStore`. `getQuery` is bound as well, so it can serve as the snapshot getter without a wrapper:
```
const query = useSyncExternalStore(q.subscribe, q.getQuery);
```
In React, prefer the [`useQueryManager`](/docs/utils/hooks.md#usequerymanager) hook, which wraps this and handles creating the manager exactly once.
### Batching[](#batching "Direct link to Batching")
`batch(fn: () => void)` runs `fn`, deferring history recording and subscriber notification until it returns. The whole batch becomes a single undo step and triggers a single notification, or neither if the query ends up unchanged. Batches may be nested; only the outermost one commits.
If `fn` throws, the query and its history are restored to their pre-batch state and the error propagates, so a batch either applies completely or not at all.
[`undo()`, `redo()`, and `clearHistory()`](#undoredo) may be called inside a batch, and their notifications are deferred like everything else. Because they manage the history stacks themselves, a batch containing one of them records no entry of its own, leaving the stacks exactly as those methods left them.
```
q.batch(() => {
q.add(rule1);
q.add(rule2);
q.add(rule3);
}); // one notification, one undo step
```
### Strict mode[](#strict-mode "Direct link to Strict mode")
By default, a mutation whose target can't be used is a silent no-op (see [aborted operations](#aborted-operations)). Set `strict: true` to raise a `QueryManagerError` instead:
```
const q = new QueryManager(query, { fields, strict: true });
q.remove('no-such-id'); // throws QueryManagerError
```
The error carries a `code` (the [`AbortReason`](#aborted-operations)) and the full `info` object, so failures can be handled by kind rather than by message:
```
try {
q.remove(id);
} catch (error) {
if (error instanceof QueryManagerError && error.code === 'target-not-found') {
// ...
}
}
```
The two non-error reasons—`"same-location"` and `"no-change"`—never throw, so idempotent code (setting a value to what it already is, or dropping a rule where it started) keeps working under `strict`.
To observe aborted operations without changing control flow, use `onInvalidTarget`. It is called for *every* abort, including the non-error reasons, and runs before any `strict` throw, so an operation can be both observed and enforced:
```
const q = new QueryManager(query, {
fields,
onInvalidTarget: ({ reason, operation }) => logger.warn(`${operation}: ${reason}`),
});
```
Both options can be overridden per call, which takes precedence over the manager's own configuration:
```
q.remove(id, { strict: true }); // just this call
q.remove(id, { strict: false }); // opt out of a manager-wide strict setting
```
A `strict` throw inside [`batch`](#batching) rolls the whole batch back.
### Undo/redo[](#undoredo "Direct link to Undo/redo")
Recording is opt-in through the `history` option, so instances that never undo retain no extra references. Pass `true` for the defaults, or an object to configure `maxHistory` (default `50`) and/or `coalesceMs` (default `500`).
```
const q = new QueryManager(undefined, { fields, history: true });
```
* `undo()` / `redo()` — Restore the previous or most recently undone query. No-ops when the corresponding `can*` method returns `false`. Both notify subscribers.
* `canUndo(): boolean` / `canRedo(): boolean`
* `clearHistory()` — Discards all history without changing the current query.
* `getHistory(): { past, future }` — Copies of the recorded queries, `past` oldest first and `future` newest first.
`undo()`, `redo()`, and `clearHistory()` may be called inside a [batch](#batching); see [Batching](#batching) for how that interacts with the batch's own history entry.
Recording follows the same semantics as the [`react-querybuilder/history`](/docs/tips/undo-redo.md) entry point: consecutive changes to the same property of the same rule within `coalesceMs` are merged into a single undo step (so typing a value produces one entry rather than one per keystroke), structural changes never coalesce, and changes that alter no observable property are not recorded at all.
### Traversal[](#traversal "Direct link to Traversal")
`walk(options?)` is a generator yielding every rule and group in the query, depth-first in pre-order, starting with the root group itself. Combinator strings in independent-combinator queries are skipped.
Each entry is a `QueryNode`:
```
interface QueryNode {
node: RuleGroupTypeAny | RuleType;
path: Path;
parent: RuleGroupTypeAny | null; // `null` for the root group
}
```
```
for (const { node, path } of q.walk({ rulesOnly: true })) {
console.log(path, node.field);
}
```
`WalkOptions`:
| Option | Description |
| ------------ | ----------------------------------------------------------------------------------------------------------- |
| `from` | Traverse only the subtree at this `Path` or `id`, visiting that node first. Yields nothing if unresolvable. |
| `rulesOnly` | Visit only rules. Groups are still traversed, just not yielded (except as `parent`). |
| `groupsOnly` | Visit only groups. |
Derived methods:
* `rules(options?)` / `groups(options?)` — Shorthand for `walk` with `rulesOnly`/`groupsOnly`.
* `find(predicate, options?): QueryNode | null` — The first matching node.
* `filter(predicate, options?): QueryNode[]` — All matching nodes.
* `[Symbol.iterator]()` — Equivalent to `walk()` with no options, so a manager can be spread (`[...q]`) or used directly in `for...of`.
Traversal operates on the query as it was when iteration began, so mutating the manager mid-iteration does not affect a walk already in progress. Because generators are lazy, that snapshot is taken on the first iteration step rather than when `walk()` is called.
### Lookups[](#lookups "Direct link to Lookups")
These mirror the standalone [`findPath`](/docs/utils/misc.md#findpath) and [`findID`](/docs/utils/misc.md#findid) utilities, minus the trailing `query` parameter.
* `findPath(path: Path)` — The rule or group at `path`.
* `findID(id: string)` — The rule or group with the given `id`.
* `getPathOfID(id: string): Path | null` — The path of the rule or group with the given `id`.
* `pathIsDisabled(path: Path): boolean` — Whether the node at `path` is disabled, either itself or by an ancestor group.
Methods that accept *either* a path or an `id`, and narrow the result:
* `getNode(pathOrID)` — The rule or group.
* `getRule(pathOrID): RuleType | null` — `null` if the target is a group.
* `getGroup(pathOrID): RuleGroupTypeAny | null` — `null` if the target is a rule.
* `getParent(pathOrID): RuleGroupTypeAny | null` — The containing group, or `null` for the root group.
Unlike the standalone `findPath`, which can return `undefined` for an out-of-range index, all of these normalize an unresolvable target to `null`.
`findID`, `getPathOfID`, and the `pathOrID` forms above are backed by an `id`-to-`Path` index built once per query, so repeated lookups are constant time rather than a tree walk. The index is rebuilt automatically whenever the query changes, including via `undo`, `redo`, and a rolled-back `batch`.
note
`validate()` results are cached against the current query for the same reason. A custom `validator` with side effects, or one that depends on anything other than the query, may therefore run fewer times than expected.
### Rule configuration[](#rule-configuration "Direct link to Rule configuration")
These methods resolve the same field/operator configuration the `QueryBuilder` component uses, applying the same precedence rules (field-level properties first, then the corresponding `get*` option, then the manager-level defaults).
* `getFields(): FullOptionList` — The normalized field list, for populating a field selector.
* `getCombinators(): FullOptionList` — The normalized combinator list, for populating a combinator selector.
* `getFieldData(field): FullField` — The configured field. For an unconfigured field, returns the same minimal fallback (`{ name, value, label }`, all set to the field name) that `getRuleContext` reports as `fieldData`.
`getFields` and `getCombinators` return frozen arrays (unless the [`freeze` option](#freezing-manager) is `false`), so they are safe to hand to rendering code without defensive copying. Either way, treat them as read-only.
* `getOperators(field): FullOptionList` — The operator list for a field.
* `getValueSources(field, operator): ValueSourceFullOptions` — The available value sources.
* `getMatchModes(field): MatchModeOptions` — The available match modes.
* `getValues(field, operator): FullOptionList` — The value option list.
* `getValueEditorType(field, operator): ValueEditorType` — The value editor type.
When `autoSelectField`, `autoSelectOperator`, or `autoSelectValue` is `false`, an empty placeholder option is prepended to the corresponding list. Pass the `translations` option to control those placeholders exactly as the `translations` prop does for the `QueryBuilder` component—only the placeholder properties of `fields`, `operators`, and `values` are used, since the remaining keys describe UI elements that have no meaning outside the component. This matters beyond presentation: `placeholderName` becomes the `field`, `operator`, or `value` written into rules created by the manager, so a manager paired with a component should receive the same translations.
```
const q = new QueryManager(undefined, {
fields,
autoSelectField: false,
translations: { fields: { placeholderName: '#', placeholderLabel: 'Select a field' } },
});
q.createRule(); // => { field: '#', ... }
```
`getRuleContext(pathOrID)` resolves all of the above for a specific rule at once, plus its validation result, returning `null` when the target can't be resolved or isn't a rule.
```
interface RuleContext {
fieldData: FullField;
hideValueControls: boolean;
inputType: InputType | null;
matchModes: MatchModeOptions;
operatorObject: FullOperator | undefined;
operators: OptionList;
parameters: FlexibleOptionList | null;
validationResult: boolean | ValidationResult;
valueEditorType: ValueEditorType;
values: FlexibleOptionList ;
valueSourceOptions: ValueSourceFullOptions;
valueSources: ValueSources;
}
```
This is the same derivation the [`useRule`](/docs/utils/hooks.md#userule) hook performs—both call the shared `deriveRuleContext` utility—so a non-React implementation can render a rule without reimplementing the precedence rules.
```
const ctx = q.getRuleContext([0]);
// => { fieldData: { name: 'firstName', ... }, valueEditorType: 'text', valueSources: ['value'], ... }
```
`getRuleGroupContext(pathOrID)` is the equivalent for groups, defaulting to the root group. It returns `null` when the target can't be resolved or isn't a group.
```
interface RuleGroupContext {
combinator: string;
combinatorObject: FullCombinator | undefined;
combinators: FullOptionList;
/** The selected combinator's `className`, or `null` for independent combinators. */
combinatorBasedClassName: Classname | null;
independentCombinators: boolean;
validationResult: boolean | ValidationResult;
}
```
note
Unlike a rule, a group's `validationResult` comes *only* from the query-level validation map—there is no field-level validator fallback.
### Classnames[](#classnames "Direct link to Classnames")
`@react-querybuilder/core` also exports the classname derivations used by `useRule` and `useRuleGroup`, so an implementation in any framework can produce a byte-identical `class` attribute for every element:
* `deriveRuleClassNames({ classNames, suppressStandardClassnames })` — the per-element classnames for a rule (`fields`, `operators`, `value`, `removeRule`, and so on).
* `deriveRuleOuterClassName({ classNames, suppressStandardClassnames, ...state })` — the rule's wrapper classname, including conditional state classes for `disabled`, `muted`, drag-and-drop, subqueries, and validation.
* `deriveRuleGroupClassNames({ classNames, suppressStandardClassnames, ...dndState })` — the per-element classnames for a rule group, including its `header`.
* `deriveRuleGroupOuterClassName({ ... })` — the group's wrapper classname.
* `deriveRuleClassName(key, { ... })` — a single rule classname, for cases where only one is needed.
* `deriveQueryBuilderClassNames({ classNames, suppressStandardClassnames, disabled, validationResult })` — the query builder's own wrapper classname, including the conditional `disabled`, `valid`, and `invalid` classes. Only a `boolean` `validationResult` contributes a class; a `ValidationMap` describes individual rules and groups, not the query as a whole.
caution
A group's wrapper reflects **fewer** states than a rule's: `dndOver`, `dndCopy`, `dndDropNotAllowed`, and `hasSubQuery` apply to rules only. The two condition sets are declared separately for exactly this reason, so use the matching function rather than assuming symmetry.
Each takes the merged [`controlClassnames`](/docs/components/querybuilder.md#controlclassnames) object and returns plain strings.
Composition is declared as data rather than code: every derived classname names the `controlClassnames` keys that contribute to it (in application order, after the standard classname) plus any state-dependent classes. Conditional elements—the rule wrapper and the group `header`—use the same declaration, so there is no element a port can handle differently by accident.
```
interface ClassnameSpec {
sources: readonly (keyof Classnames)[];
conditions?: readonly { key; when; standardOnly? }[];
}
```
For each entry the result is the standard classname, then each `sources` entry, then each active condition's custom class, then a single object of active standard classes.
```
deriveRuleClassNames({ classNames: { valueSelector: 'vs', fields: 'f' } });
// => { fields: 'rule-fields vs f', operators: 'rule-operators vs', ... }
```
### Option resolvers and factories[](#option-resolvers-and-factories "Direct link to Option resolvers and factories")
The precedence rules the `QueryBuilder` component applies when resolving a rule's configuration are exported as standalone functions, so `useQueryBuilderSetup` and `QueryManager` share one implementation rather than each keeping its own:
* `resolveOperatorList({ field, fieldData, getOperators, operators, ... })` — the field's own `operators`, then `getOperators`, then the query-level list.
* `resolveDefaultOperator({ field, fieldData, getDefaultOperator, getOperators })` — the field's `defaultOperator`, then `getDefaultOperator` (string or function), then the first available operator.
* `resolveValueEditorType({ field, operator, fieldData, getValueEditorType })` — the field's `valueEditorType` (string or function of the operator), then `getValueEditorType`, then `"text"`.
* `resolveValueList({ field, operator, fieldData, getValues, ... })` — the field's own `values`, then `getValues`, then an empty list.
* `createRule(options)` / `createRuleGroup(options, independentCombinators?)` — build a new rule or group from that configuration.
Each accepts an optional `placeholder` so a UI layer can supply translated placeholder options; omit it where translations don't apply.
note
`createRule` computes `value` in a second pass, once `field`, `operator`, and `valueSource` are known, since the default value depends on all three. `createRuleGroup` generates the group's own `id` *before* any contained rule's — observable when `idGenerator` is deterministic.
### Value editors[](#value-editors "Direct link to Value editors")
The logic behind the [`useValueEditor`](/docs/utils/hooks.md#usevalueeditor) hook is exported separately, since a value editor is the control an implementation is most likely to rewrite:
* `getValueEditorReset({ skipHook, type, operator, value, inputType })` — returns `{ reset, value }`. A rule's `value` must collapse to a single element when it's an array (or a comma-containing string in a `number` input) but the operator is no longer one of `between`/`notBetween`/`in`/`notIn` and the editor isn't a multiselect. React applies this in an effect; apply it wherever is idiomatic.
* `getMultiValueUpdate({ value, index, valueAsArray, operator, values, listsAsArrays, parseNumberMethod })` — the next value when the editor at `index` in a series changes. For `between`/`notBetween`, editing the first bound guarantees an array of at least two elements, seeding the second from the first available option.
* `coerceBigIntValue(value, parseNumberMethod)` — a `bigint`, falling back to the parsed number when the value can't be represented as one.
* `coerceInputType(inputType, operator)` — the `type` an `
q.getQuery(); // unchanged
```
`transform(options?)` runs [`transformQuery`](/docs/utils/misc.md#transformquery) against the current query and returns its result directly, rather than a new manager — `transformQuery` can produce arbitrary shapes that are no longer valid queries. The manager is never modified.
```
q.transform({ propertyMap: { combinator: 'AndOr' } });
```
---
# Validation
> *Refer to the [TypeScript reference](/docs/typescript.md) page for information about the types and interfaces referenced below.*
`react-querybuilder` provides two methods for validating queries: query-level validation and field-based validation.
## Query-level validation[](#query-level-validation "Direct link to Query-level validation")
Query-level validation can treat the entire query as valid or invalid, or you can report validation results for specific rules/groups within the query based on the `id` property.
To mark an entire query as valid or invalid, return a `boolean` value from the `validator` callback function (`true` for valid, `false` for invalid).
```
import { QueryBuilder, RuleGroupType } from 'react-querybuilder';
/**
* This function returns false (indicating "invalid") when no rules are present.
*/
const validator = (q: RuleGroupType) => q.rules.length > 0;
const App = () => {
return ` for each evaluated query object (rule, group, or entire query) will be assigned one of two classes: `queryBuilder-valid` or `queryBuilder-invalid`. You can use these classes to style the elements with CSS.
See it in action
In the [demo](/demo#validateQuery=true), check the "Use validation" option and create an empty group or text input without a value. Empty groups will show a message where rules usually appear (using the `:after` pseudo-selector), and text fields without values will have a [purple](https://meyerweb.com/eric/thoughts/2014/06/19/rebeccapurple/) background.
## Effect on exports[](#effect-on-exports "Direct link to Effect on exports")
See the [validation section on the Export page](/docs/utils/export.md#validation) for more information.
## Default validator[](#default-validator "Direct link to Default validator")
You can pass the provided [`defaultValidator`](/docs/utils/misc.md#defaultvalidator) to the `validator` prop to check for invalid combinators, empty groups, or (if the query uses independent combinators) out-of-sequence `rules` arrays. The [demo](/demo) uses the default validator.
---