Skip to main content
Version: Next

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) to the group at the specified path.

AddOptions

export interface AddOptions {
  /**
   * If the query extends `RuleGroupTypeIC` (i.e. the query has independent
   * combinators), then the first combinator in this list will be inserted
   * before the new rule/group if the parent group is not empty. This option
   * is overridden by `combinatorPreceding`.
   */
  combinators?: OptionList;
  /**
   * If the query extends `RuleGroupTypeIC` (i.e. the query has independent
   * combinators), then this combinator will be inserted before the new rule/group
   * if the parent group is not empty. This option will supersede `combinators`.
   */
  combinatorPreceding?: string;
  /**
   * ID generator.
   */
  idGenerator?: () => string;
}

Source: /packages/react-querybuilder/src/utils/queryTools.ts#L21-L39

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

export interface UpdateOptions {
  /**
   * When updating the `field` of a rule, the rule's `operator`, `value`, and `valueSource`
   * will be reset to their respective defaults. Defaults to `true`.
   */
  resetOnFieldChange?: boolean;
  /**
   * When updating the `operator` of a rule, the rule's `value` and `valueSource`
   * will be reset to their respective defaults. Defaults to `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;
  /**
   * Gets the default value for a given rule, in case the value needs to be reset.
   */
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  getRuleDefaultValue?: (rule: RuleType) => any;
}

Source: /packages/react-querybuilder/src/utils/queryTools.ts#L80-L104

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

export interface MoveOptions {
  /**
   * When `true`, the source rule/group will not be removed from its original path.
   */
  clone?: boolean;
  /**
   * If the query extends `RuleGroupTypeIC` (i.e. the query is using independent
   * combinators), then the first combinator in this list will be inserted before
   * the rule/group if necessary.
   */
  combinators?: OptionList;
  /**
   * ID generator.
   */
  idGenerator?: () => string;
}

Source: /packages/react-querybuilder/src/utils/queryTools.ts#L289-L304

insert​

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

Inserts a rule or group (and an independent combinator if necessary, to keep the query valid) at the specified path.

InsertOptions

export interface InsertOptions {
  /**
   * If the query extends `RuleGroupTypeIC` (i.e. the query has independent
   * combinators), then the first combinator in this list will be inserted
   * before the new rule/group if the parent group is not empty. This option
   * is overridden by `combinatorPreceding`.
   */
  combinators?: OptionList;
  /**
   * If the query extends `RuleGroupTypeIC` (i.e. the query has independent
   * combinators), then this combinator will be inserted before the new rule/group
   * if the parent group is not empty and the new rule/group is not the first in the
   * group (`path.at(-1) > 0`). This option will supersede `combinators`.
   */
  combinatorPreceding?: string;
  /**
   * If the query extends `RuleGroupTypeIC` (i.e. the query has independent
   * combinators), then this combinator will be inserted after the new rule/group
   * if the parent group is not empty and the new rule/group is the first in the
   * group (`path.at(-1) === 0`). This option will supersede `combinators`.
   */
  combinatorSucceeding?: string;
  /**
   * ID generator.
   *
   * @default generateID
   */
  idGenerator?: () => string;
  /**
   * When `true`, the new rule/group will replace the rule/group at `path`.
   */
  replace?: boolean;
}

Source: /packages/react-querybuilder/src/utils/queryTools.ts#L415-L447

Defaults​

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

The default components are also exported: