Skip to main content
Version: v7

Miscellaneous

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

A non-comprehensive list of exports from react-querybuilder.

Utilities​

transformQuery​

function transformQuery(query: RuleGroupTypeAny, options: QueryTransformerOptions): any;

This function recursively steps through a query object (RuleGroupType or RuleGroupTypeIC), passing each RuleType object to a provided ruleProcessor function. Available options include:

  • ruleProcessor: Custom processing for each rule.
  • ruleGroupProcessor: Custom processing for each rule group. Each group's rules property will be retained and recursively processed regardless of any other mutations.
  • propertyMap: Keys in the rule or group objects that match keys in this object will be renamed to the corresponding value.
  • combinatorMap: Best explained with an example: {and: "&&", or: "||"} would translate "and"/"or" combinators to "&&"/"||", respectively.
  • operatorMap: Convert operators that match the keys in this object to the corresponding values, e.g. {"=": "=="}.
  • deleteRemappedProperties: Defaults to true; pass false to leave the remapped properties and the original properties in the resulting object.

See the test suite for example usage.

defaultValidator​

function defaultValidator(query: RuleGroupTypeAny): {
  [id: string]: { valid: boolean; reasons?: string[] };
};

Pass validator={defaultValidator} to automatically validate groups (rules will be ignored). A group will be marked invalid if either of the following are true:

  1. The group has no child rules or groups (query.rules.length === 0)
  2. The group has a missing/invalid combinator property and more than one child rule or group (rules.length >= 2).

You can see an example of the default validator in action in the demo if you check the 'Use validation' option. Empty groups will have bold text on their "+ Rule" button and a description of the situation where the rules normally appear.

findPath​

function findPath(path: Path, query: RuleGroupTypeAny): RuleType | RuleGroupTypeAny;

findPath is a utility function for finding the rule or group within the query hierarchy that has a given path. Useful in custom onAddRule and onAddGroup functions.

More extensive documentation on the path property is here.

convertQuery​

function convertQuery(query: RuleGroupType): RuleGroupTypeIC;
// OR
function convertQuery(query: RuleGroupTypeIC): RuleGroupType;

convertQuery toggles a query between the conventional RuleGroupType structure–with combinators at the group level–and the "independent combinators" structure RuleGroupTypeIC–with combinators between every other rule/group.

convertToIC and convertFromIC do the same thing as convertQuery, but only in the directions indicated by their respective names.

Query tools​

Several methods are available to assist with programmatic manipulation of query objects. These methods are used by the <QueryBuilder /> component itself, so they are guaranteed to achieve the same result as a corresponding UI-based update. Each of these methods returns the modified query.

Check out the "External controls" Tips & Tricks page to see these methods used outside the context of the <QueryBuilder /> component.

add​

(query: RuleGroupTypeAny, ruleOrGroup: RuleGroupTypeAny | RuleType, path: Path, options: AddOptions) => RuleGroupTypeAny

Adds a rule or group (and an independent combinator if necessary, to keep the query valid).

AddOptions
interface AddOptions {
  /** Only applicable for `RuleGroupTypeIC`. Default is `defaultCombinators`. */
  combinators?: OptionList;
}

remove​

(query: RuleGroupTypeAny, path: Path) => RuleGroupTypeAny

Removes a rule or group (and the preceding independent combinator, if one exists).

update​

(query: RuleGroupTypeAny, prop: string, value: any, path: Path, options: UpdateOptions) => RuleGroupTypeAny

Updates a property of a rule or group, or updates an independent combinator.

UpdateOptions
interface UpdateOptions {
  /** Resets `operator` and `value` when `field` changes. Default is `true`. */
  resetOnFieldChange?: boolean;
  /** Resets `value` when `operator` changes. Default is `false`. */
  resetOnOperatorChange?: boolean;
  /** Determines the default operator name for a given field. */
  getRuleDefaultOperator?: (field: string) => string;
  /** Determines the valid value sources for a given field and operator. */
  getValueSources?: (field: string, operator: string) => ValueSources;
  /** Used when the `value` property is reset (see `resetOn*Change` options). */
  getRuleDefaultValue?: (rule: RuleType) => any;
}

move​

(query: RuleGroupTypeAny, oldPath: Path, newPath: Path, options: MoveOptions) => RuleGroupTypeAny

Moves (or clones, with a new id) a rule or group to a new location in the query tree.

MoveOptions
interface MoveOptions {
  /** Copy the source rule/group instead of move. Default is `false`. */
  clone?: boolean;
  /** Only applicable for `RuleGroupTypeIC`. Default is `defaultCombinators`. */
  combinators?: OptionList;
}

Defaults​

The default configuration objects are exported for convenience, including the following.

The default components are also exported: