User-friendly React component to build queries (filters).
Inspired by [jQuery QueryBuilder](http://querybuilder.js.org/).
Using awesome UI frameworks for widgets: [Ant Design](https://ant.design/), [Material-UI](https://mui.com/), [Bootstrap](https://reactstrap.github.io/).
Now [Fluent UI](https://developer.microsoft.com/en-us/fluentui#/get-started/web) is also supported!
See [live demo](https://ukrbublik.github.io/react-awesome-query-builder)
* [Features](#features)
* [Getting started](#getting-started)
* [Demo apps](#demo-apps)
* [Usage](#usage)
* [Minimal JavaScript example with class component](#minimal-javascript-example-with-class-component)
* [Minimal TypeScript example with function component](#minimal-typescript-example-with-function-component)
* [API](#api)
* [Query](#query-)
* [Builder](#builder-)
* [Utils](#utils)
* [Save/load tree](#saveload-tree)
* [Validation utils](#validation-utils)
* [Export](#export-utils)
* [Import](#import-utils)
* [Save/load config from server](#saveload-config-from-server)
* [Config format](#config-format)
* [Validation](#validation)
* [i18n](#i18n)
* [Ternary mode](#ternary-mode)
* [SSR](#ssr)
* [ctx](#ctx)
* [Versions](#versions)
* [Changelog](#changelog)
* [Migration to 6.5.0](#migration-to-650)
* [Migration to 6.4.0](#migration-to-640)
* [Migration to 6.3.0](#migration-to-630)
* [Migration to 6.2.0](#migration-to-620)
* [Migration to 6.0.0](#migration-to-600)
* [Migration to 5.2.0](#migration-to-520)
* [Migration to 4.9.0](#migration-to-490)
* [Migration from v1 to v2](#migration-from-v1-to-v2)
* [Contributing](#contributing)
* [Code Contributing](#code-contributing)
* [Financial Contributing](#financial-contributing)
### React-Awesome-Query-Builder AI Bot
[React-Awesome-Query-Builder](https://codeparrot.ai/oracle?owner=ukrbublik&repo=react-awesome-query-builder) Bot will help you understand this repository better. You can ask for code examples, installation guide, debugging help and much more.
### Features
* Highly configurable.
You can configure fields, types, operators, functions, widgets, behavior settings etc.
* Fields can have simple type (string, number, bool, date/time, list), custom or complex (structs, arrays)
* Aggregation is supported (query like "COUNT OF users WHERE (role == 'Manager' AND department == 'Development') > 5")
* Fields can be compared with other fields
* Comparison operators can be: binary (== != < >), unary ('is null'), 'between' or complex operators like 'proximity'
* Functions are supported in both LHS and RHS.
Functions nesting is supported (function argument can be a function)
* [Ternary mode](#ternary-mode) (if-then-else)
* Export to MongoDb, SQL, [JsonLogic](http://jsonlogic.com), [SpEL](https://docs.spring.io/spring-framework/docs/3.2.x/spring-framework-reference/html/expressions.html), ElasticSearch or your custom format
* Import from [JsonLogic](http://jsonlogic.com), [SpEL](https://docs.spring.io/spring-framework/docs/3.2.x/spring-framework-reference/html/expressions.html), SQL
* Reordering (drag-n-drop) support for rules and groups of rules
* Query value and config can be saved/loaded from server
* Themes: [Ant Design](https://ant.design/), [Material-UI](https://mui.com/), [Bootstrap](https://reactstrap.github.io/), [Fluent UI](https://developer.microsoft.com/en-us/fluentui), vanilla
It is possible to use another UI framework of your choice, see [how-to](/CONTRIBUTING.md#other-ui-frameworks)
* TypeScript support (see [types](/packages/core/modules/index.d.ts) and [demo in TS](/packages/examples))
## Getting started
From v6 library is divided into packages:
- [`@react-awesome-query-builder/core`](/packages/core) - has core functionality to import/export/store query, provides utils
- [`@react-awesome-query-builder/ui`](/packages/ui) - has core React components like `` `` and CSS, provides config with basic (vanilla) widgets
- [`@react-awesome-query-builder/antd`](/packages/antd) - provides config with [Ant Design](https://ant.design/) widgets
- [`@react-awesome-query-builder/mui`](/packages/mui) - provides config with [MUI](https://mui.com/) widgets
- [`@react-awesome-query-builder/material`](/packages/material) - provides config with [Material-UI v4](https://v4.mui.com/) widgets (deprecated)
- [`@react-awesome-query-builder/bootstrap`](/packages/bootstrap) - provides config with [Bootstrap](https://reactstrap.github.io/) widgets
- [`@react-awesome-query-builder/fluent`](/packages/fluent) - provides config with [Fluent UI](https://developer.microsoft.com/en-us/fluentui) widgets
```mermaid
graph LR;
core-->ui;
core-->sql((sql));
ui-->antd;
ui-->mui;
ui-->material;
ui-->bootstrap;
ui-->fluent;
```
`ui` re-exports from `core`, other packages re-export from `ui`.
For using this library on frontend you need to install and use only `ui` (for basic widgets) or one of framework-specific packages (`antd` / `mui` / `bootstrap` / `fluent`).
For using this library on server-side (Node.js) you need only `core`.
This is useful if you want to pass query value from frontend to backend in JSON format and perform [export](#export-utils) eg. to SQL on server-side for security reasons.
Example of installation if you use [MUI](https://mui.com/):
```
npm i @react-awesome-query-builder/mui --save
```
Note: We use [pnpm](https://pnpm.io/). If you want to clone this project and run scripts, please [install pnpm](https://pnpm.io/installation):
```
npm install -g pnpm
```
See [basic usage](#usage) for minimum code example.
See [API](#api) and [config](#config-format) for documentation.
## Demo apps
- [`pnpm start`](/packages/examples) - demo app with hot reload of demo code and local library code, uses TS, uses complex config to demonstrate anvanced usage, uses all supported UI frameworks.
- [`pnpm sandbox-ts`](/packages/sandbox) - simple demo app, built with Vite, uses TS, uses MUI widgets.
- [`pnpm sandbox-js`](/packages/sandbox_simple) - simplest demo app, built with Vite, not uses TS, uses vanilla widgets.
- [`pnpm sandbox-next`](/packages/sandbox_next) - advanced demo app with server side, built with Next.js, uses TS, uses MUI widgets, has API to save/load query value and query config from storage.
## Usage
#### Minimal JavaScript example with class component
```
…
```
#### Minimal TypeScript example with function component
```
…
```
# API
## ``
Props:
- `{...config}` - destructured [`CONFIG`](/CONFIG.adoc)
- `value` - query value in internal [Immutable](https://immutable-js.github.io/immutable-js/) format
- `onChange` - callback called when query value changes. Params: `value` (in Immutable format), `config`, `actionMeta` (details about action which led to the change, see `ActionMeta` in [`index.d.ts`](/packages/core/modules/index.d.ts)), `actions` (you can use to run actions programmatically, see `Actions` in [`index.d.ts`](/packages/core/modules/index.d.ts)).
- `onInit` - callback called before initial render, has same arguments as `onChange` (but `actionMeta` is undefined)
- `renderBuilder` - function to render query builder itself. Takes 1 param `props` you need to pass into ``.
*Notes*:
- Please apply `useCallback` for `onChange` and `renderBuilder` for performance reason
- If you put query builder component inside [Material-UI](https://github.com/mui-org/material-ui)'s `` or ``, please:
- use prop `disableEnforceFocus={true}` for dialog or popver
- set css `.MuiPopover-root, .MuiDialog-root { z-index: 900 !important; }` (or 1000 for AntDesign v3)
- If you put query builder component inside [Fluent-UI](https://developer.microsoft.com/en-us/fluentui)'s ``, please:
- set css `.ms-Layer.ms-Layer--fixed.root-119 { z-index: 900 !important; }`
- `props` arg in `renderBuilder` have `actions` and `dispatch` you can use to run actions programmatically
- For a list of available actions see `Actions` interface in [`index.d.ts`](/packages/core/modules/index.d.ts). See `runActions()` in [examples](/packages/examples/src/demo/index.tsx) as a demonstration of calling actions programmatically.
## ``
Render this component only inside `Query.renderBuilder()` like in example above:
```js
renderBuilder = (props) => (
)
```
Wrapping `` in `div.query-builder` is **necessary** for drag-n-drop support.
Optionally you can add class `.qb-lite` to it for showing action buttons (like delete rule/group, add, etc.) only on hover, which will look cleaner.
Wrapping in `div.query-builder-container` is necessary for correct drag-n-drop support if you put query builder inside scrollable block.
## `Utils`
### Save/load tree
#### `getTree`
`Utils.getTree (immutableValue, light = true, children1AsArray = true) -> Object`
Convert query value from internal Immutable format to JS object.
You can use it to save value on backend in `onChange` callback of ``.
Tip: Use `light = false` in case if you want to store query value in your state in JS format and pass it as `value` of `` after applying `loadTree()` (which is not recommended because of double conversion). See issue [#190](https://github.com/ukrbublik/react-awesome-query-builder/issues/190)
#### `loadTree`
`Utils.loadTree (jsValue) -> Immutable`
Convert query value from JS format to internal Immutable format.
You can use it to load saved value from backend and pass as `value` prop to ``.
### Validation utils
#### `isValidTree`
`Utils.isValidTree (immutableValue, config) -> Boolean`
If `showErrorMessage` in config.settings is true, use this method to check if query has validation errors (presented in UI with red text color under the rule).
Note that incomplete rules or empty groups are not counted as validation errors for this function.
If `showErrorMessage` is false, this function will always return true.
#### `validateTree`
`Utils.validateTree (immutableValue, config, options?) -> Array`
Validates immutable query value to check it corresponds to the config and has no parts that are invalid or incomplete.
Returns array of errors *grouped by item in tree*.
Each array element is `{ itemStr, itemPositionStr, errors, path }` (see type [`ValidationItemErrors`](/packages/core/modules/index.d.ts)).
To present item for user you can use `itemStr` (string representation of rule eg. `Number > 55`) and `itemPositionStr` (eg. `Rule #4 (index path: 1, 2)`).
Also you can use `path` to get raw item data with `Utils.TreeUtils.getItemByPath(tree, path)` *(advanced)*.
`errors` is an array of objects `{ str, key, args, side, delta }` (see type [`ValidationError`](/packages/core/modules/index.d.ts)).
`str` is an error message translated with [i18next.t(key, args)](https://www.i18next.com/overview/api#t) (namespace is `raqbvalidation`).
`side` can be one of `rhs` or `lhs`.
`delta` can be 0 or 1 for `between` operator.
You can override/extend translations with:
`Utils.i18n.addResources("en", "raqbvalidation", { ...yourTranslations })`
See default [validation translations](/packages/core/modules/i18n/validation/translations.js).
See [i18n for validation](#validation-translations).
#### `sanitizeTree`
`Utils.sanitizeTree (immutableValue, config, options?) -> { fixedTree, fixedErrors, nonFixedErrors }`
Validates and modifies immutable query value to ensure it corresponds to the config and has no parts that are invalid or incomplete.
Invalid rules (eg. if field is not found in config) will always be deleted.
Invalid values (eg. value > max or < min, value not passing `validateValue()` in field config) will be either:
- always deleted if `showErrorMessage` in config.settings is false
- fixed (i