Has 7 sections:
{conjunctions, operators, widgets, types, funcs, settings, fields}
Each section is described below.
Usually it’s enough to just reuse basic config, provide your own fields and maybe change some settings.
Optionally you can override some options in basic config or add your own types/widgets/operators (or even conjunctions like XOR or NOR).
There are functions for building query string: formatConj
, formatValue
, formatOp
, formatField
, formatFunc
which are used for QbUtils.queryString()
.
They have common param isForDisplay
- false by default, true will be used for (QbUtils.queryString(immutableTree, config, true)
(see 3rd param true).
Also there are similar mongoConj
, mongoFormatOp
, mongoFormatValue
, mongoFunc
for building MongoDb query with QbUtils.mongodbFormat()
.
And sqlFormatConj
, sqlFormatOp
, sqlFormatValue
, sqlFormatReverse
, sqlFunc
for building SQL where query with QbUtils.sqlFormat()
.
And jsonLogic
for building JsonLogic with QbUtils.jsonLogicFormat()
.
💡
|
Example: demo config
|
-
Use
BasicConfig
for simple vanilla UI -
Use
AntdConfig
for more advanced UI with AntDesign widgets -
Use
MaterialConfig
for Material-UI widgets
import {BasicConfig} from 'react-awesome-query-builder'; import AntdConfig from 'react-awesome-query-builder/lib/config/antd'; import MaterialConfig from 'react-awesome-query-builder/lib/config/material'; const InitialConfig = BasicConfig; // or AntdConfig or MaterialConfig const myConfig = { ...InitialConfig, // reuse basic config fields: { stock: { label: 'In stock', type: 'boolean', }, // ... my other fields } };
What is in basic config?
const {
conjunctions: {
AND,
OR
},
operators: {
equal,
not_equal,
less,
less_or_equal,
greater,
greater_or_equal,
like,
not_like,
starts_with,
ends_with,
between,
not_between,
is_empty,
is_not_empty,
select_equals, // like `equal`, but for select
select_not_equals,
select_any_in,
select_not_any_in,
multiselect_equals, // like `equal`, but for multiselect
multiselect_not_equals,
proximity, // complex operator with options
},
widgets: {
text,
textarea,
number,
slider,
rangeslider, // missing in `BasicConfig`
select,
multiselect,
treeselect, // missing in `BasicConfig` and in `MaterialConfig`
treemultiselect, // missing in `BasicConfig` and in `MaterialConfig`
date,
time,
datetime,
boolean,
field, // to compare field with another field of same type
func, // to compare field with result of function
},
types: {
text,
number,
date,
time,
datetime,
select,
multiselect,
treeselect,
treemultiselect,
boolean,
},
settings
} = AntdConfig;
Example:
{
// simple
qty: {
type: 'number',
label: 'Quantity',
fieldSettings: {
min: 0,
max: 100,
}
},
// complex
user: {
type: '!struct', // special keyword for comlex fields
label: 'User',
subfields: {
// subfields of complex field
name: {
type: 'text',
label: 'Name',
label2: 'User name', //optional, see below
fieldSettings: {
validateValue: (val, _fieldSettings) => (val.length <= 20),
}
},
},
},
...
}
key | required | default | meaning |
---|---|---|---|
|
+ |
One of types described in config.types or |
|
|
|||
|
+ for |
Config for subfields of complex field (multiple nesting is supported) |
|
|
+ |
Label to be displayed in field list |
|
|
Can be optionally specified for nested fields. |
||
|
Optional tooltip to be displayed in field list by hovering on item |
||
|
Settings for widgets, will be passed as props. Example: |
||
|
+ for (multi)select, tree (multi)select |
List of values for (multi)select widget. |
|
|
Function to validate entered value. Return true/false or error string / null. |
||
|
- for |
false |
If true, user can provide own options in multiselect, otherwise they will be limited to |
|
- for (multi)select, tree (multi)select |
false |
Show search (autocomplete)? |
|
- for |
false |
Whether to expand all nodes by default |
|
- for |
true |
Can select only leafs or any node? |
|
- for |
Async function to load list of options for |
|
|
- for |
false |
If true, |
|
- for |
false |
If true, |
|
Default value |
||
|
See usecase at |
||
|
You can override config of corresponding type (see below at section config.types) |
||
|
Shorthand for |
||
|
Can exclude some operators. Example: |
||
|
If comparing with funcs is enabled for this field ( |
||
|
false |
If true, field will appear only at right side (when you compare field with another field) |
|
|
false |
If true, field will appear only at left side |
|
|
For type= |
Example:
import ru_RU from 'antd/lib/locale-provider/ru_RU';
import { ruRU } from '@material-ui/core/locale';
import AntdWidgets from 'react-awesome-query-builder/lib/components/widgets/antd';
import {Widgets} from 'react-awesome-query-builder';
const { FieldCascader, FieldDropdown, FieldTreeSelect } = AntdWidgets;
{
valueSourcesInfo: {
value: {
label: "Value"
},
field: {
label: "Field",
widget: "field",
},
func: {
label: "Function",
widget: "func",
}
},
locale: {
moment: 'ru',
antd: ru_RU,
material: ruRU,
},
renderField: (props) => <FieldCascader {...props} />,
renderOperator: (props) => <FieldDropdown {...props} />,
renderFunc: (props) => <FieldDropdown {...props} />,
canReorder: true,
canRegroup: true,
maxNesting: 10,
showLabels: false,
showNot: true,
setOpOnChangeField: ['keep', 'default'],
customFieldSelectProps: {
showSearch: true
},
...
}
Behaviour settings:
key | default | meaning |
---|---|---|
|
|
By default fields can be compared with values. |
|
false |
Show error message in QueryBuilder if validateValue() in field config returns false |
|
true |
Activate reordering support for rules and groups of rules? |
|
true |
Allow move rules (or groups) in/out groups during reorder? |
|
true |
Show |
|
Maximum number of rules which can be added to the query builder |
|
|
Max nesting for rule groups. |
|
|
true |
Leave empty group after deletion or add 1 clean rule immediately? |
|
false |
Not allow to add/delete rules or groups, but allow change |
|
false |
Not allow to change fields |
|
false |
Not allow to change operators |
|
false |
Not allow to change values |
|
false |
Clear value on field change? false - if prev & next fields have same type (widget), keep |
|
false |
Clear value on operator change? |
|
|
Strategies for selecting operator for new field (used by order until success): |
|
For |
|
|
|
Operators usable in |
💡
|
For fully read-only mode use these settings: |
immutableGroupsMode: true,
immutableFieldsMode: true,
immutableOpsMode: true,
immutableValuesMode: true,
canReorder: false,
canRegroup: false,
Render settings:
key | default | meaning |
---|---|---|
|
|
Size of AntDesign components - |
|
|
Render fields list |
|
|
Render operators list |
|
|
Render functions list |
|
Other internal render functions you can override if using another UI framework (example) |
|
|
false |
Show labels above all fields? |
|
100 |
To shorten long labels of fields/values (by length, i.e. number of chars) |
|
|
Placement of antdesign’s dropdown pop-up menu |
|
|
You can pass props to |
|
|
You can change the position of the group actions to the following: |
|
||
|
||
|
||
|
||
|
|
Width for slider |
|
|
Width for select |
|
|
Width for search in autocomplete |
|
5 |
Max rows for textarea |
Other settings:
key | default | meaning |
---|---|---|
|
"en" |
Locale (string or array of strings) used for moment |
|
|
Locale object used for AntDesign widgets |
|
|
Locale object used for MaterialUI widgets |
|
{} |
Options for createMuiTheme |
|
Function for formatting query string, used to format rule with reverse operator which haven’t |
|
|
Function for formatting query string, used to format field |
|
|
Function for formatting query string, used to format aggregation rule (like |
|
|
|
Separator for struct fields. |
|
|
Separator for struct fields in UI. |
Localization:
key | default |
---|---|
|
Value |
|
Value |
|
Field |
|
Operator |
|
Function |
|
Select field |
|
Select function |
|
Select operator |
|
|
|
|
|
Add group |
|
Add rule |
|
Add sub rule |
|
Not |
|
Select value source |
|
If you want to ask confirmation of removing non-empty rule/group, add these options. |
|
Are you sure delete this rule? |
|
Yes |
|
|
|
Are you sure delete this group? |
|
Yes |
|
|
{
AND: {
label: 'And',
formatConj: (children, _conj, not) => ( (not ? 'NOT ' : '') + '(' + children.join(' || ') + ')' ),
reversedConj: 'OR',
mongoConj: '$and',
},
OR: {...},
}
where AND
and OR
- available conjuctions (logical operators). You can add NOR
if you want.
key | required | meaning |
---|---|---|
|
+ |
Label to be displayed in conjunctions swicther |
|
+ |
Function for formatting query, used to join rules into group with conjunction. |
|
+ for MongoDB format |
Name of logical operator for MongoDb |
|
+ for SQL format |
See |
|
Opposite logical operator. |
{
equal: {
label: 'equals',
reversedOp: 'not_equal',
labelForFormat: '==',
cardinality: 1,
formatOp: (field, _op, value, _valueSrc, _valueType, opDef) => `${field} ${opDef.labelForFormat} ${value}`,
mongoFormatOp: (field, op, value) => ({ [field]: { '$eq': value } }),
},
..
}
key | required | default | meaning |
---|---|---|---|
|
+ |
Label to be displayed in operators select component |
|
|
+ |
Opposite operator. |
|
|
1 |
Number of right operands (1 for binary, 2 for |
|
|
+ |
Function for formatting query string, used to join operands into rule. |
|
|
If |
||
|
+ for MongoDB format |
Function for formatting MongoDb expression, used to join operands into rule. |
|
|
+ for SQL format |
Operator name in SQL |
|
|
- for SQL format |
Function for advanced formatting SQL WHERE query if just |
|
|
+ for JsonLogic |
String (eg. |
|
|
+ for |
Labels to be displayed on top of 2 values widgets if |
|
|
+ for |
Labels to be displayed before each 2 values widgets |
|
|
Special for |
ℹ️
|
There is also special import {Operators: {ProximityOperator}} from 'react-awesome-query-builder'; See |
import {Widgets} from 'react-awesome-query-builder';
import AntdWidgets from 'react-awesome-query-builder/lib/components/widgets/antd';
import MaterialWidgets from 'react-awesome-query-builder/lib/components/widgets/material';
const {
TextWidget,
NumberWidget,
...
} = AntdWidgets;
const {
VanillaTextWidget,
VanillaNumberWidget,
...
} = Widgets;
const {
MaterialTextWidget,
MaterialNumberWidget,
...
} = MaterialWidgets;
{
text: {
type: 'text',
valueSrc: 'value',
factory: (props) => <TextWidget {...props} />,
formatValue: (val, _fieldDef, _wgtDef, isForDisplay) => (isForDisplay ? '"' + val + '"' : JSON.stringify(val)),
mongoFormatValue: (val, _fieldDef, _wgtDef) => (val),
// Options:
valueLabel: "Text",
valuePlaceholder: "Enter text",
// Custom props (https://ant.design/components/input/):
customProps: {
maxLength: 3
},
},
..
},
key | required | default | meaning |
---|---|---|---|
|
+ |
One of types described in config.types |
|
|
+ |
React function component |
|
|
+ |
Function for formatting widget’s value in query string. |
|
|
- for MongoDB format |
v ⇒ v |
Function for formatting widget’s value in MongoDb query. |
|
- for SQL format |
|
Function for formatting widget’s value in SQL WHERE query. |
|
- for JsonLogic |
v ⇒ v |
Function for formatting widget’s value for JsonLogic. |
|
|
Common option, text to be placed on top of widget if |
|
|
|
Common option, placeholder text to be shown in widget for empty value |
|
|
Option for |
||
|
Option for |
||
|
|
Option for |
|
|
|
Option for |
|
|
|
Option for Material-UI date/time pickers, |
|
|
|
Option for |
|
|
Option for |
||
|
Option for |
||
|
You can pass any props directly to widget with |
ℹ️
|
There is special field widget, rendered by <ValueFieldWidget> .It can be used to compare field with another field of same type. To enable this feature set valueSources of type to ['value', 'field'] (see below in config.types).
|
ℹ️
|
There is special func widget, rendered by <FuncWidget> .It can be used to compare field with result of function (see config.funcs). To enable this feature set valueSources of type to ['value', 'func'] (see below in config.types).
|
{
time: {
valueSources: ['value', 'field', 'func'],
defaultOperator: 'equal',
widgets: {
time: {
operators: ['equal', 'between'],
widgetProps: {
valuePlaceholder: "Time",
timeFormat: 'h:mm:ss A',
use12Hours: true,
},
opProps: {
between: {
valueLabels: ['Time from', 'Time to'],
},
},
},
},
},
..
}
key | required | default | meaning |
---|---|---|---|
|
keys of |
Array with values |
|
|
If specified, it will be auto selected when user selects field |
||
|
+ |
Available widgets for current type and their config. |
|
|
List of operators for widget, described in config.operators |
||
|
Can be used to override config of corresponding widget specified in config.widgets. Example: |
||
|
Can be used to override config of operator for widget. Example: |
{
lower: {
label: 'Lowercase',
sqlFunc: 'LOWER',
mongoFunc: '$toLower',
returnType: 'text',
args: {
str: {
type: 'text',
valueSources: ['value', 'field'],
}
}
},
..
}
key | required | default | meaning |
---|---|---|---|
|
+ |
One of types described in config.types |
|
|
same as func key |
Label to be displayed in functions list |
|
|
Example result: for |
Function for formatting func expression in query rule. |
|
|
- for SQL format |
same as func key |
Func name in SQL |
|
- for SQL format |
Can be used instead of |
|
|
- for MongoDB format |
same as func key |
Func name in Mongo |
|
false |
||
|
- for MongoDB format |
Can be used instead of |
|
|
+ for JsonLogic |
String (function name) or function with 1 param - args object |
|
|
Function to convert given JsonLogic expression to array of arguments of current function. If given expression can’t be parsed into current function, throw an error. |
||
|
Arguments of function. Config is almost same as for simple fields |
||
|
arg’s key |
Label to be displayed in arg’s label or placeholder (if |
|
|
+ |
One of types described in config.types |
|
|
keys of |
Array with values |
|
|
Default value |
||
|
+ for (multi)select, tree (multi)select widgets |
List of values for Select widget. |
|
|
Settings for widgets, will be passed as props. Example: |
||
|
false |
Last args can be optional |
|
|
|
Can render custom function brackets in UI (or not render). |
|
|
|
Can render custom arguments separators in UI (other than |