QueryBuilder controlElements prop

Refer to the TypeScript reference page for information about the types and interfaces referenced below.

The controlElements prop object allows you to override the default components.

Usage example

function App() {
  return (
    <QueryBuilder controlElements={{ valueEditor: CustomValueEditor }}>
  )
}

Properties

The following control overrides are supported per the Controls interface. Setting a control override to null will hide the element by rendering it as () => null.

Property	Type
actionElement	React.ComponentType<ActionProps>
addGroupAction	React.ComponentType<ActionWithRulesAndAddersProps> | null
addRuleAction	React.ComponentType<ActionWithRulesAndAddersProps> | null
cloneGroupAction	React.ComponentType<ActionWithRulesProps> | null
cloneRuleAction	React.ComponentType<ActionProps> | null
combinatorSelector	React.ComponentType<CombinatorSelectorProps> | null
dragHandle	React.ForwardRefExoticComponent<DragHandleProps & React.RefAttributes<HTMLSpanElement>> | null
fieldSelector	React.ComponentType<FieldSelectorProps> | null
inlineCombinator	React.ComponentType<InlineCombinatorProps> | null
lockGroupAction	React.ComponentType<ActionWithRulesProps> | null
lockRuleAction	React.ComponentType<ActionProps> | null
matchModeEditor	React.ComponentType<MatchModeEditorProps> | null
notToggle	React.ComponentType<NotToggleProps> | null
operatorSelector	React.ComponentType<OperatorSelectorProps> | null
removeGroupAction	React.ComponentType<ActionWithRulesProps> | null
removeRuleAction	React.ComponentType<ActionProps> | null
rule	React.ComponentType<RuleProps>
ruleGroup	React.ComponentType<RuleGroupProps>
ruleGroupBodyElements	React.ComponentType<RuleGroupProps & ReturnType<typeof useRuleGroup>>
ruleGroupHeaderElements	React.ComponentType<RuleGroupProps & ReturnType<typeof useRuleGroup>>
shiftActions	React.ComponentType<ShiftActionsProps> | null
valueEditor	React.ComponentType<ValueEditorProps> | null
valueSelector	React.ComponentType<ValueSelectorProps>
valueSourceSelector	React.ComponentType<ValueSourceSelectorProps> | null

actionElement

The component for all button-type controls. Default is ActionElement. Receives props per the ActionProps, ActionWithRulesProps, or ActionWithRulesAndAddersProps interface depending on the control, which can be any of the following:

• Usage example
• Properties
  • actionElement
  • addGroupAction
  • addRuleAction
  • cloneGroupAction
  • cloneRuleAction
  • combinatorSelector
  • dragHandle
  • fieldSelector
  • inlineCombinator
  • lockGroupAction
  • lockRuleAction
  • matchModeEditor
  • notToggle
  • operatorSelector
  • removeGroupAction
  • removeRuleAction
  • rule
  • ruleGroup
  • ruleGroupBodyElements
  • ruleGroupHeaderElements
  • shiftActions
  • valueEditor
  • valueSelector
  • valueSourceSelector

For example, this:

<QueryBuilder controlElements={{ actionElement: MyAwesomeButton }} />

...is equivalent to this:

<QueryBuilder
  controlElements={{
    addGroupAction: MyAwesomeButton
    addRuleAction: MyAwesomeButton
    cloneGroupAction: MyAwesomeButton
    cloneRuleAction: MyAwesomeButton
    lockGroupAction: MyAwesomeButton
    lockRuleAction: MyAwesomeButton
    removeGroupAction: MyAwesomeButton
    removeRuleAction: MyAwesomeButton
  }}
/>

addGroupAction

Adds a sub-group to the current group. Default is ActionElement.

Props for addGroupAction

Per the ActionWithRulesAndAddersProps interface:

Prop	Type	Description
label	ReactNode	translations.addGroup.label, e.g. "+ Group"
title	string	translations.addGroup.title, e.g. "Add group"
className	string	CSS classNames to be applied
handleOnClick	(e: React.MouseEvent, context?: any) => void	Adds a new sub-group to this group
rules	RuleOrGroupArray	The rules array for this group
ruleOrGroup	RuleGroupTypeAny	This group
level	number	The level of this group
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this group
disabled	boolean	Whether this group is disabled/locked
path	Path	Path of this group
schema	Schema	Query schema

addRuleAction

Adds a rule to the current group. Default is ActionElement.

Props for addRuleAction

Per the ActionWithRulesAndAddersProps interface:

Prop	Type	Description
label	ReactNode	translations.addRule.label, e.g. "+ Rule"
title	string	translations.addRule.title, e.g. "Add rule"
className	string	CSS classNames to be applied
handleOnClick	(e: React.MouseEvent, context?: any) => void	Adds a new rule to this rule
rules	RuleOrGroupArray	The rules array for this rule
ruleOrGroup	RuleGroupTypeAny	This rule
level	number	The level of this rule
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this rule
disabled	boolean	Whether this rule is disabled/locked
path	Path	Path of this rule
schema	Schema	Query schema

cloneGroupAction

Clones the current group. Default is ActionElement.

Props for cloneGroupAction

Per the ActionWithRulesProps interface:

Prop	Type	Description
label	ReactNode	translations.cloneRuleGroup.label, e.g. "⧉"
title	string	translations.cloneRuleGroup.title, e.g. "Clone group"
className	string	CSS classNames to be applied
handleOnClick	(e: React.MouseEvent) => void	Clones this group
rules	RuleOrGroupArray	The rules array for this group
ruleOrGroup	RuleGroupTypeAny	This group
level	number	The level of this group
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this group
disabled	boolean	Whether this group is disabled/locked
path	Path	Path of this group
schema	Schema	Query schema

cloneRuleAction

Clones the current rule. Default is ActionElement.

Props for cloneRuleAction

Per the ActionProps interface:

Prop	Type	Description
label	string	translations.cloneRule.label, e.g. "⧉"
title	string	translations.cloneRule.title, e.g. "Clone rule"
className	string	CSS classNames to be applied
handleOnClick	(e: React.MouseEvent) => void	Clones the rule
ruleOrGroup	RuleType	This rule
level	number	The level of this rule
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this rule
disabled	boolean	Whether this rule is disabled/locked
path	Path	Path of this rule
schema	Schema	Query schema

combinatorSelector

Selects the combinator property for the current group, or the current independent combinator value. Default is ValueSelector.

Props for combinatorSelector

Per the CombinatorSelectorProps interface:

Prop	Type	Description
options	OptionList	Same as combinators prop passed into QueryBuilder
value	string	Selected combinator from the existing query representation, if any
className	string	CSS classNames to be applied
handleOnChange	(value: any) => void	Updates the group's combinator
rules	RuleOrGroupArray	The rules array for this group
title	string	translations.combinators.title, e.g. "Combinators"
level	number	The level of this group
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this group
disabled	boolean	Whether this group is disabled/locked
path	Path	Path of this group
schema	Schema	Query schema

dragHandle

Provides a draggable handle for reordering rules and groups. Default is DragHandle. Only rendered if drag-and-drop is enabled. Note that this component must be based on React.forwardRef.

Props for dragHandle

Receives the forwarded ref and the following props per the DragHandleProps interface:

Prop	Type	Description
label	ReactNode	translations.dragHandle.label, e.g. "⁞⁞"
title	string	translations.dragHandle.title, e.g. "Drag handle"
className	string	CSS classNames to be applied
level	number	The level of this rule/group
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this rule/group
disabled	boolean	Whether this rule/group is disabled/locked
path	Path	Path of this rule/group
schema	Schema	Query schema
ruleOrGroup	RuleGroupTypeAny | RuleType	This group or rule, depending on the parent component

fieldSelector

Selects the field property for the current rule. Default is ValueSelector.

Props for fieldSelector

Per the FieldSelectorProps interface:

Prop	Type	Description
options	OptionList<Field>	Same as fields prop passed into QueryBuilder
value	string	Selected field from the existing query representation, if any
title	string	translations.fields.title, e.g. "Fields"
operator	string	Selected operator from the existing query representation, if any
className	string	CSS classNames to be applied
handleOnChange	(value: any) => void	Updates the rule's field
level	number	The level of this rule
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this rule
disabled	boolean	Whether this rule is disabled/locked
path	Path	Path of this rule
schema	Schema	Query schema
rule	RuleType	This rule

inlineCombinator

A small wrapper around the combinatorSelector component. Default is InlineCombinator.

Props for inlineCombinator

Per the InlineCombinatorProps interface, which extends CombinatorSelectorProps:

Prop	Type	Description
component	Schema['controls']['combinatorSelector']	Same as the combinatorSelector component

lockGroupAction

Locks the current group (sets the disabled property to true). Default is ActionElement.

Props for lockGroupAction

Per the ActionWithRulesProps interface:

Prop	Type	Description
label	ReactNode	translations.lockGroup.label or translations.lockGroupDisabled.label, e.g. "🔓" when unlocked and "🔒" when locked
title	string	translations.lockGroup.title or translations.lockGroupDisabled.title, e.g. "Lock group" or "Unlock group"
className	string	CSS classNames to be applied
handleOnClick	(e: React.MouseEvent) => void	Locks the group
rules	RuleOrGroupArray	The rules present for this group
ruleOrGroup	RuleGroupTypeAny	This group
level	number	The level of this group
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this group
disabled	boolean	Whether this group is disabled/locked
disabledTranslation	string	translations.lockGroupDisabled if parent group is not disabled, otherwise undefined
path	Path	Path of this group
schema	Schema	Query schema

lockRuleAction

Locks the current rule (sets the disabled property to true). Default is ActionElement.

Props for lockRuleAction

Per the ActionWithRulesProps interface:

Prop	Type	Description
label	ReactNode	translations.lockRule.label or translations.lockRuleDisabled.label, e.g. "🔓" when unlocked and "🔒" when locked
title	string	translations.lockRule.title or translations.lockRuleDisabled.title, e.g. "Lock rule" or "Unlock rule"
className	string	CSS classNames to be applied
handleOnClick	(e: React.MouseEvent) => void	Locks the rule
ruleOrGroup	RuleType	This rule
level	number	The level of this rule
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this rule
disabled	boolean	Whether this rule is disabled/locked
disabledTranslation	string	translations.lockRuleDisabled if parent group is not disabled, otherwise undefined
path	Path	Path of this rule
schema	Schema	Query schema

matchModeEditor

Manages the match property for the current rule, including the mode and threshold (see Subqueries). Default is MatchModeEditor.

Props for matchModeEditor

Per the MatchModeEditorProps interface:

Prop	Type	Description
match	MatchConfig	Current match configuration for this rule
options	OptionList<MatchMode>	Available match modes for the current field
field	string	Field name corresponding to this rule
fieldData	FullField	The entire object from the fields array for this field
rule	RuleType	This rule
selectorComponent	ComponentType<ValueSelectorProps>	Component to use for the match mode selector
numericEditorComponent	ComponentType<ValueEditorProps>	Component to use for the match threshold editor
classNames	{ matchMode: string; matchThreshold: string }	CSS classNames for sub-components
value	string	Current match mode value
className	string	CSS classNames to be applied
handleOnChange	(value: any) => void	Updates the rule's match configuration
level	number	The level of this rule
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this rule
disabled	boolean	Whether this rule is disabled/locked
path	Path	Path of this rule
schema	Schema	Query schema

notToggle

Toggles the not property of the current group between true and false. Default is NotToggle.

Props for notToggle

Per the NotToggleProps interface:

Prop	Type	Description
label	ReactNode	translations.notToggle.label, e.g. "Not"
title	string	translations.notToggle.title, e.g. "Invert this group"
className	string	CSS classNames to be applied
handleOnChange	(checked: boolean) => void	Updates the group's not property
checked	boolean	Whether the input should be checked or not
level	number	The level of this group
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this group
disabled	boolean	Whether this group is disabled/locked
path	Path	Path of this group
schema	Schema	Query schema
ruleGroup	RuleGroupTypeAny	This group

operatorSelector

Selects the operator property for the current rule. Default is ValueSelector.

Props for operatorSelector

Per the OperatorSelectorProps interface:

Prop	Type	Description
field	string	Field name corresponding to this rule
fieldData	Field	The entire object from the fields array for this field
options	OptionList<Operator>	Return value of getOperators(field, { fieldData })
value	string	Selected operator from the existing query representation, if any
title	string	translations.operators.title, e.g. "Operators"
className	string	CSS classNames to be applied
handleOnChange	(value: any) => void	Updates the rule's operator
level	number	The level of this rule
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this rule
disabled	boolean	Whether this rule is disabled/locked
path	Path	Path of this rule
schema	Schema	Query schema
rule	RuleType	This rule

removeGroupAction

Removes the current group from its parent group's rules array. Default is ActionElement.

Props for removeGroupAction

Per the ActionWithRulesProps interface:

Prop	Type	Description
label	ReactNode	translations.removeGroup.label, e.g. "⨯"
title	string	translations.removeGroup.title, e.g. "Remove group"
className	string	CSS classNames to be applied
handleOnClick	(e: React.MouseEvent) => void	Removes the group
rules	RuleOrGroupArray	The rules array for this group
ruleOrGroup	RuleGroupTypeAny	This group
level	number	The level of this group
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this group
disabled	boolean	Whether this group is disabled/locked
path	Path	Path of this group
schema	Schema	Query schema

removeRuleAction

Removes the current rule from its parent group's rules array. Default is ActionElement.

Props for removeRuleAction

Per the ActionProps interface:

Prop	Type	Description
label	ReactNode	translations.removeRule.label, e.g. "⨯"
title	string	translations.removeRule.title, e.g. "Remove rule"
className	string	CSS classNames to be applied
handleOnClick	(e: React.MouseEvent) => void	Removes the rule
ruleOrGroup	RuleType	This rule
level	number	The level of this rule
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this rule
disabled	boolean	Whether this rule is disabled/locked
path	Path	Path of this rule
schema	Schema	Query schema

rule

Rule layout component. Default is Rule.

Props for rule

Per the RuleProps interface:

Prop	Type	Description
id	string	Unique identifier for this rule
path	Path	Path of this rule
rule	RuleType	The rule object
translations	Translations	The default translations merged with the translations prop
schema	Schema	Query schema
actions	QueryActions	Query update functions
context	any	Container for custom props that are passed to all components
disabled	boolean	Whether the rule itself is disabled
shiftUpDisabled	boolean	Whether shifting the rule up is disallowed
shiftDownDisabled	boolean	Whether shifting the rule down is disallowed
parentDisabled	boolean	Whether the parent group of this rule is disabled

tip

If you enable drag-and-drop and want to use a custom Rule component, use the controlElements prop on the QueryBuilderDnD context provider instead of QueryBuilder.

ruleGroup

Rule group layout component. Default is RuleGroup.

Props for ruleGroup

Per the RuleGroupProps interface:

Prop	Type	Description
id	string	Unique identifier for this group
path	Path	Path of this group
ruleGroup	RuleGroupTypeAny	The group object
translations	Translations	The default translations merged with the translations prop
schema	Schema	Query schema
actions	QueryActions	Query update functions
context	any	Container for custom props that are passed to all components
disabled	boolean	Whether the group itself is disabled
shiftUpDisabled	boolean	Whether shifting the group up is disallowed
shiftDownDisabled	boolean	Whether shifting the group down is disallowed
parentDisabled	boolean	Whether the parent group of this group is disabled

tip

If you enable drag-and-drop and want to use a custom RuleGroup component, use the controlElements prop on the QueryBuilderDnD context provider instead of QueryBuilder.

ruleGroupBodyElements

Rule group body elements. Default is RuleGroupBodyComponents, which returns an array containing only the elements themselves (no HTML or React Native wrapper element). Receives the same props as ruleGroup, in addition to the return value of the useRuleGroup hook.

ruleGroupHeaderElements

Rule group header elements. Default is RuleGroupHeaderComponents, which returns a React Fragment containing only the elements themselves (no HTML or React Native wrapper element). Receives the same props as ruleGroup, in addition to the return value of the useRuleGroup hook.

shiftActions

Shifts the current rule/group up or down in the query hierarchy. Default is ShiftActions.

Props for shiftActions

Per the ShiftActionsProps interface:

Prop	Type	Description
labels	{ shiftUp: ReactNode; shiftDown: ReactNode; }	translations.shiftActionUp.label and translations.shiftActionDown.label, e.g. "˄" and "˅"
titles	{ shiftUp: string; shiftDown: string; }	translations.shiftActionUp.title and translations.shiftActionDown.title, e.g. "Shift up" and "Shift down"
className	string	CSS classNames to be applied
ruleOrGroup	RuleGroupTypeAny	This rule/group
level	number	The level of this rule/group
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this rule/group
disabled	boolean	Whether this rule/group is disabled/locked
path	Path	Path of this rule/group
schema	Schema	Query schema
shiftUp	() => void	Method to shift the rule/group up one place
shiftDown	() => void	Method to shift the rule/group down one place
shiftUpDisabled	boolean	Whether shifting the rule/group up is disallowed
shiftDownDisabled	boolean	Whether shifting the rule/group down is disallowed

valueEditor

Updates the value property for the current rule. Default is ValueEditor.

Props for valueEditor

Per the ValueEditorProps interface:

Prop	Type	Description
field	string	Field name corresponding to this rule
fieldData	Field	The entire object from the fields array for this field
operator	string	Operator name corresponding to this rule
value	string	value from the existing query representation, if any
title	string	translations.value.title, e.g. "Value"
handleOnChange	(value: any) => void	Updates the rule's value
type	ValueEditorType	Type of editor to be displayed
inputType	string	Intended @type attribute of the <input>, if type prop is "text"
values	any[]	List of available values for this rule
className	string	CSS classNames to be applied
valueSource	ValueSource	Value source for this rule
listsAsArrays	boolean	Whether to manage value lists (i.e. "between"/"in" operators) as arrays
parseNumbers	ParseNumberMethod	Whether to parse real numbers from strings
separator	ReactNode	Separator element for series of editors (i.e. "between" operator)
level	number	The level of this rule
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this rule
disabled	boolean	Whether this rule is disabled/locked
path	Path	Path of this rule
schema	Schema	Query schema
rule	RuleType	This rule

valueSelector

The component for all value selector controls. Default is ValueSelector. Receives props per the CombinatorSelectorProps, FieldSelectorProps, OperatorSelectorProps, or ValueSourceSelectorProps interface depending on the control, which can be any of the following:

• combinatorSelector
• fieldSelector
• operatorSelector
• valueSourceSelector

For example, this:

<QueryBuilder controlElements={{ valueSelector: MyAwesomeSelector }} />

...is equivalent to this:

<QueryBuilder
  controlElements={{
    combinatorSelector: MyAwesomeSelector
    fieldSelector: MyAwesomeSelector
    operatorSelector: MyAwesomeSelector
    valueSourceSelector: MyAwesomeSelector
  }}
/>

valueSourceSelector

Selects the valueSource property for the current rule. Default is ValueSelector.

Props for valueSourceSelector

Per the ValueSourceSelectorProps interface:

Prop	Type	Description
field	string	Field name corresponding to this rule
fieldData	Field	The entire object from the fields array for the selected field
options	OptionList<ValueSourceOption>	Return value of getValueSources(field, operator, { fieldData })
value	ValueSource	Selected value source for this rule, if any
title	string	translations.valueSourceSelector.title, e.g. "Value source"
className	string	CSS classNames to be applied
handleOnChange	(value: any) => void	Updates the rule's valueSource
level	number	The level of this rule
context	any	Container for custom props that are passed to all components
validation	boolean | ValidationResult	Validation result of this rule
disabled	boolean	Whether this rule is disabled/locked
path	Path	Path of this rule
schema	Schema	Query schema
rule	RuleType	This rule