react-query-builder-semantic
Credits
This component was inspired by prior work from:
Thanks to sapientglobalmarkets for providing us this component's code base
Thanks to coryhouse for providing the medium for documentation and deployment
Getting Started
npm install react-query-builder-semantic --save
Semantic UI React Integration
Documentation
Query Builder Semantic API
Usage
Import QueryBuilderSemantic with default styles.
import 'semantic-ui-css/semantic.min.css';import QueryBuilderSemantic from 'react-query-builder-semantic/lib/QueryBuilderSemantic';
Import QueryBuilderSemantic without styles.
import 'semantic-ui-css/semantic.min.css';import QueryBuilderSemantic from 'react-query-builder-semantic/lib/QueryBuilderSemantic/QueryBuilderSemantic';
QueryBuilderSemantic
<QueryBuilderSemantic />
is the only top-level component exposed from this library. It supports the following properties:
ruleSemanticProps (Required)
Semantic Props for valueEditor, fieldSelector, valueSelector, segment, deleteRuleButton on a rule. Default is :
ruleSemanticProps: segment: size: 'tiny' padded: true compact: true valueEditor: size: 'tiny' type: "text" fieldSelector: scrolling: true selection: true search: true operatorSelector: scrolling: true selection: true search: true deleteRuleButton: size: 'tiny' compact: true circular: true floated: 'right' icon: 'remove'
ruleGroupSemanticProps (Required)
Semantic Props for dropDown, addGroupButton, removeGroupButton, segment, addRuleButton on a group. Default is :
ruleGroupSemanticProps: dropDown: button: true attached: 'left' className: 'icon' size: 'tiny' labeled: true scrolling: true icon: 'filter' segment: size: 'tiny' addGroupButton: attached: true size: 'tiny' compact: true icon: 'plus' removeGroupButton: attached: 'right' size: 'tiny' compact: true icon: 'minus' addRuleButton: attached: 'right' size: 'tiny' compact: true icon: 'plus'
fields (Required)
[ {value:String, text:String} ]
The array of fields that should be used. Each field should be an object with
{value:String, text:String}
values (Optional)
[ {value:String, text:String} ]
The array of values that should be used. Each value should be an object with
{value:String, text:String}
operators (Optional)
[ {value:String, text:String} ]
The array of operators that should be used. The default operators include:
value: 'null' text: 'Is Null' value: 'notNull' text: 'Is Not Null' value: 'in' text: 'In' value: 'notIn' text: 'Not In' value: '=' text: '=' value: '!=' text: '!=' value: '<' text: '<' value: '>' text: '>' value: '<=' text: '<=' value: '>=' text: '>='
combinators (Optional)
[ {value:String, text:String},{content:any} ]
The array of combinators that should be used for RuleGroups. The default set includes:
text: 'AND' value: 'and' content: <Label color='purple' content='AND' circular /> text: 'OR' value: 'or' content: <Label color='blue' content='OR' circular />
combinatorColors
[ {color:String, combinator:String} ]
The array of combinator colors to use for the selected combinator that should be used for RuleGroups. The default set includes:
combinatorColors: color: 'purple' combinator: 'and' color: 'blue' combinator: 'or'
controlElements (Optional)
ReactPropTypesshape fieldSelector: ReactPropTypesfunc //returns ReactClass operatorSelector: ReactPropTypesfunc //returns ReactClass valueEditor: ReactPropTypesfunc //returns ReactClass
This is a custom controls object that allows you to override the control elements used. The following control overrides are supported:
-
fieldSelector
: By default a<Dropdown scrolling selection search />
is used. The following props are passed:/*** Semantic Props for fieldSelector on a rule*/ruleSemanticProps: PropTypesshape/*** Semantic Dropdown props on a rule* https://react.semantic-ui.com/modules/dropdown/*/fieldSelector: PropTypesanyoptions: ReactPropTypesarrayisRequired //same as 'fields' passed into QueryBuilderSemanticvalue: ReactPropTypesstring //selected field from the existing query representation, if anyclassName: ReactPropTypesstring //css classNames to be appliedhandleOnChange: ReactPropTypesfunc //callback function to update query representation -
operatorSelector
: By default a<<Dropdown scrolling selection search />
is used. The following props are passed:/*** Semantic Props for valueSelector on a rule*/ruleSemanticProps: PropTypesshape/*** Semantic Dropdown props on a rule* https://react.semantic-ui.com/modules/dropdown/*/operatorSelector: PropTypesanyoptions: ReactPropTypesarrayisRequired //same as 'fields' passed into QueryBuilderSemanticvalue: ReactPropTypesstring //selected operator from the existing query representation, if anyclassName: ReactPropTypesstring //css classNames to be appliedhandleOnChange: ReactPropTypesfunc //callback function to update query representation -
valueEditor
: By default a<Input type="text" />
is used. The following props are passed:/*** Semantic Props for valueEditor on a rule*/ruleSemanticProps: PropTypesshape/*** Semantic Input props on a rule* https://react.semantic-ui.com/elements/input/*/valueEditor: PropTypesanyvalues: ReactPropTypesarray //values corresponding to this Rulefield: ReactPropTypesstring //field name corresponding to this Ruleoperator: ReactPropTypesstring //operator name corresponding to this Rulevalue: ReactPropTypesstring //value from the existing query representation, if anyhandleOnChange: ReactPropTypesfunc //callback function to update the query representation
getOperators (Optional)
function(field):[]
This is a callback function invoked to get the list of allowed operators for the given field
onQueryChange (Optional)
function(queryJSON):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 <QueryBuilderSemantic />
. This is an object
with the following properties:
/** *Root <div> element */ queryBuilder: PropTypesstring /** *<Segment.Group> containing the RuleGroup */ ruleGroup: PropTypesstring /** *<Dropdown> control for combinators */ combinators: PropTypesstring /** *<Button> to add a Rule */ addRule: PropTypesstring /** *<Button> to add a RuleGroup */ addGroup: PropTypesstring /** *<Button> to remove a RuleGroup */ removeGroup: PropTypesstring /** *<Segment> containing the Rule */ rule: PropTypesstring /** *<Dropdown> control for fields */ fields: PropTypesstring /** *<Dropdown> control for operators */ operators: PropTypesstring /** *<Input> for the field value */ value: PropTypesstring /** *<Button> to remove a Rule */ removeRule: PropTypesstring
translations (Optional)
This can be used to override translatable texts applied to various controls
that are created by the <QueryBuilderSemantic />
. This is an object
with the following properties:
fields: title: "Fields" operators: title: "Operators" value: title: "Value" removeRule: title: "Remove rule" removeGroup: title: "Remove group" addRule: title: "Add rule" addGroup: title: "Add group" combinators: title: "Combinators"
Query Builder API
Usage
Import QueryBuilder with default styles.
import QueryBuilder from 'react-query-builder-semantic/lib/QueryBuilder';
Import QueryBuilder without styles.
import QueryBuilder from 'react-query-builder-semantic/lib/QueryBuilder/QueryBuilder';
QueryBuilder
<QueryBuilder />
is the only top-level component exposed from this library. It supports the following properties:
fields (Required)
[ {name:String, label:String, id:ID} ]
The array of fields that should be used. Each field should be an object with
{name:String, label:String, id:ID}
|
The Id is optional, if you do not provide an id for a field then the name will be used
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: '>='
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
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 appliedhandleOnClick: 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 appliedhandleOnClick: 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 appliedhandleOnClick: 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 appliedhandleOnClick: 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 QueryBuildervalue: ReactPropTypesstring //selected combinator from the existing query representation, if anyclassName: ReactPropTypesstring //css classNames to be appliedhandleOnChange: ReactPropTypesfunc //callback function to update query representationrules: ReactPropTypesarray //Provides the number of rules already present for this grouplevel: 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 QueryBuildervalue: ReactPropTypesstring //selected field from the existing query representation, if anyclassName: ReactPropTypesstring //css classNames to be appliedhandleOnChange: ReactPropTypesfunc //callback function to update query representationlevel: 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 Ruleoptions: ReactPropTypesarrayisRequired //return value of getOperators(field)value: ReactPropTypesstring //selected operator from the existing query representation, if anyclassName: ReactPropTypesstring //css classNames to be appliedhandleOnChange: ReactPropTypesfunc //callback function to update query representationlevel: ReactPropTypesnumber //The level the group this rule belongs to -
valueEditor
: By default a<input type="text" />
is used. The following props are passed:field: ReactPropTypesstring //field name corresponding to this Ruleoperator: ReactPropTypesstring //operator name corresponding to this Rulevalue: ReactPropTypesstring //value from the existing query representation, if anyhandleOnChange: ReactPropTypesfunc //callback function to update the query representationlevel: ReactPropTypesnumber //The level the group this rule belongs to
getOperators (Optional)
function(field):[]
This is a callback function invoked to get the list of allowed operators for the given field
onQueryChange (Optional)
function(queryJSON):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:
/** *Root <div> element */ queryBuilder: PropTypesstring /** *<div> containing the RuleGroup */ ruleGroup: PropTypesstring /** *<select> control for combinators */ combinators: PropTypesstring /** *<button> to add a Rule */ addRule: PropTypesstring /** *<button> to add a RuleGroup */ addGroup: PropTypesstring /** *<button> to remove a RuleGroup */ removeGroup: PropTypesstring /** *<div> containing the Rule */ rule: PropTypesstring /** *<select> control for fields */ fields: PropTypesstring /** *<select> control for operators */ operators: PropTypesstring /** *<input> for the field value */ value: PropTypesstring /** *<button> to remove a Rule */ removeRule: PropTypesstring
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"