CONFIG.adoc

Table of Contents

• Config format
  • Basic config
  • Sections
    • config.fields
    • config.settings
    • config.conjunctions
    • config.operators
    • config.widgets
    • config.types
    • config.funcs
    • config.ctx
    • Serialize entire config to string

Config format

Has 8 sections:

{conjunctions, operators, widgets, types, funcs, settings, fields, ctx}

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, mongoFormatFunc, mongoArgsAsObject for building MongoDb query with QbUtils.mongodbFormat().
And sqlFormatConj, sqlOp, sqlFormatOp, sqlFormatValue, sqlFormatReverse, formatSpelField, sqlFunc, sqlFormatFunc for building SQL where query with QbUtils.sqlFormat().
And spelFormatConj, spelOp, spelFormatOp, spelFormatValue, spelFormatReverse, spelFunc, spelFormatFunc for building query in (Spring Expression Language (SpEL) with QbUtils.spelFormat().
And jsonLogic for building JsonLogic with QbUtils.jsonLogicFormat().

💡	Example 1: config for sandbox_simple

💡	Example 2: config for sandbox

 

Basic config

• Use BasicConfig for simple vanilla UI

• Use AntdConfig for more advanced UI with AntDesign widgets

• Use MuiConfig for MUI widgets

• Use MaterialConfig for Material-UI v4 widgets

• Use BootstrapConfig for Bootstrap widgets

• Use FluentUIConfig for Fluent UI widgets

import {BasicConfig} from '@react-awesome-query-builder/ui';
import {AntdConfig} from '@react-awesome-query-builder/antd';
import {MuiConfig} from '@react-awesome-query-builder/mui';
import {MaterialConfig} from '@react-awesome-query-builder/material';
import {BootstrapConfig} from "@react-awesome-query-builder/bootstrap";
import {FluentUIConfig} from "@react-awesome-query-builder/fluent";
const InitialConfig = BasicConfig; // or AntdConfig or MuiConfig or BootstrapConfig or FluentUIConfig

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_null,
    is_not_null,
    is_empty,
    is_not_empty,
    select_equals, // like `equal`, but for select
    select_not_equals,
    select_any_in,
    select_not_any_in,
    multiselect_contains,
    multiselect_not_contains,
    multiselect_equals, // like `equal`, but for multiselect
    multiselect_not_equals,
    proximity, // complex operator with options
  },
  widgets: {
    text,
    textarea,
    number,
    slider,
    rangeslider, // missing in `BasicConfig`, `BootstrapConfig`, `FluentUIConfig`
    select,
    multiselect,
    treeselect, // present only in `AntdConfig`
    treemultiselect, // present only in `AntdConfig`
    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,
  ctx,
} = AntdConfig;

 

Sections

config.fields

Example:

{
  // simple
  qty: {
    type: 'number',
    label: 'Quantity',
    fieldSettings: {
      min: 0,
      max: 100,
    }
  },
  // complex
  user: {
    type: '!struct', // special keyword for complex 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
type	+		One of types described in config.types or !struct/!group for complex field (use !struct for objects, !group for arrays)
mode			For !group type, values are: some/array some is light mode (default), at least one subrule should match (for export elemMatch will be used in MongoDb, some in JsonLogic) array is extended mode, user can choose one of group operators (some/all/none/count >/</==/…​)
subfields	+ for !struct/!group type		Config for subfields of complex field (multiple nesting is supported)
label	+		Label to be displayed in field list (If not specified, fields’s key will be used instead)
label2			Can be optionally specified for nested fields. By default, if nested field is selected (eg. name of user in example above), <FieldDropdown> component will show name. Just name can be confusing, so can be overriden by setting label2 to something like User name. As alternative, you can use <FieldCascader> component which handles nested fields right. See renderField in settings.
fieldName			By default field name for export is constructed from current feild key and ancestors keys joined by settings.fieldSeparator. You can override this by specifying fieldName
tooltip			Optional tooltip to be displayed in field list by hovering on item
fieldSettings			Settings for widgets, will be passed as props. Example: {min: 1, max: 10} Available settings for Number and Slider widgets: min, max, step. Slider also supports marks (example: { 0: "0%", 100: "100%" }). Available settings for date/time widgets: timeFormat, dateFormat, valueFormat, use12Hours, useKeyboard. Available settings for text widget: maxLength, maxRows.
fieldSettings.listValues	+ for (multi)select		List of values for (multi)select widget. Example: [{value: 'yellow', title: 'Yellow'}, {value: 'green', title: 'Green'}] (or alternatively { yellow: 'Yellow', green: 'Green' }) You can also use groupTitle to group values. Example: [{value: 'red', groupTitle: 'Warm colors'}, {value: 'orange', groupTitle: 'Warm colors'} …​]
fieldSettings.treeValues	+ for tree (multi)select		List of values for tree (multi)select widget. Example: [{value: 'warm', title: 'Warm colors'}, {value: 'red', title: 'Red', parent: 'warm'}, {value: 'orange', title: 'Orange', parent: 'warm'}] (or alternatively [{value: 'warm', title: 'Warm colors', children: [ {value: 'red', title: 'Red'}, {value: 'orange', title: 'Orange'} ]}])
fieldSettings.validateValue			Function to validate input value. Simple way: return true/false. Advanced: if value is valid, return null, otherwise return error string or object {error, fixedValue?}. error can be a string or an object {key, args} to use i18n. `(val: any, fieldSettings: Object) ⇒ boolean | string | {error: string
Object, fixedValue?: any} | null`	fieldSettings.allowCustomValues	- for multiselect widget	false
If true, user can provide own options in multiselect, otherwise they will be limited to listValues	fieldSettings.showSearch	- for (multi)select, tree (multi)select	false
Show search (autocomplete)?	fieldSettings.treeExpandAll	- for treeselect/treemultiselect widgets	false
Whether to expand all nodes by default	fieldSettings.treeSelectOnlyLeafs	- for treeselect widget	true
Can select only leafs or any node?	fieldSettings.asyncFetch	- for select widget
Async function to load list of options for select from server. Function format: async (string search, int offset) ⇒ { values: Array, hasMore: boolean } values - list of {title: string, value: mixed, groupTitle?: string} For server-side select listValues will not be used. See also useLoadMore, useAsyncSearch.	fieldSettings.useAsyncSearch	- for select widget	false
If true, asyncFetch supports search.	fieldSettings.useLoadMore	- for select widget	false
If true, asyncFetch supports pagination.	defaultValue
Default value	preferWidgets
See usecase at examples/demo for slider field. Its type is number. There are 3 widgets defined for number type: number, slider, rangeslider. So setting preferWidgets: ['slider', 'rangeslider'] will force rendering slider, and setting preferWidgets: ['number'] will render number input.	operators, defaultOperator, widgets, valueSources
You can override config of corresponding type (see below at section config.types)	mainWidgetProps
Shorthand for widgets.<main>.widgetProps	excludeOperators
Can exclude some operators. Example: ['proximity'] for text type	funcs
If comparing with funcs is enabled for this field (valueSources contains 'func'), you can also limit list of funcs to be compared (by default will be available all funcs from config.funcs with returnType matching field’s type)	hideForSelect		false
If true, field will appear only at right side (when you compare field with another field)	hideForCompare		false
If true, field will appear only at left side	conjunctions, showNot

 
 

config.settings

Example:

import ru_RU from 'antd/es/locale/ru_RU';
import { ruRU } from '@material-ui/core/locale'; //v4
import { ruRU as muiRuRU } from '@mui/material/locale';
import { AntdWidgets } from '@react-awesome-query-builder/antd';
const { FieldCascader, FieldDropdown, FieldTreeSelect } = AntdWidgets;

{
  valueSourcesInfo: {
    value: {
      label: "Value"
    },
    field: {
      label: "Field",
      widget: "field",
    },
    func: {
        label: "Function",
        widget: "func",
    }
  },
  fieldSources: ["field", "func"],
  locale: {
      moment: 'ru',
      antd: ru_RU,
      material: ruRU,
      mui: muiRuRU,
  },
  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
valueSourcesInfo	{value: {}}	By default fields can be compared with values. If you want to enable comparing with another fields, add field like in example above. If you want to enable comparing with result of function, add func like in example above.
fieldSources	["field"]	To enable functions in LHS, set to ["field", "func"]
keepInputOnChangeFieldSrc	true	Keep value entered in RHS after changing source of LHS?
showErrorMessage	false	Show error message in QueryBuilder if validateValue() in field config returns false for the value or if input value does not satisfy max, min constraints in fieldSettings
canReorder	true	Activate reordering support for rules and groups of rules?
canRegroup	true	Allow move rules (or groups) in/out groups during reorder? False - allow "safe" reorder, means only reorder at same level
showNot	true	Show NOT together with AND/OR?
forceShowConj	false	Show conjuction for 1 rule in group?
maxNumberOfRules		Maximum number of rules which can be added to the query builder
maxNesting		Max nesting for rule groups. Set 1 if you don’t want to use groups at all. This will remove also Add group button.
canLeaveEmptyGroup	true	True - leave empty group after deletion of rules, false - automatically remove empty groups + add 1 empty rule to empty root
shouldCreateEmptyGroup	false	False - automatically add 1 empty rule into new group
immutableGroupsMode	false	Not allow to add/delete rules or groups, but allow change
immutableFieldsMode	false	Not allow to change fields
immutableOpsMode	false	Not allow to change operators
immutableValuesMode	false	Not allow to change values
clearValueOnChangeField	false	Clear value on field change? false - if prev & next fields have same type (widget), keep
clearValueOnChangeOp	false	Clear value on operator change?
setOpOnChangeField	['keep', 'default']	Strategies for selecting operator for new field (used by order until success): default (default if present), keep (keep prev from last field), first, none
canCompareFieldWithField		For <ValueFieldWidget> - Function for building right list of fields to compare field with field (string leftField, Object leftFieldConfig, string rightField, Object rightFieldConfig) ⇒ boolean For type == select/multiselect you can optionally check listValues
groupOperators	['all', 'some', 'none']	Operators usable in !group fields with array mode
showLock	false	Show "Lock" switch for rules and groups to make them read-only ("admin mode") NOTE: To preserve read-only state of rules in JsonLogic, please use jsonLogic.add_operation("locked", v ⇒ v); in your code
canDeleteLocked	false	Show "Delete" button for locked rule?
removeIncompleteRulesOnLoad	false	Remove incomplete rules (without field, operator, value, or if not all required args are present for functin) during initial validation of value prop passed to <Query>
removeEmptyRulesOnLoad	true	Remove empty rules during initial validation of value prop passed to <Query>
removeEmptyGroupsOnLoad	true	Remove empty groups during initial validation of value prop passed to <Query>
removeInvalidMultiSelectValuesOnLoad	true	Remove values that are not in listValues during initial validation of value prop passed to <Query>? By default true, but false for AntDesign as can be removed manually
useConfigCompress	false	Set to true if you use Utils.decompressConfig()
fieldItemKeysForSearch	["label", "path", "altLabel", "grouplabel"]	Keys in field item (see type FieldItem) available for search. Available keys: "key", "path", "label", "altLabel" (label2), "tooltip", "grouplabel" (label of parent group, for subfields of complex fields)
listKeysForSearch	["title", "value"]	Keys in list item (see type ListItem) available for search. Available keys: "title", "value", "groupTitle"

💡	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
renderSize	small	Size of AntDesign components - small or large
renderField	(props) ⇒ <FieldSelect {…​props} />	Render fields list Available widgets for AntDesign: FieldSelect, FieldDropdown, FieldCascader, FieldTreeSelect
renderOperator	(props) ⇒ <FieldSelect {…​props} />	Render operators list Available widgets for AntDesign: FieldSelect, FieldDropdown
renderFunc	(props) ⇒ <FieldSelect {…​props} />	Render functions list Available widgets for AntDesign: FieldSelect, FieldDropdown
renderConjs, renderButton, renderIcon, renderButtonGroup, renderSwitch, renderProvider, renderValueSources, renderConfirm, useConfirm, renderRuleError		Other internal render functions you can override if using another UI framework (example)
renderItem		Render Item Able to Customize Render behavior for rule/group items.
showLabels	false	Show labels above all fields?
maxLabelsLength	100	To shorten long labels of fields/values (by length, i.e. number of chars)
dropdownPlacement	bottomLeft	Placement of antdesign’s dropdown pop-up menu
customFieldSelectProps	{}	You can pass props to FieldSelect widget. Example: {showSearch: true}
groupActionsPosition	topRight	You can change the position of the group actions to the following: topLeft, topCenter, topRight, bottomLeft, bottomCenter, bottomRight
renderBeforeWidget
renderAfterWidget
renderBeforeActions
renderAfterActions
defaultSliderWidth	200px	Width for slider
defaultSelectWidth	200px	Width for select
defaultSearchWidth	100px	Width for search in autocomplete
defaultMaxRows	5	Max rows for textarea

Other settings:

key	default	meaning
locale.moment	"en"	Locale (string or array of strings) used for moment
locale.antd	en_US	Locale object used for AntDesign widgets
locale.material	enUS	Locale object used for MaterialUI v4 widgets
locale.mui	enUS	Locale object used for MUI widgets
theme.material	{}	Options for createTheme
theme.mui	{}	Options for createTheme
formatReverse		Function for formatting query string, used to format rule with reverse operator which haven’t formatOp. (string q, string operator, string reversedOp, Object operatorDefinition, Object revOperatorDefinition, bool isForDisplay) ⇒ string q - already formatted rule for opposite operator (which have formatOp) return smth like "NOT(" + q + ")"
formatField		Function for formatting query string, used to format field (string field, Array parts, string label2, Object fieldDefinition, Object config, bool isForDisplay) ⇒ string parts - list of fields’s keys for struct field label2 - field’s label2 OR parts joined by fieldSeparatorDisplay Default impl will just return field (or label2 for isForDisplay==true)
formatAggr		Function for formatting query string, used to format aggregation rule (like SOME OF Cars HAVE Year > 2010) (string whereStr, string aggrField, string operator, mixed value, string valueSrc, string valueType, Object operatorDefinition, Object operatorOptions, bool isForDisplay, Object aggrFieldDef) ⇒ string whereStr - formatted string representing condition for items (eg. Year > 2010 in example) aggrField - aggregation field (eg. Cars in example) operator - can be some/all/none (with cardinality 0) or equal/less/between/.. (applied to count of items) value - for operators with cardinality 1/2 it is value for comparing with count of items
fieldSeparator	.	Separator for struct fields.
fieldSeparatorDisplay	.	Separator for struct fields in UI.

Localization:

key	default
valueLabel	Value
valuePlaceholder	Value
fieldLabel	Field
operatorLabel	Operator
funcLabel	Function
fieldPlaceholder	Select field
funcPlaceholder	Select function
operatorPlaceholder	Select operator
lockLabel	Lock
lockedLabel	Locked
deleteLabel	null
delGroupLabel	null
addGroupLabel	Add group
addRuleLabel	Add rule
addSubRuleLabel	Add sub rule
notLabel	Not
fieldSourcesPopupTitle	Select source
valueSourcesPopupTitle	Select value source
removeRuleConfirmOptions	If you want to ask confirmation of removing non-empty rule/group, add these options. List of all valid properties is here
removeRuleConfirmOptions.title	Are you sure delete this rule?
removeRuleConfirmOptions.okText	Yes
removeRuleConfirmOptions.okType	danger
removeRuleConfirmOptions.cancelText	Cancel
removeGroupConfirmOptions.title	Are you sure delete this group?
removeGroupConfirmOptions.okText	Yes
removeGroupConfirmOptions.okType	danger
removeGroupConfirmOptions.cancelText	Cancel

 
 

config.conjunctions

{
  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	+	Label to be displayed in conjunctions swicther
formatConj	+	Function for formatting query, used to join rules into group with conjunction. (Immultable.List children, string conj, bool not, bool isForDisplay) ⇒ string children - list of already formatted queries (strings) to be joined with conjuction
mongoConj	+ for MongoDB format	Name of logical operator for MongoDb
sqlFormatConj	+ for SQL format	See formatConj
spelFormatConj	+ for SpEL format	See formatConj
reversedConj		Opposite logical operator. Can be used to optimize !(A OR B) to !A && !B (done for MongoDB format)

 
 

config.operators

{
  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	+		Label to be displayed in operators select component
tooltip			Optional tooltip to be displayed in operators list by hovering on item
reversedOp	+		Opposite operator
isNotOp		false	Eg. true for operator "!=", false for operator "=="
cardinality		1	Number of right operands (1 for binary, 2 for between)
formatOp	+		Function for formatting query string, used to join operands into rule. (string field, string op, mixed value, string valueSrc, string valueType, Object opDef, Object operatorOptions, bool isForDisplay) ⇒ string value - string (already formatted value) for cardinality==1 -or- Immutable.List of strings for cardinality>1
labelForFormat			If formatOp is missing, labelForFormat will be used to join operands when building query string
mongoFormatOp	+ for MongoDB format		Function for formatting MongoDb expression, used to join operands into rule. (string field, string op, mixed value, bool useExpr, string valueSrc, string valueType, Object opDef, Object operatorOptions, Object fieldDef) ⇒ object value - mixed for cardinality==1 -or- Array for cardinality>2 useExpr - true if resulted expression will be wrapped in {'$expr': {…​}} (used only if you compare field with another field or function) (you need to use aggregation operators in this case, like $eq (aggregation) instead of $eq)
sqlOp	+ for SQL format		Operator name in SQL
sqlFormatOp	- for SQL format		Function for advanced formatting SQL WHERE query when just sqlOp is not enough. (string field, string op, mixed value, string valueSrc, string valueType, Object opDef, Object operatorOptions, Object fieldDef) ⇒ string value - mixed for cardinality==1 -or- Array for cardinality>2
spelOp	+ for SpEL format		Operator name in SpEL
spelFormatOp	- for SpEL format		Function for advanced formatting query in SpEL when just spelOp is not enough. (string field, string op, mixed value, string valueSrc, string valueType, Object opDef, Object operatorOptions, Object fieldDef) ⇒ string value - mixed for cardinality==1 -or- Array for cardinality>2
jsonLogic	+ for JsonLogic		String (eg. '<') -or- function for advanced formatting (object field, string op, mixed value, Object opDef, Object operatorOptions, Object fieldDef) ⇒ object value - mixed for cardinality==1 -or- Array for cardinality>2 field - already formatted {"var": <some field>}
elasticSearchQueryType	+ for ElasticSearch format		String (eg. term) -or- function (string valueType) ⇒ string One of types of term-level queries
valueLabels	+ for cardinality==2		Labels to be displayed on top of 2 values widgets if config.settings.showLabels is true Example: ['Value from', {label: 'Value to', placeholder: 'Enter value to'}]
textSeparators	+ for cardinality==2		Labels to be displayed before each 2 values widgets Example: [null, 'and']
options			Special for proximity operator (see demo for details)

ℹ️	There is also special proximity operator, its options are rendered with <ProximityOperator>. import {CustomOperators: {ProximityOperator}} from '@react-awesome-query-builder/ui'; See examples/demo

 
 

config.widgets

import {VanillaWidgets} from '@react-awesome-query-builder/ui';
import {AntdWidgets} from '@react-awesome-query-builder/antd';
import {MuiWidgets} from '@react-awesome-query-builder/mui';
import {MaterialWidgets} from '@react-awesome-query-builder/material'; // MUI v4
import {BootstrapWidgets} from '@react-awesome-query-builder/bootstrap';
import {FluentUIWidgets} from "@react-awesome-query-builder/fluent";
const {
    VanillaTextWidget,
    VanillaNumberWidget,
    ...
} = VanillaWidgets;
const {
    TextWidget,
    NumberWidget,
    ...
} = AntdWidgets;
const {
    MuiTextWidget,
    MuiNumberWidget,
    ...
} = MuiWidgets;
const {
    BootstrapTextWidget,
    BootstrapNumberWidget,
    ...
} = BootstrapWidgets;
const {
    FluentUITextWidget,
    FluentUINumberWidget,
    ...
} = FluentUIWidgets;

{
  text: {
    type: 'text',
    valueSrc: 'value',
    factory: (props) => <TextWidget {...props} />,
    formatValue: (val, _fieldDef, _wgtDef, isForDisplay) => (isForDisplay ? val.toString() : 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
type	+		One of types described in config.types
factory	+		React function component
formatValue	+		Function for formatting widget’s value in query string. (mixed val, Object fieldDef, Object wgtDef, bool isForDisplay, string op, Object opDef) ⇒ string
mongoFormatValue	- for MongoDB format	v ⇒ v	Function for formatting widget’s value in MongoDb query. (mixed val, Object fieldDef, Object wgtDef, string op, Object opDef) ⇒ any
sqlFormatValue	- for SQL format	v ⇒ SqlString.escape(v)	Function for formatting widget’s value in SQL WHERE query. (mixed val, Object fieldDef, Object wgtDef, string op, Object opDef) ⇒ string
spelFormatValue	- for SpEL format		Function for formatting widget’s value in SpEL query. (mixed val, Object fieldDef, Object wgtDef, string op, Object opDef) ⇒ string
jsonLogic	- for JsonLogic	v ⇒ v	Function for formatting widget’s value for JsonLogic. (mixed val, Object fieldDef, Object wgtDef, string op, Object opDef) ⇒ any
elasticSearchFormatValue	- for ElasticSearch format	v ⇒ v	Function for formatting widget’s value for ES query. (string esQueryType, mixed val, string op, string field, Object config) ⇒ Object
valueLabel		config.settings.valueLabel	Common option, text to be placed on top of widget if config.settings.showLabels is true
valuePlaceholder		config.settings.valuePlaceholder	Common option, placeholder text to be shown in widget for empty value
maxLength			Option for <TextWidget>, <TextAreaWidget>
maxRows			Option for <TextAreaWidget>
timeFormat		HH:mm:ss	Option for <TimeWidget>, <DateTimeWidget> to display time in widget. Example: 'HH:mm'
use12Hours		false	Option for <TimeWidget>
dateFormat		YYYY-MM-DD	Option for <DateWidget>, <DateTimeWidget> to display date in widget. Example: YYYY-MM-DD
valueFormat			Option for <TimeWidget>, <DateWidget>, <DateTimeWidget> to prepare string representation of value to be stored. Example: YYYY-MM-DD HH:mm
labelYes, labelNo			Option for <BooleanWidget>
customProps			You can pass any props directly to widget with customProps. For example enable search for <Select> widget: customProps: {showSearch: true}
hideOperator			Hide operator?

ℹ️	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).

 
 

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
valueSources		keys of valueSourcesInfo at config.settings	Array with values 'value', 'field', 'func'. If 'value' is included, you can compare field with values. If 'field' is included, you can compare field with another field of same type. If 'func' is included, you can compare field with result of function (see config.funcs).
defaultOperator			If specified, it will be auto selected when user selects field
widgets.*	+		Available widgets for current type and their config. Normally there is only 1 widget per type. But see type number at examples/demo - it has 3 widgets number, slider, rangeslider. Or see type select - it has widget select for operator = and widget multiselect for operator IN.
widgets.<widget>.operators			List of operators for widget, described in config.operators
widgets.<widget>.widgetProps			Can be used to override config of corresponding widget specified in config.widgets. Example: {timeFormat: 'h:mm:ss A'} for time field with AM/PM.
widgets.<widget>.opProps.<operator>			Can be used to override config of operator for widget. Example: opProps: { between: {valueLabels: ['Time from', 'Time to']} } for building range of times.

 
 

config.funcs

{
  lower: {
    label: 'Lowercase',
    sqlFunc: 'LOWER',
    mongoFunc: '$toLower',
    returnType: 'text',
    args: {
      str: {
        type: 'text',
        valueSources: ['value', 'field'],
      }
    }
  },
  ..
}

key	required	default	meaning
returnType	+		One of types described in config.types
label		same as func key	Label to be displayed in functions list
formatFunc		Example result: for isForDisplay==false - FUNC(val1, val2), for isForDisplay==true - FUNC(arg1: val1, arg2: val2)	Function for formatting func expression in query rule. (Object args, bool isForDisplay) ⇒ string where args is object {<arg name> : <arg value>}
sqlFunc	- for SQL format	same as func key	Func name in SQL
sqlFormatFunc	- for SQL format		Can be used instead of sqlFunc. Function with 1 param - args object {<arg name> : <arg value>}, should return formatted function expression string. Example: SUM function can be formatted with ({a, b}) ⇒ a + " + " + b
spelFunc	- for SpEL format	same as func key	Func name in SpEL
spelFormatFunc	- for SpEL format		Can be used instead of spelFunc. Function with 1 param - args object {<arg name> : <arg value>}, should return formatted function expression string. Example: SUM function can be formatted with ({a, b}) ⇒ a + " + " + b
mongoFunc	- for MongoDB format	same as func key	Func name in Mongo
mongoArgsAsObject		false	Some functions like $rtrim supports named args, other ones like $slice takes args as array
mongoFormatFunc	- for MongoDB format		Can be used instead of mongoFunc. Function with 1 param - args object {<arg name> : <arg value>}, should return formatted function expression object.
jsonLogic	+ for JsonLogic		String (function name) or function with 1 param - args object {<arg name> : <arg value>}, should return formatted function expression for JsonLogic.
jsonLogicImport			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.
spelImport			Function to convert given raw SpEL value to array of arguments of current function. If given value can’t be parsed into current function, throw an error.
args.*			Arguments of function. Config is almost same as for simple fields
args.<arg>.label		arg’s key	Label to be displayed in arg’s label or placeholder (if config.settings.showLabels is false)
args.<arg>.type	+		One of types described in config.types
args.<arg>.valueSources		keys of valueSourcesInfo at config.settings	Array with values 'value', 'field', 'func', 'const'. const requires defaultValue
args.<arg>.defaultValue			Default value
args.<arg>.fieldSettings			Settings for widgets, will be passed as props. Example: {min: 1, max: 10}
args.<arg>.fieldSettings.listValues	+ for (multi)select widgets		List of values for Select widget. Example: [{value: 'yellow', title: 'Yellow'}, {value: 'green', title: 'Green'}]
args.<arg>.fieldSettings.treeValues	+ for tree (multi)select widgets		List of values for TreeSelect widget. Example: [{value: 'warm', title: 'Warm colors'}, {value: 'red', title: 'Red', parent: 'warm'}, {value: 'orange', title: 'Orange', parent: 'warm'}]
args.<arg>.isOptional		false	Last args can be optional
renderBrackets		['(', ')']	Can render custom function brackets in UI (or not render).
renderSeps		[', ']	Can render custom arguments separators in UI (other than ,).
allowSelfNesting		false	Allows the function to be used within its own arguments.

See the collection of basic funcstions. You can copy them to config.funcs:

import { BasicFuncs } from '@react-awesome-query-builder/ui';
const config = {
  //...
  funcs: {
    LINEAR_REGRESSION: BasicFuncs.LINEAR_REGRESSION,
    LOWER: BasicFuncs.LOWER,
  }
};

 
 

config.ctx

Required starting from version 6.3.0

It is a collection of JS functions and React components to be used in other sections of config by reference to ctx rather than by reference to imported modules.

💡	The purpose of ctx is to isolate non-serializable part of config.

Typically you just need to copy it from basic config - AntdConfig.ctx for AntDesign, MuiConfig.ctx for MUI, BasicConfig.ctx for vanilla UI etc.

But if you use advanced server-side config, you may need to add your custom functions (eg. validateValue) to ctx and refer to them in other config sections by name.

import {BasicConfig} from '@react-awesome-query-builder/ui';

const fields = {
  firstName: {
    type: "text",
    fieldSettings: {
      // use function `validateFirstName` from `ctx` by name
      validateValue: "validateFirstName",
    }
  },
};

const ctx = {
  ...BasicConfig.ctx,
  validateFirstName: (val: string) => {
    return (val.length < 10);
  },
};

// `zipConfig` can be passed to backend as JSON
const zipConfig = {
  fields,
  settings: {
    useConfigCompress: true, // this is required to use Utils.decompressConfig()
  },
  // you can add here other sections like `widgets` or `types`, but don't add `ctx`
};

// Config can be loaded from backend with providing `ctx`
const config = Utils.decompressConfig(zipConfig, BasicConfig, ctx);

You can’t just pass JS function to validateValue in fieldSettings because functions can’t be serialized to JSON.

 
The shape of ctx:

const ctx = {
  // provided in BasicConfig:
  RCE: React.createElement,
  W: {
    VanillaButton,
    // ... other widgets provieded with the lib
  },
  utils: {
    moment, // used in `formatValue`
    SqlString, // used in `sqlFormatValue`
    // ... other utils
  },
  // your custom extensions:
  components: {
    MyLabel, // used in `labelYes` and `labelNo` below
    // ... other custom components used in JSXs in your config
  },
  validateFirstName: (val: string) => {
    return (val.length < 10);
  },
  myRenderField: (props: FieldProps, _ctx: ConfigContext) => {
    if (props.customProps?.["showSearch"]) {
      return <MuiFieldAutocomplete {...props}/>;
    } else {
      return <MuiFieldSelect {...props}/>;
    }
  },
  autocompleteFetch, // see implementation in `/packages/sandbox_next/components/demo/config_ctx.tsx`
}

Referring to ctx in zipConfig:

const zipConfig = {
  fields: {
    firstName: {
      type: "text",
      fieldSettings: {
        validateValue: "validateFirstName",
      }
    },
    in_stock: {
      type: "boolean",
      mainWidgetProps: {
        labelYes: <MyLabel>Yes</MyLabel>,
        labelNo: <MyLabel>No</MyLabel>,
      }
    },
    autocomplete: {
      type: "select",
      fieldSettings: {
        asyncFetch: "autocompleteFetch",
      },
    },
  },
  settings: {
    renderField: "myRenderField",
    renderButton: "W.VanillaButton",
    useConfigCompress: true, // this is required
  },
};

To build zip config from full config you can use this util:

const zipConfig = Utils.compressConfig(config, BasicConfig);

In order to generate zip config corretly (to JSON-serializable object), you should put your custom functions to ctx and refer to them by names as in examples above.

import merge from "lodash/merge";
const ctx = {
  validateFirstName: (val) => {
    return (val.length < 10);
  },
};
const config = merge({}, BasicConfig, {
  fields: {
    firstName: {
      type: "text",
      fieldSettings: {
        validateValue: "validateFirstName",
      }
    },
  },
  ctx,
});
const zipConfig = Utils.compressConfig(config, BasicConfig);
const config2 = Utils.decompressConfig(zipConfig, BasicConfig, ctx); // should be same as `config`

ℹ️	settings.useConfigCompress should be true if you use Utils.decompressConfig()

 
 

Serialize entire config to string

Section config.ctx demonstrates the concept of zipConfig which is a special config format that contains only changes against full config and can be serialized to JSON. Base configs provided by this library (BasicConfig, AntdConfig etc.) still has JS functions (at least for the moment of writing, in version 6.3.0). If you want to serialize the entire config (not only changes), you can’t do it to JSON as it contains JS functions. But you can do it to string with a help of serialize-javascript and deserialize back with eval(). Yes, it’s unsecure, but can be used for some purposes.

🔥	Using eval() is not secure

To achieve this ability, JS functions in config (like factory, formatValue, validateValue etc.) should be pure functions, they should not use imported modules like this:

import { VanillaWidgets } from '@react-awesome-query-builder/ui';
const { VanillaButton } = VanillaWidgets;
import moment from "moment";

const config = {
  settings: {
    renderButton: (props) => <VanillaButton {...props} />,
  },
  widgets: {
    date: {
      jsonLogic: (val, fieldDef, wgtDef) => moment(val, wgtDef.valueFormat).toDate(),
    },
  },
};

If you try to serialize this config and deserialize back with eval(), you will get ReferenceError: react__WEBPACK_IMPORTED_MODULE_0___default is not defined.

Instead of this all imported modules should be included in config.ctx. All render functions in config have ctx as 2nd argument. In format functions you can refer to ctx via this.

const config = {
  settings: {
    renderButton: (props, {RCE, W: {VanillaButton}}) => RCE(VanillaButton, props),
  },
  widgets: {
    date: {
      jsonLogic: function (val, fieldDef, wgtDef) {
        return this.utils.moment(val, wgtDef.valueFormat).toDate();
      },
    },
  },

  ctx: {
    RCE: React.createElement,
    W: {
      VanillaButton,
    },
    utils: {
      moment,
    },
  }
};

Now entire config (without ctx) can be serialized to a string with serialize-javascript and then deserialized back with eval() and appending ctx. See example.