react-querybuilder-material-ui
Getting Started
npm install react-querybuilder-material-ui --save
OR
yarn add react-querybuilder-material-ui
Demo
OR
To run the demo yourself, go through the following steps:
npm install
Install npm packagesnpm start
Run a local server- http://localhost:8080/ Visit your localhost in your browser
Usage
import QueryBuilder from 'react-querybuilder'; const fields = name: 'firstName' label: 'First Name' name: 'lastName' label: 'Last Name' name: 'age' label: 'Age' name: 'address' label: 'Address' name: 'phone' label: 'Phone' name: 'email' label: 'Email' name: 'twitter' label: 'Twitter' name: 'isDev' label: 'Is a Developer?' value: false ; const dom = <QueryBuilder = = />; { console;}
API
This library exposes a React component, <QueryBuilder />
, and a utility function, formatQuery
. <QueryBuilder />
is the default export, and formatQuery
is exposed as a named export.
QueryBuilder
<QueryBuilder />
supports the following properties:
query
(Optional)
{id?: string, combinator: string, rules: ({field: string, value: any, operator: string} | {rules: ...[], combinator: string})[]}
The initial query, in JSON form (follows the same format as the parameter passed to the onQueryChange
callback). id
is optional. See the demo source for examples.
fields
(Required)
{name: string, label: string, id?: string}[]
The array of fields that should be used. Each field should be an object with at least:
{name: string, label: string}
The id
is optional. If you do not provide an id
for a field then the name
will be used.
Field objects can also contain other data. Each field object will be passed to the appropriate OperatorSelector
and ValueEditor
components as fieldData
(see the section on controlElements
).
operators
(Optional)
{name: string, label: string}[]
The array of operators that should be used. The default operators include:
name: 'null' label: 'is null' name: 'notNull' label: 'is not null' name: 'in' label: 'in' name: 'notIn' label: 'not in' name: '=' label: '=' name: '!=' label: '!=' name: '<' label: '<' name: '>' label: '>' name: '<=' label: '<=' name: '>=' label: '>=' name: 'contains' label: 'contains' name: 'beginsWith' label: 'begins with' name: 'endsWith' label: 'ends with' name: 'doesNotContain' label: 'does not contain' name: 'doesNotBeginWith' label: 'does not begin with' name: 'doesNotEndWith' label: 'does not end with' ;
combinators
(Optional)
{name: string, label: string}[]
The array of combinators that should be used for RuleGroups. The default set includes:
name: 'and' label: 'AND' name: 'or' label: 'OR' ;
controlElements
(Optional)
ReactPropTypesshape addGroupAction: ReactPropTypesfunc // returns ReactClass removeGroupAction: ReactPropTypesfunc // returns ReactClass addRuleAction: ReactPropTypesfunc // returns ReactClass removeRuleAction: ReactPropTypesfunc // returns ReactClass combinatorSelector: ReactPropTypesfunc // returns ReactClass fieldSelector: ReactPropTypesfunc // returns ReactClass operatorSelector: ReactPropTypesfunc // returns ReactClass valueEditor: ReactPropTypesfunc // returns ReactClass notToggle: ReactPropTypesfunc // returns ReactClass;
This is a custom controls object that allows you to override the control elements used. The following control overrides are supported:
addGroupAction
: By default a<button />
is used. The following props are passed:
label: ReactPropTypesstring // "+Group" className: ReactPropTypesstring // CSS classNames to be applied handleOnClick: ReactPropTypesfunc // Callback function to invoke adding a <RuleGroup /> rules: ReactPropTypesarray // Provides the number of rules already present for this group, level: ReactPropTypesnumber // The level of the current group
removeGroupAction
: By default a<button />
is used. The following props are passed:
label: ReactPropTypesstring // "x" className: ReactPropTypesstring // CSS classNames to be applied handleOnClick: ReactPropTypesfunc // Callback function to invoke removing a <RuleGroup /> rules: ReactPropTypesarray // Provides the number of rules already present for this group, level: ReactPropTypesnumber // The level of the current group
addRuleAction
: By default a<button />
is used. The following props are passed:
label: ReactPropTypesstring // "+Rule" className: ReactPropTypesstring // CSS classNames to be applied handleOnClick: ReactPropTypesfunc // Callback function to invoke adding a <Rule /> rules: ReactPropTypesarray // Provides the number of rules already present for this group, level: ReactPropTypesnumber // The level of the current group
removeRuleAction
: By default a<button />
is used. The following props are passed:
label: ReactPropTypesstring // "x" className: ReactPropTypesstring // CSS classNames to be applied handleOnClick: ReactPropTypesfunc // Callback function to invoke removing a <Rule /> level: ReactPropTypesnumber // The level of the current group
combinatorSelector
: By default a<select />
is used. The following props are passed:
options: ReactPropTypesarrayisRequired // Same as 'combinators' passed into QueryBuilder value: ReactPropTypesstring // Selected combinator from the existing query representation, if any className: ReactPropTypesstring // CSS classNames to be applied handleOnChange: ReactPropTypesfunc // Callback function to update query representation rules: ReactPropTypesarray // Provides the number of rules already present for this group level: ReactPropTypesnumber // The level of the current group
fieldSelector
: By default a<select />
is used. The following props are passed:
options: ReactPropTypesarrayisRequired // Same as 'fields' passed into QueryBuilder value: ReactPropTypesstring // Selected field from the existing query representation, if any operator: ReactPropTypesstring // Selected operator from the existing query representation, if any className: ReactPropTypesstring // CSS classNames to be applied handleOnChange: ReactPropTypesfunc // Callback function to update query representation level: ReactPropTypesnumber // The level the group this rule belongs to
operatorSelector
: By default a<select />
is used. The following props are passed:
field: ReactPropTypesstring // Field name corresponding to this Rule fieldData: ReactPropTypesobject // The entire object from the fields array for this field options: ReactPropTypesarrayisRequired // Return value of getOperators(field) value: ReactPropTypesstring // Selected operator from the existing query representation, if any className: ReactPropTypesstring // CSS classNames to be applied handleOnChange: ReactPropTypesfunc // Callback function to update query representation level: ReactPropTypesnumber // The level the group this rule belongs to
valueEditor
: By default an<input type="text" />
is used. The following props are passed:
field: ReactPropTypesstring // Field name corresponding to this Rule fieldData: ReactPropTypesobject // The entire object from the fields array for this field operator: ReactPropTypesstring // Operator name corresponding to this Rule value: ReactPropTypesstring // Value from the existing query representation, if any handleOnChange: ReactPropTypesfunc // Callback function to update the query representation type: ReactPropTypes // Type of editor to be displayed inputType: ReactPropTypesstring // Type of <input> if `type` is "text" values: ReactPropTypes // level: ReactPropTypesnumber // The level the group this rule belongs to className: ReactPropTypesstring // CSS classNames to be applied
notToggle
: By default,<label><input type="checkbox" />Not</label>
is used. The following props are passed:
checked: ReactPropTypesbool // Whether the input should be checked or not handleOnChange: ReactPropTypesfunc // Callback function to update the query representation title: ReactPropTypesstring // Tooltip for the label level: ReactPropTypesnumber // The level of the group className: ReactPropTypesstring // CSS classNames to be applied
getOperators
(Optional)
function(field: string): []
This is a callback function invoked to get the list of allowed operators for the given field.
getValueEditorType
(Optional)
function(field: string, operator: string): string
This is a callback function invoked to get the type of ValueEditor
for the given field and operator. Allowed values are "text"
(the default), "select"
, "checkbox"
, and "radio"
.
getInputType
(Optional)
function(field: string, operator: string): string
This is a callback function invoked to get the type
of <input />
for the given field and operator (only applicable when getValueEditorType
returns "text"
or a falsy value). If no function is provided, "text"
is used as the default.
getValues
(Optional)
function(field: string, operator: string): []
This is a callback function invoked to get the list of allowed values for the given field and operator (only applicable when getValueEditorType
returns "select"
or "radio"
). If no function is provided, an empty array is used as the default.
onQueryChange
(Optional)
function(queryJSON: RuleGroup): void
This is a notification that is invoked anytime the query configuration changes. The query is provided as a JSON structure, as shown below:
controlClassnames
(Optional)
This can be used to assign specific CSS
classes to various controls that are created by the <QueryBuilder />
. This is an object with the following properties:
queryBuilder: string // Root <div> element ruleGroup: string // <div> containing the RuleGroup header: string // <div> containing the RuleGroup header controls combinators: string // <select> control for combinators addRule: string // <button> to add a Rule addGroup: string // <button> to add a RuleGroup removeGroup: string // <button> to remove a RuleGroup notToggle: string // <label> on the "not" toggle rule: string // <div> containing the Rule fields: string // <select> control for fields operators: string // <select> control for operators value: string // <input> for the field value removeRule: string // <button> to remove a Rule
translations
(Optional)
This can be used to override translatable texts applied to various controls that are created by the <QueryBuilder />
. This is an object with the following properties:
fields: title: "Fields" operators: title: "Operators" value: title: "Value" removeRule: label: "x" title: "Remove rule" removeGroup: label: "x" title: "Remove group" addRule: label: "+Rule" title: "Add rule" addGroup: label: "+Group" title: "Add group" combinators: title: "Combinators" notToggle: title: "Invert this group"
showCombinatorsBetweenRules
(Optional)
boolean
Pass true
to show the combinators (and/or) between rules and rule groups instead of at the top of rule groups. This can make some queries easier to understand as it encourages a more natural style of reading.
showNotToggle
(Optional)
boolean
Pass true
to show the "Not" toggle switch for each rule group.
formatQuery
formatQuery
formats a given query in either JSON or SQL format. Example:
; const query = id: 'g-b6SQ6WCcup8e37xhydwHE' rules: id: 'r-zITQOjVEWlsU1fncraSNn' field: 'firstName' value: 'Steve' operator: '=' id: 'r-zVx7ARNak3TCZNFHkwMG2' field: 'lastName' value: 'Vai' operator: '=' combinator: 'and' not: false; console; // '(firstName = "Steve" and lastName = "Vai")'
An optional third argument can be passed into formatQuery
if you need to control the way the value portion of the output is processed. (This is only applicable when the format is "sql"
.)
const query = id: 'g-J5GsbcFmZ6xOJCLPPKIfE' rules: id: 'r-KneYcwIPPHDGSogtKhG4g' field: 'instrument' value: 'Guitar' 'Vocals' operator: 'in' id: 'r-wz6AkZbzSyDYbPk1AxgvO' field: 'lastName' value: 'Vai' operator: '=' combinator: 'and' not: false; const valueProcessor = { if operator === 'in' // Assuming `value` is an array, such as from a multi-select return `()`; else return `""`; }; console; // '(instrument in ("Guitar","Vocals") and lastName = "Vai")'
Development
Changelog Generation
We are using github-changes to generate the changelog.
To use it:
- tag your commit using semantic versioning
- run
npm run generate-changelog
- enter your github credentials at the prompt
- commit
- push your commit and tags
Credits
This component was inspired by prior work from: