Path concepts

While the id property uniquely identifies rules and groups, it doesn't indicate their position within the query hierarchy. React Query Builder uses a "path" concept to locate and update query objects based on their structural position.

The path property is an integer array that uniquely identifies each rule and group's location within a query. The root query group has a path of [], while all nested rules and groups have paths reflecting their position within their ancestor groups' rules arrays.

Each object's path equals its parent group's path plus its index within the parent's rules array: path = [...parentPath, index].

This example query shows the path for each rule and group with explanatory comments:

// [] (the root group)
const query: RuleGroupType = {
  combinator: 'and',
  rules: [
    // [0] (the first, aka zeroth, element in the root rules array)
    { field: 'f1', operator: '=', value: 'v1' },
    // [1] (the second element in the root rules array is a sub-group)
    {
      combinator: 'or',
      rules: [
        // [1, 0] (the first element within the rules array
        //         of the group occupying the second position
        //         in the root rules array)
        { field: 'f2', operator: '=', value: 'v2' },
        // [1, 1] (the second element within the rules array
        //         of the group occupying the second position
        //         in the root rules array)
        { field: 'f3', operator: '=', value: 'v3' },
      ],
    },
  ],
};

The first rule has path [0] (index 0 in the root rules array). The sub-group has path [1] (index 1 in the root array). Child rules within that group have paths starting with 1 (their parent's path) followed by their own indices.

Finding a path

The findPath function locates specific rules or groups for examination or updates. Using the query above:

findPath([1, 0], query);

Returns:

{ "field": "f2", "operator": "=", "value": "v2" }

Example

While most scenarios don't require direct path interaction, it's useful when custom components need to access other query parts.

For example, if a custom value editor needs sibling rule values, you can retrieve the full query object using the useQueryBuilderQuery hook (which connects to React Query Builder's Redux store), then find sibling rules using getParentPath and findPath.

info

Before version 7, custom components only received props for their specific rule or group. Additional data (like the root query) required the context prop.

The context prop remains available, but query retrieval no longer requires it.

import {
  RuleGroupType,
  RuleType,
  ValueEditor,
  ValueEditorProps,
  findPath,
  getParentPath,
  useQueryBuilderQuery,
} from 'react-querybuilder';

export const CustomValueEditor = (props: ValueEditorProps) => {
  // Get the full query object
  const query = useQueryBuilderQuery();
  // Get the path of this rule's parent group
  const parentPath = getParentPath(props.path);
  // Find the parent group object in the query
  const parentGroup = findPath(parentPath, query) as RuleGroupType;
  const id = findPath(props.path, query)!.id;
  // Get a comma-separated list of all sibling rule values
  const siblingValues = (
    parentGroup.rules.filter(
      r =>
        // filter out groups
        !('rules' in r) &&
        // filter out self
        r.id !== id
    ) as RuleType[]
  )
    // map the `value` property
    .map(r => r.value)
    // join with comma
    .join(', ');

  return (
    <div style={{ display: 'flex', flexDirection: 'column' }}>
      <ValueEditor {...props} />
      <span>Others: {siblingValues}</span>
    </div>
  );
};

Open Sandbox