Security News
Highlights from the 2024 Rails Community Survey
A record 2,709 developers participated in the 2024 Ruby on Rails Community Survey, revealing key tools, practices, and trends shaping the Rails ecosystem.
cxhub-query-builder
Advanced tools
User-friendly query builder for React. Demo: https://ukrbublik.github.io/react-awesome-query-builder
User-friendly React component to build queries (filters).
Inspired by jQuery QueryBuilder. Using awesome Ant Design v4 for widgets. Now Material-UI is also supported!
See live demo
Install:
npm i react-awesome-query-builder --save
For AntDesign widgets only:
npm i antd --save
For Material-UI widgets only:
npm i @material-ui/core @material-ui/lab @material-ui/icons @material-ui/pickers material-ui-confirm --save
See basic usage for minimum code example.
See API and config for documentation.
Demo apps:
npm start
- 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
- 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
- demo app with hot reload of only demo code (uses latest version of library from npm), not uses TS, uses vanilla widgets.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 Material-UI widgets only:
import MaterialConfig from 'react-awesome-query-builder/lib/config/material';
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 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 = () => (
<div>
<Query
{...config}
value={this.state.tree}
onChange={this.onChange}
renderBuilder={this.renderBuilder}
/>
{this.renderResult(this.state)}
</div>
)
renderBuilder = (props) => (
<div className="query-builder-container" style={{padding: '10px'}}>
<div className="query-builder qb-lite">
<Builder {...props} />
</div>
</div>
)
renderResult = ({tree: immutableTree, config}) => (
<div className="query-builder-result">
<div>Query string: <pre>{JSON.stringify(QbUtils.queryString(immutableTree, config))}</pre></div>
<div>MongoDb query: <pre>{JSON.stringify(QbUtils.mongodbFormat(immutableTree, config))}</pre></div>
<div>SQL where: <pre>{JSON.stringify(QbUtils.sqlFormat(immutableTree, config))}</pre></div>
<div>JsonLogic: <pre>{JSON.stringify(QbUtils.jsonLogicFormat(immutableTree, config))}</pre></div>
</div>
)
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`
}
}
import React, { useState } 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 Material-UI widgets only:
//import MaterialConfig from "react-awesome-query-builder/lib/config/material";
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 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 = (immutableTree: ImmutableTree, config: Config) => {
// Tip: for better performance you can apply `throttle` - see `examples/demo`
setState({ 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 = (props: BuilderProps) => (
<div className="query-builder-container" style={{ padding: "10px" }}>
<div className="query-builder qb-lite">
<Builder {...props} />
</div>
</div>
);
return (
<div>
<Query
{...config}
value={state.tree}
onChange={onChange}
renderBuilder={renderBuilder}
/>
<div className="query-builder-result">
<div>
Query string:{" "}
<pre>
{JSON.stringify(QbUtils.queryString(state.tree, state.config))}
</pre>
</div>
<div>
MongoDb query:{" "}
<pre>
{JSON.stringify(QbUtils.mongodbFormat(state.tree, state.config))}
</pre>
</div>
<div>
SQL where:{" "}
<pre>
{JSON.stringify(QbUtils.sqlFormat(state.tree, state.config))}
</pre>
</div>
<div>
JsonLogic:{" "}
<pre>
{JSON.stringify(QbUtils.jsonLogicFormat(state.tree, state.config))}
</pre>
</div>
</div>
</div>
);
};
<Query />
Props:
{...config}
- destructured query CONFIG
value
- query value in internal Immutable formatonChange
- 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
).renderBuilder
- function to render query builder itself. Takes 1 param props
you need to pass into <Builder {...props} />
.Notes:
<Dialog />
or <Popover />
, please:
disableEnforceFocus={true}
for dialog or popver.MuiPopover-root, .MuiDialog-root { z-index: 900 !important; }
(or 1000 for AntDesign v3)props
arg in renderBuilder
have actions
and dispatch
you can use to run actions programmatically (for list of actions see Actions
in index.d.ts
).<Builder />
Render this component only inside Query.renderBuilder()
like in example above:
renderBuilder = (props) => (
<div className="query-builder-container">
<div className="query-builder qb-lite">
<Builder {...props} />
</div>
</div>
)
Wrapping <Builder />
in div.query-builder
is necessary.
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 if you put query builder inside scrollable block.
Utils
onChange
callback of <Query>
.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
value
prop to <Query>
(don't forget to also apply checkTree()
).
validateValue
in config, bad ranges) will be deleted if showErrorMessage
is false OR marked with errors if showErrorMessage
is true.
showErrorMessage
in config.settings is true, use this method to check is query has bad values.isForDisplay
= true can be used to make string more "human readable".
errors
, logic
will be rule object and data
will contain all used fields with null values ("template" data).This library uses configarion driven aprroach.
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.
Versions 4.x are backward-compatible with 2.x and 3.x. It's recommended to update your version.
Version | Supported |
---|---|
4.x | :white_check_mark: |
3.x | :white_check_mark: |
2.x | :white_check_mark: |
1.x | :warning: |
0.x | :x: |
See CHANGELOG
Version 4.9.0 has a breaking change for operators is_empty
and is_not_empty
.
Now these operstors 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]}
.
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.
This project exists thanks to all the people who contribute. [Contribute].
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.
Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]
MIT. See also LICENSE.txt
Forked from https://github.com/fubhy/react-query-builder
FAQs
User-friendly query builder for React. Demo: https://ukrbublik.github.io/react-awesome-query-builder
The npm package cxhub-query-builder receives a total of 83 weekly downloads. As such, cxhub-query-builder popularity was classified as not popular.
We found that cxhub-query-builder demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A record 2,709 developers participated in the 2024 Ruby on Rails Community Survey, revealing key tools, practices, and trends shaping the Rails ecosystem.
Security News
In 2023, data breaches surged 78% from zero-day and supply chain attacks, but developers are still buried under alerts that are unable to prevent these threats.
Security News
Solo open source maintainers face burnout and security challenges, with 60% unpaid and 60% considering quitting.