Skip to main content
Version: v6

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, used with the independentCombinators prop).

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 following default configuration objects are exported for convenience.

The default components are also exported: