[![npm](https://img.shields.io/npm/v/react-awesome-query-builder.svg)](https://www.npmjs.com/package/react-awesome-query-builder) [![Smoke](https://github.com/ukrbublik/react-awesome-query-builder/actions/workflows/smoke.yml/badge.svg?text=Test)](https://github.com/ukrbublik/react-awesome-query-builder/actions/workflows/smoke.yml?query=branch%3Amaster) [![travis](https://travis-ci.org/ukrbublik/react-awesome-query-builder.svg?branch=master)](https://travis-ci.com/github/ukrbublik/react-awesome-query-builder) [![codecov](https://codecov.io/gh/ukrbublik/react-awesome-query-builder/branch/master/graph/badge.svg?date=20201002)](https://codecov.io/gh/ukrbublik/react-awesome-query-builder) [![antd](https://img.shields.io/badge/skin-Ant%20Design-blue?logo=Ant%20Design)](https://ant.design) [![mui](https://img.shields.io/badge/skin-Material%20UI-blue?logo=MUI)](https://material-ui.com) [![bootstrap](https://img.shields.io/badge/skin-Bootstrap-blue?logo=Bootstrap)](https://reactstrap.github.io/) [![demo](https://img.shields.io/badge/demo-blue)](https://ukrbublik.github.io/react-awesome-query-builder/) [![sandbox TS](https://img.shields.io/badge/sandbox-TS-blue)](https://codesandbox.io/s/github/ukrbublik/react-awesome-query-builder/tree/master/sandbox?file=/src/demo/config_simple.tsx) [![sandbox JS](https://img.shields.io/badge/sandbox-JS-blue)](https://codesandbox.io/s/github/ukrbublik/react-awesome-query-builder/tree/master/sandbox_simple?file=/src/demo/config_simple.js) User-friendly React component to build queries (filters). Inspired by [jQuery QueryBuilder](http://querybuilder.js.org/). Using awesome [Ant Design](https://ant.design/) v4 for widgets. Now [Material-UI](https://material-ui.com/) is also supported! See [live demo](https://ukrbublik.github.io/react-awesome-query-builder) [![Open in codesandbox.io](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/github/ukrbublik/react-awesome-query-builder/tree/master/sandbox?file=/src/demo/config_simple.tsx) * [Features](#features) * [Getting started](#getting-started) * [Usage](#usage) * [Minimal JavaScript example with class component](#minimal-javascript-example-with-class-component) * [Minimal TypeScript example with function component](#minimal-typescript-example-with-function-component) * [API](#api) * [Config format](#config-format) * [Versions](#versions) * [Changelog](#changelog) * [Migration to 5.2.0](#migration-to-520) * [Migration to 4.9.0](#migration-to-490) * [Migration from v1 to v2](#migration-from-v1-to-v2) * [Contributing](#contributing) * [Code Contributing](#code-contributing) * [Financial Contributing](#financial-contributing) ### Features [![Screenshot](https://ukrbublik.github.io/react-awesome-query-builder/screenshot.png)](https://ukrbublik.github.io/react-awesome-query-builder) - Highly configurable - Fields can be of type: - simple (string, number, bool, date/time/datetime, list) - structs (will be displayed in selectbox as tree) - custom type (dev should add its own widget component in config for this) - Comparison operators can be: - binary (== != < > ..) - unary (is empty, is null) - 'between' (for numbers, dates, times) - complex operators like 'proximity' - Values of fields can be compared with: - values - another fields (of same type) - function (arguments also can be values/fields/funcs) - Reordering (drag-n-drop) support for rules and groups of rules - Themes: - [Ant Design](https://ant.design/) - [Material-UI](https://material-ui.com/) - [Bootstrap](https://reactstrap.github.io/) - vanilla (Using another UI framework and custom widgets is possible, see below) - Export to MongoDb, SQL, [JsonLogic](http://jsonlogic.com), [SpEL](https://docs.spring.io/spring-framework/docs/3.2.x/spring-framework-reference/html/expressions.html), ElasticSearch or your custom format - Import from [JsonLogic](http://jsonlogic.com), [SpEL](https://docs.spring.io/spring-framework/docs/3.2.x/spring-framework-reference/html/expressions.html) - TypeScript support (see [types](/modules/index.d.ts) and [demo in TS](/examples)) ## Getting started Install: ``` npm i react-awesome-query-builder --save ``` For AntDesign widgets only: ``` npm i antd @ant-design/icons --save ``` For Material-UI 4 widgets only: ``` npm i @material-ui/core @material-ui/lab @material-ui/icons @material-ui/pickers material-ui-confirm@2 --save ``` For MUI 5 widgets only: ``` npm i @mui/material @emotion/react @emotion/styled @mui/lab @mui/icons-material @mui/x-date-pickers material-ui-confirm@3 --save ``` For Bootstrap widgets only: ``` npm i bootstrap reactstrap @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/react-fontawesome --save ``` See [basic usage](#usage) for minimum code example. See [API](#api) and [config](#config-format) for documentation. Demo apps: - [`npm start`](/examples) - demo app with hot reload of demo code and local library code, uses TS, uses complex config to demonstrate anvanced usage. - [`npm run sandbox-ts`](/sandbox) - demo app with hot reload of only demo code (uses latest version of library from npm), uses TS, uses AntDesign widgets. - [`npm run sandbox-js`](/sandbox_simple) - demo app with hot reload of only demo code (uses latest version of library from npm), not uses TS, uses vanilla widgets. ## Usage #### Minimal JavaScript example with class component ```javascript import React, {Component} from 'react'; import {Query, Builder, BasicConfig, Utils as QbUtils} from 'react-awesome-query-builder'; // For AntDesign widgets only: import AntdConfig from 'react-awesome-query-builder/lib/config/antd'; import 'antd/dist/antd.css'; // or import "react-awesome-query-builder/css/antd.less"; // For MUI 4/5 widgets only: import MaterialConfig from 'react-awesome-query-builder/lib/config/material'; import MuiConfig from 'react-awesome-query-builder/lib/config/mui'; // For Bootstrap widgets only: import BootstrapConfig from "react-awesome-query-builder/lib/config/bootstrap"; import 'react-awesome-query-builder/lib/css/styles.css'; import 'react-awesome-query-builder/lib/css/compact_styles.css'; //optional, for more compact styles // Choose your skin (ant/material/vanilla): const InitialConfig = AntdConfig; // or MaterialConfig or MuiConfig or BootstrapConfig or BasicConfig // You need to provide your own config. See below 'Config format' const config = { ...InitialConfig, fields: { qty: { label: 'Qty', type: 'number', fieldSettings: { min: 0, }, valueSources: ['value'], preferWidgets: ['number'], }, price: { label: 'Price', type: 'number', valueSources: ['value'], fieldSettings: { min: 10, max: 100, }, preferWidgets: ['slider', 'rangeslider'], }, color: { label: 'Color', type: 'select', valueSources: ['value'], fieldSettings: { listValues: [ { value: 'yellow', title: 'Yellow' }, { value: 'green', title: 'Green' }, { value: 'orange', title: 'Orange' } ], } }, is_promotion: { label: 'Promo?', type: 'boolean', operators: ['equal'], valueSources: ['value'], }, } }; // You can load query value from your backend storage (for saving see `Query.onChange()`) const queryValue = {"id": QbUtils.uuid(), "type": "group"}; class DemoQueryBuilder extends Component { state = { tree: QbUtils.checkTree(QbUtils.loadTree(queryValue), config), config: config }; render = () => (

{this.renderResult(this.state)}

) renderBuilder = (props) => (

) renderResult = ({tree: immutableTree, config}) => (

Query string:

{JSON.stringify(QbUtils.queryString(immutableTree, config))}

MongoDb query:

{JSON.stringify(QbUtils.mongodbFormat(immutableTree, config))}

SQL where:

{JSON.stringify(QbUtils.sqlFormat(immutableTree, config))}

JsonLogic:

{JSON.stringify(QbUtils.jsonLogicFormat(immutableTree, config))}

) onChange = (immutableTree, config) => { // Tip: for better performance you can apply `throttle` - see `examples/demo` this.setState({tree: immutableTree, config: config}); const jsonTree = QbUtils.getTree(immutableTree); console.log(jsonTree); // `jsonTree` can be saved to backend, and later loaded to `queryValue` } } ``` #### Minimal TypeScript example with function component ([Codesandbox](https://codesandbox.io/s/relaxed-sun-erhnu?file=/src/demo/demo.tsx)) ```typescript import React, { useState, useCallback } from "react"; import { Query, Builder, Utils as QbUtils } from "react-awesome-query-builder"; // types import { JsonGroup, Config, ImmutableTree, BuilderProps } from "react-awesome-query-builder"; // For AntDesign widgets only: import AntdConfig from "react-awesome-query-builder/lib/config/antd"; import "antd/dist/antd.css"; // or import "react-awesome-query-builder/css/antd.less"; // For MUI 4/5 widgets only: //import MaterialConfig from 'react-awesome-query-builder/lib/config/material'; //import MuiConfig from 'react-awesome-query-builder/lib/config/mui'; // For Bootstrap widgets only: //import BootstrapConfig from "react-awesome-query-builder/lib/config/bootstrap"; import "react-awesome-query-builder/lib/css/styles.css"; import "react-awesome-query-builder/lib/css/compact_styles.css"; //optional, for more compact styles // Choose your skin (ant/material/vanilla): const InitialConfig = AntdConfig; // or MaterialConfig or MuiConfig or BootstrapConfig or BasicConfig // You need to provide your own config. See below 'Config format' const config: Config = { ...InitialConfig, fields: { qty: { label: "Qty", type: "number", fieldSettings: { min: 0 }, valueSources: ["value"], preferWidgets: ["number"] }, price: { label: "Price", type: "number", valueSources: ["value"], fieldSettings: { min: 10, max: 100 }, preferWidgets: ["slider", "rangeslider"] }, color: { label: "Color", type: "select", valueSources: ["value"], fieldSettings: { listValues: [ { value: "yellow", title: "Yellow" }, { value: "green", title: "Green" }, { value: "orange", title: "Orange" } ] } }, is_promotion: { label: "Promo?", type: "boolean", operators: ["equal"], valueSources: ["value"] } } }; // You can load query value from your backend storage (for saving see `Query.onChange()`) const queryValue: JsonGroup = { id: QbUtils.uuid(), type: "group" }; export const Demo: React.FC = () => { const [state, setState] = useState({ tree: QbUtils.checkTree(QbUtils.loadTree(queryValue), config), config: config }); const onChange = useCallback((immutableTree: ImmutableTree, config: Config) => { // Tip: for better performance you can apply `throttle` - see `examples/demo` setState(prevState => { ...prevState, tree: immutableTree, config: config }); const jsonTree = QbUtils.getTree(immutableTree); console.log(jsonTree); // `jsonTree` can be saved to backend, and later loaded to `queryValue` }, []); const renderBuilder = useCallback((props: BuilderProps) => (

), []); return (

Query string:{" "}

            {JSON.stringify(QbUtils.queryString(state.tree, state.config))}

MongoDb query:{" "}

            {JSON.stringify(QbUtils.mongodbFormat(state.tree, state.config))}

SQL where:{" "}

            {JSON.stringify(QbUtils.sqlFormat(state.tree, state.config))}

JsonLogic:{" "}

            {JSON.stringify(QbUtils.jsonLogicFormat(state.tree, state.config))}

); }; ``` ## API ### `` Props: - `{...config}` - destructured query [`CONFIG`](/CONFIG.adoc) - `value` - query value in internal [Immutable](https://immutable-js.github.io/immutable-js/) format - `onChange` - callback when query value changed. Params: `value` (in Immutable format), `config`, `actionMeta` (details about action which led to the change, see `ActionMeta` in [`index.d.ts`](/modules/index.d.ts)). - `renderBuilder` - function to render query builder itself. Takes 1 param `props` you need to pass into ``. *Notes*: - Please apply `useCallback` for `onChange` and `renderBuilder` for performance reason - If you put query builder component inside [Material-UI](https://github.com/mui-org/material-ui)'s `

	Stars	Issues	Version	Updated	Created
react-awesome-query-builder	1,810	123	5.4.2	a year ago	7 years ago
react-media-query-hoc	59	21	2.1.1	4 years ago	7 years ago
react-querybuilder	1,050	18	7.3.0	3 days ago	8 years ago

react-awesome-query-builder vs react-media-query-hoc vs react-querybuilder

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Sick of boring JavaScript newsletters?

Downloads in past