Gathering detailed insights and metrics for @react-awesome-query-builder-dev/bootstrap
Gathering detailed insights and metrics for @react-awesome-query-builder-dev/bootstrap
User-friendly query builder for React
Installations
npm install @react-awesome-query-builder-dev/bootstrapDeveloper Guide
BETA
Typescript
Yes
Module System
CommonJS, ESM
Node Version
23.11.0
NPM Version
lerna/8.2.2/node@v23.11.0+x64 (linux)
Releases
116
Languages
5
JavaScript
TypeScript
SCSS
Shell
HTML
JavaScript (74.37%)
TypeScript (22.52%)
SCSS (2.56%)
Shell (0.51%)
HTML (0.05%)
Developer
Download Statistics
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
GitHub Statistics
MIT License
2,126 Stars
902 Commits
523 Forks
31 Watchers
10 Branches
87 Contributors
Updated on Jul 13, 2025
Maintainers
1
Package Meta Information
Latest Version
6.7.0-rc.3
Package Id
@react-awesome-query-builder-dev/bootstrap@6.7.0-rc.3
Unpacked Size
177.05 kB
Size
23.72 kB
File Count
93
NPM Version
lerna/8.2.2/node@v23.11.0+x64 (linux)
Node Version
23.11.0
Published on
May 01, 2025
Total Downloads
Cumulative downloads
Total Downloads
NaN
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
1
Peer Dependencies
7
Dev Dependencies
22
@babel/cli@babel/core@babel/plugin-transform-class-properties@babel/plugin-transform-modules-commonjs@babel/plugin-transform-private-methods@babel/plugin-transform-private-property-in-object@babel/plugin-transform-runtime@babel/preset-env@babel/preset-react@babel/preset-typescript@babel/runtime@fortawesome/fontawesome-svg-core@fortawesome/free-solid-svg-icons@fortawesome/react-fontawesome@popperjs/core@types/react@types/react-dombootstrapreactreact-domreactstrapsass
User-friendly React component to build queries (filters).
Inspired by jQuery QueryBuilder. Using awesome UI frameworks for widgets: Ant Design, Material-UI, Bootstrap. Now Fluent UI is also supported!
See live demo
React-Awesome-Query-Builder AI Bot
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 (if-then-else)
- Export to MongoDb, SQL, JsonLogic, SpEL, ElasticSearch or your custom format
- Import from JsonLogic, SpEL, 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, Material-UI, Bootstrap, Fluent UI, vanilla It is possible to use another UI framework of your choice, see how-to
- TypeScript support (see types and demo in TS)
Getting started
From v6 library is divided into packages:
@react-awesome-query-builder/core- has core functionality to import/export/store query, provides utils@react-awesome-query-builder/ui- has core React components like<Query><Builder>and CSS, provides config with basic (vanilla) widgets@react-awesome-query-builder/antd- provides config with Ant Design widgets@react-awesome-query-builder/mui- provides config with MUI widgets@react-awesome-query-builder/material- provides config with Material-UI v4 widgets (deprecated)@react-awesome-query-builder/bootstrap- provides config with Bootstrap widgets@react-awesome-query-builder/fluent- provides config with Fluent UI widgets
1graph LR; 2 core-->ui; 3 core-->sql((sql)); 4 ui-->antd; 5 ui-->mui; 6 ui-->material; 7 ui-->bootstrap; 8 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 eg. to SQL on server-side for security reasons.
Example of installation if you use MUI:
npm i @react-awesome-query-builder/mui --save
Note: We use pnpm. If you want to clone this project and run scripts, please install pnpm:
npm install -g pnpm
See basic usage for minimum code example.
See API and config for documentation.
Demo apps
pnpm start- 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- simple demo app, built with Vite, uses TS, uses MUI widgets.pnpm sandbox-js- simplest demo app, built with Vite, not uses TS, uses vanilla widgets.pnpm 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
1import React, {Component} from 'react'; 2 3// >>> 4import { Utils as QbUtils, Query, Builder, BasicConfig } from '@react-awesome-query-builder/ui'; 5import '@react-awesome-query-builder/ui/css/styles.css'; 6const InitialConfig = BasicConfig; 7// <<< 8 9// You need to provide your own config. See below 'Config format' 10const config = { 11 ...InitialConfig, 12 fields: { 13 qty: { 14 label: 'Qty', 15 type: 'number', 16 fieldSettings: { 17 min: 0, 18 }, 19 valueSources: ['value'], 20 preferWidgets: ['number'], 21 }, 22 price: { 23 label: 'Price', 24 type: 'number', 25 valueSources: ['value'], 26 fieldSettings: { 27 min: 10, 28 max: 100, 29 }, 30 preferWidgets: ['slider', 'rangeslider'], 31 }, 32 name: { 33 label: 'Name', 34 type: 'text', 35 }, 36 color: { 37 label: 'Color', 38 type: 'select', 39 valueSources: ['value'], 40 fieldSettings: { 41 listValues: [ 42 { value: 'yellow', title: 'Yellow' }, 43 { value: 'green', title: 'Green' }, 44 { value: 'orange', title: 'Orange' } 45 ], 46 } 47 }, 48 is_promotion: { 49 label: 'Promo?', 50 type: 'boolean', 51 operators: ['equal'], 52 valueSources: ['value'], 53 }, 54 } 55}; 56 57// You can load query value from your backend storage (for saving see `Query.onChange()`) 58const queryValue = {"id": QbUtils.uuid(), "type": "group"}; 59 60 61class DemoQueryBuilder extends Component { 62 state = { 63 tree: QbUtils.loadTree(queryValue), 64 config: config 65 }; 66 67 render = () => ( 68 <div> 69 <Query 70 {...config} 71 value={this.state.tree} 72 onChange={this.onChange} 73 renderBuilder={this.renderBuilder} 74 /> 75 {this.renderResult(this.state)} 76 </div> 77 ) 78 79 renderBuilder = (props) => ( 80 <div className="query-builder-container" style={{padding: '10px'}}> 81 <div className="query-builder qb-lite"> 82 <Builder {...props} /> 83 </div> 84 </div> 85 ) 86 87 renderResult = ({tree: immutableTree, config}) => ( 88 <div className="query-builder-result"> 89 <div>Query string: <pre>{JSON.stringify(QbUtils.queryString(immutableTree, config))}</pre></div> 90 <div>MongoDb query: <pre>{JSON.stringify(QbUtils.mongodbFormat(immutableTree, config))}</pre></div> 91 <div>SQL where: <pre>{JSON.stringify(QbUtils.sqlFormat(immutableTree, config))}</pre></div> 92 <div>JsonLogic: <pre>{JSON.stringify(QbUtils.jsonLogicFormat(immutableTree, config))}</pre></div> 93 </div> 94 ) 95 96 onChange = (immutableTree, config) => { 97 // Tip: for better performance you can apply `throttle` - see `packages/examples/src/demo` 98 this.setState({tree: immutableTree, config: config}); 99 100 const jsonTree = QbUtils.getTree(immutableTree); 101 console.log(jsonTree); 102 // `jsonTree` can be saved to backend, and later loaded to `queryValue` 103 } 104} 105export default DemoQueryBuilder;
Minimal TypeScript example with function component
1import React, { useState, useCallback } from "react"; 2 3// >>> 4import type { JsonGroup, Config, ImmutableTree, BuilderProps } from '@react-awesome-query-builder/ui'; 5import { Utils as QbUtils, Query, Builder, BasicConfig } from '@react-awesome-query-builder/ui'; 6import '@react-awesome-query-builder/ui/css/styles.css'; 7const InitialConfig = BasicConfig; 8// <<< 9 10// You need to provide your own config. See below 'Config format' 11const config: Config = { 12 ...InitialConfig, 13 fields: { 14 qty: { 15 label: "Qty", 16 type: "number", 17 fieldSettings: { 18 min: 0 19 }, 20 valueSources: ["value"], 21 preferWidgets: ["number"] 22 }, 23 price: { 24 label: "Price", 25 type: "number", 26 valueSources: ["value"], 27 fieldSettings: { 28 min: 10, 29 max: 100 30 }, 31 preferWidgets: ["slider", "rangeslider"] 32 }, 33 name: { 34 label: 'Name', 35 type: 'text', 36 }, 37 color: { 38 label: "Color", 39 type: "select", 40 valueSources: ["value"], 41 fieldSettings: { 42 listValues: [ 43 { value: "yellow", title: "Yellow" }, 44 { value: "green", title: "Green" }, 45 { value: "orange", title: "Orange" } 46 ] 47 } 48 }, 49 is_promotion: { 50 label: "Promo?", 51 type: "boolean", 52 operators: ["equal"], 53 valueSources: ["value"] 54 } 55 } 56}; 57 58// You can load query value from your backend storage (for saving see `Query.onChange()`) 59const queryValue: JsonGroup = { id: QbUtils.uuid(), type: "group" }; 60 61const DemoQueryBuilder: React.FC = () => { 62 const [state, setState] = useState({ 63 tree: QbUtils.loadTree(queryValue), 64 config: config 65 }); 66 67 const onChange = useCallback((immutableTree: ImmutableTree, config: Config) => { 68 // Tip: for better performance you can apply `throttle` - see `packages/examples/src/demo` 69 setState(prevState => ({ ...prevState, tree: immutableTree, config: config })); 70 71 const jsonTree = QbUtils.getTree(immutableTree); 72 console.log(jsonTree); 73 // `jsonTree` can be saved to backend, and later loaded to `queryValue` 74 }, []); 75 76 const renderBuilder = useCallback((props: BuilderProps) => ( 77 <div className="query-builder-container" style={{ padding: "10px" }}> 78 <div className="query-builder qb-lite"> 79 <Builder {...props} /> 80 </div> 81 </div> 82 ), []); 83 84 return ( 85 <div> 86 <Query 87 {...config} 88 value={state.tree} 89 onChange={onChange} 90 renderBuilder={renderBuilder} 91 /> 92 <div className="query-builder-result"> 93 <div> 94 Query string:{" "} 95 <pre> 96 {JSON.stringify(QbUtils.queryString(state.tree, state.config))} 97 </pre> 98 </div> 99 <div> 100 MongoDb query:{" "} 101 <pre> 102 {JSON.stringify(QbUtils.mongodbFormat(state.tree, state.config))} 103 </pre> 104 </div> 105 <div> 106 SQL where:{" "} 107 <pre> 108 {JSON.stringify(QbUtils.sqlFormat(state.tree, state.config))} 109 </pre> 110 </div> 111 <div> 112 JsonLogic:{" "} 113 <pre> 114 {JSON.stringify(QbUtils.jsonLogicFormat(state.tree, state.config))} 115 </pre> 116 </div> 117 </div> 118 </div> 119 ); 120}; 121export default DemoQueryBuilder;
API
<Query />
Props:
{...config}- destructuredCONFIGvalue- query value in internal Immutable formatonChange- callback called when query value changes. Params:value(in Immutable format),config,actionMeta(details about action which led to the change, seeActionMetainindex.d.ts),actions(you can use to run actions programmatically, seeActionsinindex.d.ts).onInit- callback called before initial render, has same arguments asonChange(butactionMetais undefined)renderBuilder- function to render query builder itself. Takes 1 parampropsyou need to pass into<Builder {...props} />.
Notes:
- Please apply
useCallbackforonChangeandrenderBuilderfor performance reason - If you put query builder component inside Material-UI's
<Dialog />or<Popover />, please:- use prop
disableEnforceFocus={true}for dialog or popver - set css
.MuiPopover-root, .MuiDialog-root { z-index: 900 !important; }(or 1000 for AntDesign v3)
- use prop
- If you put query builder component inside Fluent-UI's
<Panel />, please:- set css
.ms-Layer.ms-Layer--fixed.root-119 { z-index: 900 !important; }
- set css
propsarg inrenderBuilderhaveactionsanddispatchyou can use to run actions programmatically- For a list of available actions see
Actionsinterface inindex.d.ts. SeerunActions()in examples as a demonstration of calling actions programmatically.
<Builder />
Render this component only inside Query.renderBuilder() like in example above:
1 renderBuilder = (props) => ( 2 <div className="query-builder-container"> 3 <div className="query-builder qb-lite"> 4 <Builder {...props} /> 5 </div> 6 </div> 7 )
Wrapping <Builder /> 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 <Query>.
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 <Query> after applying loadTree() (which is not recommended because of double conversion). See issue #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 <Query>.
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).
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).
str is an error message translated with i18next.t(key, args) (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.
See i18n for validation.
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
showErrorMessagein config.settings is false - fixed (if possible) or deleted (if can't fix) if
options.forceFixis true - marked with error if
showErrorMessageis true.
options is an object with keys:
removeEmptyGroups(default: true) - If group has no children, drop it.removeEmptyRules(default: true) - If rule is empty, drop it.removeIncompleteRules(default: true) - If rule is not completed (eg. value in RHS is empty, or required argument for a function is empty), drop it. Cause it can't be exported (will not be present in result of any export function call) so can be treated as useless.forceFix(default: false) - If a rule has validation error(s), fix them if it's possible (eg. if value > max, can be reset to max), if not possible - drop it.
Returns an object with properties:
fixedTreeis a fixed immutable tree valuefixedErrorsis an array of fixed errors grouped by itemnonFixedErrorscan be present if afixedTreestill has validation errors (eg. ifforceFix: falseand there are rules with value > max, orremoveEmptyGroups: falseand there are empty groups).allErrorsis an array of all errors (fixed and non-fixed).
The format of errors in fixedErrors, nonFixedErrors, allErrors is the same as returned from validateTree.
But error objects per item alongside with str, key, args, side have also the following keys:
fixed (boolean), fixedFrom, fixedTo.
Export utils
queryString
Utils.Export.queryString (immutableValue, config, isForDisplay = false) -> String
Convert query value to custom string representation.
isForDisplay = true can be used to make string more "human readable".
mongodbFormat
Utils.Export.mongodbFormat (immutableValue, config) -> Object
Convert query value to MongoDb query object.
sqlFormat
Utils.Export.sqlFormat (immutableValue, config) -> String
Convert query value to SQL where string.
spelFormat
Utils.Export.spelFormat (immutableValue, config) -> String
Convert query value to Spring Expression Language (SpEL).
elasticSearchFormat
Utils.Export.elasticSearchFormat (immutableValue, config) -> Object
Convert query value to ElasticSearch query object.
jsonLogicFormat
Utils.Export.jsonLogicFormat (immutableValue, config) -> {logic, data, errors}
Convert query value to JsonLogic format.
If there are no errors, logic will be rule object and data will contain all used fields with null values ("template" data).
Note: You can set config.settings.fixJsonLogicDateCompareOp = true to fix the comparison of dates with == and != in JsonLogic by using custom ops date==, date!=, datetime==, datetime!=.
Note: If you import custom version of json-logic-js please add custom operators with:
1import JL from "json-logic-js"; 2Utils.JsonLogicUtils.addRequiredJsonLogicOperations(JL); 3// console.log(JL.apply({ "now": [] }));
Import utils
loadFromJsonLogic
Utils.Import.loadFromJsonLogic (jsonLogicObject, config) -> Immutable
Convert query value from JsonLogic format to internal Immutable format.
_loadFromJsonLogic
Utils.Import._loadFromJsonLogic (jsonLogicObject, config) -> [Immutable, errors]
loadFromSpel
Utils.Import.loadFromSpel (string, config) -> [Immutable, errors]
Convert query value from Spring Expression Language (SpEL) format to internal Immutable format.
loadFromSql
SqlUtils.loadFromSql (string, config) -> {tree: Immutable, errors: string[]}
Convert query value from SQL format to internal Immutable format.
Requires import of @react-awesome-query-builder/sql:
import { SqlUtils } from "@react-awesome-query-builder/sql"
Save/load config from server
compressConfig
Utils.ConfigUtils.compressConfig (config, baseConfig) -> ZipConfig
Returns compressed config that can be serialized to JSON and saved on server.
ZipConfig is a special format that contains only changes agains baseConfig.
baseConfig is a config you used as a base for constructing config, like InitialConfig in examples above.
It depends on UI framework you choose - eg. if you use @react-awesome-query-builder/mui, please provide MuiConfig to baseConfig.
decompressConfig
Utils.ConfigUtils.decompressConfig (zipConfig, baseConfig, ctx?) -> Config
Converts zipConfig (compressed config you receive from server) to a full config that can be passed to <Query />.
baseConfig is a config to be used as a base for constructing your config, like InitialConfig in examples above.
ctx is optional and can contain your custom functions and custom React components used in your config.
If ctx is provided in 3rd argument, it will inject it to result config, otherwise will copy from basic config in 2nd argument.
See SSR for more info.
Note that you should set config.settings.useConfigCompress = true in order for this function to work.
Config format
This library uses config-driven aproach.
Config defines what value types, operators are supported, how they are rendered, imported, exported.
At minimum, you need to provide your own set of fields as in basic usage.
See CONFIG for full documentation.
Validation
Useful config settings to manage global validation behaviour:
showErrorMessage: If it'sfalse, query builder won't allow user to input incorrect values (like > max or < min or value that doesn't bypassvalidateValue()in field config). If it'strue, inputs can have invalid values but the appropriate error message will be shown under the rule.removeIncompleteRulesOnLoad,removeEmptyRulesOnLoad,removeEmptyGroupsOnLoad,removeInvalidMultiSelectValuesOnLoad: during initial validation ofvalueprop passed to<Query>.
Useful field config settings to manage validation behaviour per field:
fieldSettings.min,fieldSettings.maxfor numeric fieldsfieldSettings.maxLengthfor string fieldsfieldSettings.validateValue- Custom JS function to validate value and return null (if value is valid) or object{error, fixedValue?}.errorcan be a string or an object{key, args}to use i18n- Note that functions and their arguments can also have
fieldSettings
Use Utils.sanitizeTree() to perform validation on tree value and return validation errors and fixed tree value.
See the list of validation utils.
See i18n for validation.
i18n
:construction:
This library uses i18next for translations.
Validation translations
Namespace: raqbvalidation.
Default translations resource
Example of overriding translations for validation error messages:
1Utils.i18n.addResources("en", "raqbvalidation", { 2 "INCOMPLETE_LHS": "Incomplete left-hand side", 3 "INCOMPLETE_RHS": "Incomplete right-hand side", 4});
Example of using custom translations in validateValue in config:
1Utils.i18n.addResources("en", "mynamespace", { 2 "INVALID_SLIDER_VALUE": "Invalid slider value {{val}}", 3}); 4 5const config = { 6 ...MuiConfig, 7 fields: { 8 slider: { 9 type: "number", 10 preferWidgets: ["slider"], 11 fieldSettings: { 12 validateValue: (val) => { 13 return (val < 50 ? null : { 14 error: { 15 // use `key` and `args` for i18next.t() 16 // `key` should have your namespace prefixed with ":" 17 key: "mynamespace:INVALID_SLIDER_VALUE", 18 args: { val } 19 }, 20 fixedValue: 49 21 }); 22 }, 23 } 24 } 25 } 26}; 27 28// then use <Query {...config} />
See example.
Ternary mode
First you need to configure caseValueField in config.settings. Example to use tags as case values:
1const config: Config = { 2 ...InitialConfig, 3 fields, 4 settings: { 5 ...InitialConfig.settings, 6 caseValueField: { 7 type: "select", 8 valueSources: ["value"], 9 fieldSettings: { 10 listValues: [ 11 { value: "tag1", title: "Tag #1" }, 12 { value: "tag2", title: "Tag #2" }, 13 ], 14 }, 15 mainWidgetProps: { 16 valueLabel: "Then", 17 valuePlaceholder: "Then", 18 }, 19 }, 20 canRegroupCases: true, 21 maxNumberOfCases: 10, 22 } 23};
You can use other type/widget (including your custom one) to render case values.
Also you can use function (action) by specifying valueSources: ["func"] in caseValueField.
You have to add funcs to the config (with returnType equals type in case value field).
Load empty tree in ternary mode:
1import { Utils as QbUtils, JsonSwitchGroup } from '@react-awesome-query-builder/ui';
2const emptyJson: JsonSwitchGroup = { id: QbUtils.uuid(), type: "switch_group", };
3const tree = QbUtils.loadTree(emptyJson);See example
SSR
You can save and load config from server with help of utils:
You need these utils because you can't just send config as-is to server, as it contains functions that can't be serialized to JSON.
Note that you need to set config.settings.useConfigCompress = true to enable this feature.
To put it simple:
ZipConfigtype is a JSON that contains only changes against basic config (differences). At minimum it contains yourfields. It does not containctx.Utils.ConfigUtils.decompressConfig()will mergeZipConfigto basic config (and addctxif passed).
See sandbox_next demo app that demonstrates server-side features.
ctx
Config context is an obligatory part of config starting from version 6.3.0
It is a collection of functions and React components to be used in other parts 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.
See config.ctx.
Versions
Version 5 is backward-compatible with 2-4. From version 6 library is divided into packages. It's recommended to update your version to 6.x. You just need to change your imports, see Migration to 6.0.0
Supported versions
| Version | Supported |
|---|---|
| 6.x | :white_check_mark: |
| 5.x | :heavy_check_mark: |
| 4.x | :warning: |
| 3.x | :x: |
| 2.x | :x: |
| 1.x | :x: |
| 0.x | :x: |
Changelog
See CHANGELOG
Migration to 6.5.0
Validation API has been changed:
Utils.validateTree()now returns array of validation errors intead of booleanUtils.checkTree()andUtils.validateAndFixTree()are deprecated (and removed type defs). UseUtils.sanitizeTree().fixedTreeinstead
Migration to 6.4.0
If you want to enable functions in LHS, please add to config.settings:
1fieldSources: ["field", "func"],
Migration to 6.3.0
Now config has new ctx property. Make sure you add it to your config.
Typically you just need to copy it from basic config. So if you create config like this, you don't need to make any changes:
1import { MuiConfig } from "@react-awesome-query-builder/mui"; 2const config = { 3 ...MuiConfig, 4 fields: { 5 // your fields 6 }, 7};
But if you create config without destructuring of basic config, please add ctx:
1import { MuiConfig } from "@react-awesome-query-builder/mui"; 2 3const config = { 4 ctx: MuiConfig.ctx, // needs to be added for 6.3.0+ 5 conjunctions, 6 operators, 7 widgets, 8 types, 9 settings, 10 fields, 11 funcs 12}; 13export default config;
Note: If you override render* function(s) in config setttings and call original render* function from imported config, be aware that you should pass ctx as 2nd param.
Example:
1config = {
2 ...MuiConfig,
3 settings: {
4 ...MuiConfig.settings,
5 renderField: (props) => (
6 <WithTheme theme={theme}>
7 { MuiConfig.settings.renderField?.(props, MuiConfig.ctx) } // please pass `ctx`
8 </WithTheme>
9 ),
10 }
11};See issue #996
Migration to 6.2.0
If you use treeselect or treemultiselect type (for AntDesign), please rename listValues to treeValues
Migration to 6.0.0
From version 6 library is divided into packages.
Please remove package react-awesome-query-builder and install one of:
@react-awesome-query-builder/ui@react-awesome-query-builder/antd@react-awesome-query-builder/bootstrap@react-awesome-query-builder/mui@react-awesome-query-builder/material(deprecated)@react-awesome-query-builder/fluent
Library code is backward-compatible with version 2-5. You just need to change your imports.
1- import { Utils, Export, Import, BasicFuncs } from 'react-awesome-query-builder'; 2+ import { Utils, Export, Import, BasicFuncs } from '@react-awesome-query-builder/ui'; 3 4- import { Query, Builder, BasicConfig, Widgets, Operators } from 'react-awesome-query-builder'; 5+ import { Query, Builder, BasicConfig, VanillaWidgets, CustomOperators } from '@react-awesome-query-builder/ui'; 6 7- import AntdConfig from 'react-awesome-query-builder/lib/config/antd'; 8+ import {AntdConfig} from '@react-awesome-query-builder/antd'; 9- import MuiConfig from 'react-awesome-query-builder/lib/config/mui'; 10+ import {MuiConfig} from '@react-awesome-query-builder/mui'; 11- import MaterialConfig from 'react-awesome-query-builder/lib/config/material'; 12+ import {MaterialConfig} from '@react-awesome-query-builder/material'; 13- import BootstrapConfig from 'react-awesome-query-builder/lib/config/bootstrap'; 14+ import {BootstrapConfig} from '@react-awesome-query-builder/bootstrap'; 15 16- import 'react-awesome-query-builder/lib/css/styles.css'; 17+ import '@react-awesome-query-builder/ui/css/styles.css'; 18- import 'react-awesome-query-builder/lib/css/compact_styles.css'; 19+ import '@react-awesome-query-builder/ui/css/compact_styles.css'; // instead of styles.css for more compact look
Note that you should import all types and values from a single package.
For example, @react-awesome-query-builder/antd if you use AntDesign - it inherits core and ui:
1import {Utils, Query, Builder, AntdConfig} from '@react-awesome-query-builder/antd';
You don't need to install and import ui and core packages in this case, just use antd.
Same for styles - please import from antd package:
1import '@react-awesome-query-builder/antd/css/styles.css';
instead of
1import '@react-awesome-query-builder/ui/css/styles.css';
If you use vanilla widgets, please install, import and use only @react-awesome-query-builder/ui (it inherits core).
One more thing, if you use Bootstrap widgets, now you need to explicitly import CSS:
1import "bootstrap/dist/css/bootstrap.min.css";
Migration to 5.2.0
Breaking change: children1 is now an indexed array (instead of object) in result of Utils.getTree() to preserve items order.
Before:
1children1: { 2 '<id1>': { type: 'rule', properties: ... }, 3 '<id2>': { type: 'rule', properties: ... } 4}
After:
1children1: [ 2 { id: '<id1>', type: 'rule', properties: ... }, 3 { id: '<id2>', type: 'rule', properties: ... }, 4]
Utils.loadTree() is backward comatible with children1 being array or object.
But if you rely on previous format (maybe do post-processing of getTree() result), please use Utils.getTree(tree, true, false) - it will behave same as before this change.
Another breaking change: removeIncompleteRulesOnLoad and removeEmptyGroupsOnLoad now default to true, set them to false in your settings to preserve the behaviour before 5.2.0.
Migration to 4.9.0
Version 4.9.0 has a breaking change for operators is_empty and is_not_empty.
Now these operators can be used for text type only (for other types they will be auto converted to is_null/is_not_null during loading of query value created with previous versions).
Changed meaning of is_empty - now it's just strict comparing with empty string.
Before change the meaning was similar to is_null.
If you used is_empty for text types with intention of comparing with null, please replace is_empty -> is_null, is_not_empty -> is_not_null in saved query values.
If you used JsonLogic for saving, you need to replace {"!": {"var": "your_field"}} -> {"==": [{"var": "your_field"}, null]} and {"!!": {"var": "your_field"}} -> {"!=": [{"var": "your_field"}, null]}.
Migration from v1 to v2
From v2.0 of this lib AntDesign is now optional (peer) dependency, so you need to explicitly include antd (4.x) in package.json of your project if you want to use AntDesign UI.
Please import AntdConfig from react-awesome-query-builder/lib/config/antd and use it as base for your config (see below in usage).
Alternatively you can use BasicConfig for simple vanilla UI, which is by default.
Support of other UI frameworks (like Bootstrap) are planned for future, see Other UI frameworks.
Contributing
Code Contributing
This project exists thanks to all the people who contribute. [Contribute].
Financial Contributing
Become a financial contributor and help us sustain our community. [Contribute]
If you mention in an GitHub issue that you are a sponsor, we will prioritize helping you.
As a sponsor you can ask to implement a feature that is not in a todo list or motivate for faster implementation.
Individuals
Organizations
Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]
License
MIT. See also LICENSE.txt
Forked from https://github.com/fubhy/react-query-builder
No vulnerabilities found.
Reason
19 commit(s) and 14 issue activity found in the last 90 days -- score normalized to 10
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
license file detected
Details
- Info: project has a license file: LICENSE.txt:0
- Info: FSF or OSI recognized license: MIT License: LICENSE.txt:0
Reason
2 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw
- Warn: Project is vulnerable to: GHSA-8cj5-5rvv-wf4v
Reason
SAST tool is not run on all commits -- score normalized to 3
Details
- Warn: 11 commits out of 28 are checked with a SAST tool
Reason
Found 5/25 approved changesets -- score normalized to 2
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: topLevel 'contents' permission set to 'write': .github/workflows/bump-version-pr.yml:12
- Warn: no topLevel permission defined: .github/workflows/codecov-report.yml:1
- Warn: no topLevel permission defined: .github/workflows/gh-pages.yml:1
- Warn: no topLevel permission defined: .github/workflows/long-smoke.yml:1
- Warn: no topLevel permission defined: .github/workflows/npm-publish.yml:1
- Warn: no topLevel permission defined: .github/workflows/smoke.yml:1
- Info: no jobLevel write permissions found
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
dependency not pinned by hash detected -- score normalized to 0
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/bump-version-pr.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/bump-version-pr.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/bump-version-pr.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/bump-version-pr.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/bump-version-pr.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/bump-version-pr.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/bump-version-pr.yml:41: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/bump-version-pr.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codecov-report.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/codecov-report.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/codecov-report.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/codecov-report.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codecov-report.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/codecov-report.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/codecov-report.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/codecov-report.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/gh-pages.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/gh-pages.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/gh-pages.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/gh-pages.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/gh-pages.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/gh-pages.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/gh-pages.yml:36: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/gh-pages.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/long-smoke.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/long-smoke.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/long-smoke.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/long-smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/long-smoke.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/long-smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/long-smoke.yml:31: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/long-smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/long-smoke.yml:38: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/long-smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/long-smoke.yml:43: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/long-smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/long-smoke.yml:48: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/long-smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/npm-publish.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/npm-publish.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/npm-publish.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/npm-publish.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/npm-publish.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/npm-publish.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/npm-publish.yml:29: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/npm-publish.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/npm-publish.yml:30: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/npm-publish.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/npm-publish.yml:33: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/npm-publish.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/smoke.yml:61: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/smoke.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/smoke.yml:62: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/smoke.yml:65: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/smoke.yml:78: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/smoke.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/smoke.yml:79: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/smoke.yml:82: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/smoke.yml:93: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/smoke.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/smoke.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/smoke.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/smoke.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/smoke.yml:29: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/smoke.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/smoke.yml:30: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/smoke.yml:33: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/smoke.yml:44: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/smoke.yml:49: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/smoke.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/smoke.yml:54: update your workflow using https://app.stepsecurity.io/secureworkflow/ukrbublik/react-awesome-query-builder/smoke.yml/master?enable=pin
- Warn: npmCommand not pinned by hash: scripts/nvms.sh:31
- Info: 0 out of 28 GitHub-owned GitHubAction dependencies pinned
- Info: 0 out of 13 third-party GitHubAction dependencies pinned
- Info: 0 out of 1 npmCommand dependencies pinned
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Score
5
/10
Last Scanned on 2025-07-07
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More