QueryBuilder

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-query-builder

pnpm add @react-querybuilder/core jsonata @shopify/flash-list react-native-reanimated @react-native-community/datetimepicker tailwind-variants

QueryBuilderDocyrus is the native counterpart of the web QueryBuilderDocyrus. It is built on the pure-TS @react-querybuilder/core (query tools + mutation policy — no DOM, no redux) and produces exactly the same RuleGroupType JSON as the web builder: Docyrus backend operator ids (=, like, between, is one of, last_7_days, json_key_is, active_user, …), the same value shapes, valueSource: 'value' on rules and not on groups. A query authored on a phone can be sent to /items filters or saved into a data view unchanged, and vice versa.

Mobile idioms replace the web popovers: every rule is a card, field → operator → value are picked in bottom sheets (searchable, sectioned, paged), nested groups are indented, tinted per depth and collapsible, and long-press offers Move up / Move down when draggable is on.

Usage

import { useState } from 'react';

import {
  QueryBuilderDocyrus,
  type DocyrusQBField,
  type RuleGroupType
} from '@/components/docyrus-native/query-builder';

const fields: DocyrusQBField[] = [
  { name: 'name', label: 'Name', fieldType: 'field-text' },
  { name: 'amount', label: 'Amount', fieldType: 'field-money' },
  { name: 'close_date', label: 'Close date', fieldType: 'field-date' },
  {
    name: 'status',
    label: 'Status',
    fieldType: 'field-status',
    values: [
      { name: 'uuid-open', label: 'Open', color: '#3b82f6' },
      { name: 'uuid-won', label: 'Won', color: '#22c55e' }
    ]
  },
  { name: 'is_active', label: 'Active', fieldType: 'field-switch' }
];

export function DealFilter() {
  const [query, setQuery] = useState<RuleGroupType>({ combinator: 'and', rules: [] });

  return (
    <QueryBuilderDocyrus
      fields={fields}
      query={query}
      onQueryChange={setQuery}
      showNotToggle
      showCloneButtons
      maxDepth={3}
      emptyMessage="No conditions yet. Add one to combine fields with AND / OR." />
  );
}

An id-less controlled query (like the empty one above) is prepared once per prop identity, so pass back the object you receive from onQueryChange and rule ids stay stable.

Field → operator → editor mapping

Each field resolves to a Docyrus FilterGroup — from filterGroup, or from fieldType through FIELD_TYPE_TO_FILTER_GROUP (unknown types fall back to ALPHA). With enrichFieldDefaults (default), the group supplies the operator list and the per-operator value editor:

operatorValues swaps the option list per operator and operatorValueEditorType overrides the editor per operator — identical to web.

Async option loading

A relation or user column's options live in another data source (or the tenant roster) and cannot ship in values. Declare asyncOptions on the field — the same QBAsyncOptions object the web builder takes:

const fields: DocyrusQBField[] = [
  {
    name: 'account',
    label: 'Account',
    fieldType: 'field-relation',
    asyncOptions: {
      load: async ({ search, page, pageSize, signal }) => {
        const res = await client.get('/v1/apps/base/account/items', {
          filterKeyword: search,
          limit: pageSize,
          offset: page * pageSize
        }, { signal });

        return { items: res.data.map(toOption), hasMore: res.data.length === pageSize };
      },
      resolveByIds: async ({ ids, signal }) => {
        const res = await client.get('/v1/apps/base/account/items', { filters: idFilter(ids) }, { signal });

        return res.data.map(toOption);
      }
    }
  }
];

The picker debounces the search (debounceMs, default 300), loads page 0 when the sheet opens and — unlike the web picker, which only loads the first page — pages on scroll through FlashList onEndReached while hasMore is true. resolveByIds is asked, once, for the ids the picker cannot name, so a rule reopened from storage shows labels instead of raw ids. A sticky label cache keeps every option already seen.

Depth limit

maxDepth follows react-querybuilder's maxLevels semantics, exactly as the web builder forwards it: a group at depth d (root = 0) shows Group while d < maxDepth, so maxDepth={1} allows one level of nested groups below the root. Unset, 0 or negative = unlimited (the default — the old native default of 3 is gone).

Converting a query to JSONata

useQuery2JsonataConverter / convertQueryToJsonata are the same pure-TS converter the web form-action engine uses, so a query can be evaluated on-device:

import { useQuery2JsonataConverter } from '@/components/docyrus-native/query-builder';

const { expression, evaluate, isValid } = useQuery2JsonataConverter({
  query,
  fields,
  context: { activeUserId: user.id }
});

const matches = await evaluate(record); // relative dates recomputed against "now" per call

API Reference

QBControlElements

QBClassnames

QBTranslations

Every key is optional and takes { label?: string; title?: string }: fields (+ placeholderLabel), operators (+ placeholderLabel), value, addRule, addGroup, removeRule, removeGroup, cloneRule, cloneRuleGroup, combinators, notToggle, shiftActionUp, shiftActionDown. Unset keys fall back to useUiTranslation() (ui.queryBuilder.*) and then English.

Components

Hooks & functions

Type Exports

Type Reference

DocyrusQBField

Extends react-querybuilder's Field (name, label, values, operators, valueEditorType, inputType, defaultOperator, defaultValue, …).

QBAsyncOptions

QBValueOption

Migrating from the pre-parity native QueryBuilder

The old hand-rolled QueryBuilder was not wire-compatible with Docyrus. It is replaced, not aliased: