@react-querybuilder/expr

Augments react-querybuilder with arithmetic and function expression support, letting either side of a rule be a computed operand built from fields, literals, and functions—e.g. (price * quantity) > 100 or ABS(discount) >= 5.

To see this in action, check out the react-querybuilder demo with the "expressions" option enabled.

Full documentation

Installation

npm i react-querybuilder @react-querybuilder/expr
# OR yarn add / pnpm add / bun add

Usage

All React exports live in the /ui entry point (@react-querybuilder/expr/ui); the root entry is framework-agnostic, exporting only rule processors, the validator, the function-metadata and serializer helpers, and types (so it can run server-side).

Components

Wrap your QueryBuilder in the QueryBuilderExpressions context provider. It overrides the field selector, value-source selector, and value editor to host expressions. Rules without expressions render exactly as before.

import { QueryBuilder } from 'react-querybuilder';
import { QueryBuilderExpressions } from '@react-querybuilder/expr/ui';

const App = () => (
  <QueryBuilderExpressions allowFunctionsOnLHS>
    <QueryBuilder fields={fields} query={query} onQueryChange={setQuery} />
  </QueryBuilderExpressions>
);

• Right-hand side — add "expression" to a field's valueSources to offer it in that rule's value-source selector. The expression is stored in rule.value (with valueSource: "expression").
• Left-hand side — set allowFunctionsOnLHS to wrap the rule's field in a unary function, stored on rule.lhs.

Pass custom function metadata (UI label + arity) via the functions prop; it is merged over the built-in defaultFunctionMeta (arithmetic + - * /, plus min, max, mod, abs, upper, and lower). Serialization for each export format is registered separately on the export processors.

Export

formatQuery needs an expression-aware rule processor to serialize the lhs/rhs nodes. The package provides a ready-to-use processor (and a getExpressionRuleProcessor* factory) for every export format that can represent computed operands:

import { formatQuery } from 'react-querybuilder';
import { expressionRuleProcessorSQL } from '@react-querybuilder/expr';

formatQuery(query, { format: 'sql', ruleProcessor: expressionRuleProcessorSQL });

Supported formats

formatQuery format	Ready-to-use processor	Factory	Extra context required
sql	expressionRuleProcessorSQL	getExpressionRuleProcessorSQL	—
parameterized/_named	expressionRuleProcessorParameterized	getExpressionRuleProcessorParameterized	—
jsonlogic	expressionRuleProcessorJsonLogic	getExpressionRuleProcessorJsonLogic	— (register operators before applying, see below)
cel	expressionRuleProcessorCEL	getExpressionRuleProcessorCEL	—
spel	expressionRuleProcessorSpEL	getExpressionRuleProcessorSpEL	—
cypher/gql	expressionRuleProcessorCypher	getExpressionRuleProcessorCypher	—
sparql	expressionRuleProcessorSPARQL	getExpressionRuleProcessorSPARQL	—
jsonata	expressionRuleProcessorJSONata	getExpressionRuleProcessorJSONata	—
mongodb_query	expressionRuleProcessorMongoDBQuery	getExpressionRuleProcessorMongoDBQuery	—
mongodb (deprecated)	expressionRuleProcessorMongoDB	getExpressionRuleProcessorMongoDB	—
elasticsearch	expressionRuleProcessorElasticSearch	getExpressionRuleProcessorElasticSearch	—
natural_language	expressionRuleProcessorNL	getExpressionRuleProcessorNL	—
drizzle	expressionRuleProcessorDrizzle	getExpressionRuleProcessorDrizzle	columns, drizzleOperators
sequelize	expressionRuleProcessorSequelize	getExpressionRuleProcessorSequelize	sequelizeOperators, sequelizeWhere, sequelizeLiteral, sequelizeCol
tanstack_db	expressionRuleProcessorTanStackDB	getExpressionRuleProcessorTanStackDB	tanStackDbOperators, _tanstackDbRefs, _tanstackDbPrimaryRef

Expression rules support scalar comparisons (=, !=, <, <=, >, >=), null/notNull, and between/notBetween (with expression bounds). Rules without expressions, with an unsupported operator, or missing required context, fall back to the stock processor for that format.

Note: string-match operators (contains, beginsWith, endsWith, and their negations) support expression operands—an expression RHS (search term) and/or LHS—for every export format except tanstack_db, each using that dialect's native construct. The tanstack_db format omits such rules (its like needs a static pattern), and sequelize omits a string-match rule whose search term is a bare field reference (valueSource: 'field').

The library-backed formats need the same context helpers their stock processors need. For example, drizzle:

import { getOperators } from 'drizzle-orm';
import { expressionRuleProcessorDrizzle } from '@react-querybuilder/expr';

const where = formatQuery(query, {
  format: 'drizzle',
  preset: 'sqlite', // resolves min/max to MIN/MAX (else LEAST/GREATEST)
  ruleProcessor: expressionRuleProcessorDrizzle,
  context: { columns, drizzleOperators: getOperators() },
});

and sequelize:

import { col, literal, Op, where } from 'sequelize';
import { expressionRuleProcessorSequelize } from '@react-querybuilder/expr';

const whereClause = formatQuery(query, {
  format: 'sequelize',
  preset: 'sqlite',
  ruleProcessor: expressionRuleProcessorSequelize,
  context: {
    sequelizeOperators: Op,
    sequelizeWhere: where,
    sequelizeLiteral: literal,
    sequelizeCol: col,
  },
});

Custom functions

When using custom functions, pass matching serializers to each format's processor factory (a function present in the UI but missing a serializer for the export format is omitted from that format's output):

import { getExpressionRuleProcessorSQL } from '@react-querybuilder/expr';

const sqlProcessor = getExpressionRuleProcessorSQL({
  pow: (_opts, base, exp) => `POWER(${base}, ${exp})`,
});

formatQuery(query, { format: 'sql', ruleProcessor: sqlProcessor });

Each getExpressionRuleProcessor* factory takes a single serializer registry merged over that format's built-ins.

Applying JsonLogic output

Before applying the jsonlogic output, register the operators the expressions emit. JsonLogic ships + - * / %, min, and max as built-ins, but others like abs, upper, and lower are not. Add them to your JsonLogic instance like so:

import { add_operation, apply } from 'json-logic-js';
import { jsonLogicExpressionOperators } from '@react-querybuilder/expr';

for (const [op, func] of Object.entries(jsonLogicExpressionOperators)) {
  add_operation(op, func);
}

const logic = formatQuery(query, {
  format: 'jsonlogic',
  ruleProcessor: expressionRuleProcessorJsonLogic,
});
apply(logic, data);

Validation

createExpressionValidator returns a QueryValidator that flags rules with invalid expressions (unknown function, arity mismatch, empty field reference). Use it as formatQuery's validator option or as a <QueryBuilder validator> prop:

import { createExpressionValidator } from '@react-querybuilder/expr';

const validator = createExpressionValidator(functions);