@solidexpert/ngx-query-builder

@solidexpert/ngx-query-builder

A modern Angular (v15+) query builder inspired by jQuery QueryBuilder and rebuilt with standalone components. It ships sensible defaults, rich templating hooks, and full forms support so you can compose visual query editors that match your domain.

Features

• Standalone QueryBuilderComponent that works with ngModel or Reactive Forms (ControlValueAccessor + Validator)
• Entity-aware field grouping and configurable rule defaults out of the box
• Template overrides for every UI fragment (queryInput, queryButtonGroup, querySwitchGroup, etc.)
• Expand/collapse support for nested rule sets with fully customizable icons and transitions
• Built-in operator coercion (incl. multi-select) and hooks for custom operator resolution/value handling
• Provides accessible, BEM-ish CSS class names that can be themed directly or swapped via classNames

Compatibility

Angular version	Library tag	Notes
20.x	@solidexpert/ngx-query-builder@^20	Default release line (current)
19.x	@solidexpert/ngx-query-builder@^19	Install explicitly when targeting Angular 19
18.x	@solidexpert/ngx-query-builder@^18	Legacy support branch
15.x – 17.x	@solidexpert/ngx-query-builder@^15	Final Ivy-era compatible build

ℹ️ Each major version aligns with the matching Angular major. Pin the library to the major that matches your workspace in package.json.

Installation

npm install @solidexpert/ngx-query-builder

Quick Start

Standalone component example

import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
  QueryBuilderComponent,
  QueryBuilderConfig,
  RuleSet
} from '@solidexpert/ngx-query-builder';

@Component({
  selector: 'app-query-builder-demo',
  standalone: true,
  imports: [FormsModule, QueryBuilderComponent],
  template: `
    <query-builder
      [(ngModel)]="query"
      [config]="config"
      [allowCollapse]="true"
      [persistValueOnFieldChange]="true"
    ></query-builder>
  `
})
export class QueryBuilderDemoComponent {
  query: RuleSet = {
    condition: 'and',
    rules: [{ field: 'age', operator: '>=', value: 21 }]
  };

  config: QueryBuilderConfig = {
    fields: {
      age: { name: 'Age', type: 'number', defaultOperator: '>=', defaultValue: 18 },
      gender: {
        name: 'Gender',
        type: 'category',
        options: [
          { name: 'Male', value: 'm' },
          { name: 'Female', value: 'f' }
        ]
      }
    },
    allowEmptyRulesets: false
  };
}

Using with an NgModule

Because the component is standalone, add it to the imports array of any traditional NgModule:

import { NgModule } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { QueryBuilderComponent } from '@solidexpert/ngx-query-builder';
import { DemoHostComponent } from './demo-host.component';

@NgModule({
  declarations: [DemoHostComponent],
  imports: [FormsModule, QueryBuilderComponent]
})
export class DemoModule {}

Data model essentials

• RuleSet: { condition: 'and' | 'or', rules: Array<Rule | RuleSet>, collapsed?: boolean }
• Rule: { field: string; operator?: string; value?: any; entity?: string }

Either bind via [(ngModel)] or plug the component into a reactive form control using formControlName.

Configuration reference

QueryBuilderConfig

Property	Type	Description
fields	{ [key: string]: Field }	Required field registry. Keys map to Rule.field values.
entities	{ [key: string]: Entity }	Optional entity registry to scope visible fields per rule.
allowEmptyRulesets	boolean	Allow rule sets to be empty. When false, empty sets are flagged as invalid.
getOperators(fieldName, field)	(string, Field) => string[]	Override operator list resolution. Falls back to operators on the field definition or the component’s default map.
getInputType(fieldName, operator)	(string, string) => string	Map a field/operator to a custom template type.
getOptions(fieldName)	(string) => Option[]	Provide runtime option lists (async ready if paired with async pipe).
addRuleSet(parent) / addRule(parent)	(RuleSet) => void	Override default rule creation logic. Useful when pairing with server-driven defaults.
removeRuleSet(ruleset, parent?) / removeRule(rule, parent)	Custom removal handlers.
coerceValueForOperator(operator, value, rule)	(string, any, Rule) => any	Override built-in coercion logic (e.g. normalise between string/number types).
calculateFieldChangeValue(currentField, nextField, value)	(Field, Field, any) => any	Decide how to migrate a rule’s value when the field changes.

QueryBuilderClassNames

Every visual element exposes a class token that can be replaced. The defaults ship with the q-* prefix. Override selectively through the [classNames] input, e.g.:

classNames = {
  button: 'btn btn-sm btn-secondary',
  addIcon: 'fa fa-plus',
  removeIcon: 'fa fa-minus text-danger'
};

Component inputs

Input	Type	Default	Description
disabled	boolean	false	Disables user interaction and propagates ControlValueAccessor state.
allowRuleset	boolean	true	Shows the “+ Ruleset” button when true.
allowCollapse	boolean	false	Enables collapse/expand controls on the outer ruleset.
emptyMessage	string	"A ruleset cannot be empty..."	Message rendered when an empty ruleset is invalid.
classNames	QueryBuilderClassNames	{}	Override CSS class tokens.
config	QueryBuilderConfig	{ fields: {} }	Core configuration object for fields, entities, and hooks.
operatorMap	{ [type: string]: string[] }	See source defaults	Extend or replace the built-in operator map used when a field has no explicit operators.
persistValueOnFieldChange	boolean	false	When toggled, keeps a rule’s value if the new field shares the same type (string/number/time/date/boolean). Ignored if calculateFieldChangeValue is supplied.
parent* inputs	—	—	Internal plumbing used when rendering nested instances. They can generally be ignored by consumers.

[(ngModel)], formControl, and [value]/(valueChange) bindings all use the same RuleSet shape; prefer ngModel / formControl for automatic change detection and validation.

Structural directives

All template overrides are standalone directives exported alongside the component. Use *directive="..." syntax to redefine specific UI fragments.

Directive	Purpose	Context (let- variables)
queryInput	Replace the value editor.	let rule, let field=field, let options=options, let onChange=onChange
queryOperator	Replace the operator selector.	let rule, let operators=operators, let onChange=onChange
queryField	Replace the field selector.	let rule, let fields=fields, let onChange=onChange, let getFields=getFields
queryEntity	Replace the entity selector.	let rule, let entities=entities, let onChange=onChange
querySwitchGroup	Redefine the AND/OR toggle block.	let ruleset, let onChange=onChange, let getDisabledState=getDisabledState
queryButtonGroup	Customise the add/remove buttons.	let ruleset, let addRule=addRule, let addRuleSet=addRuleSet, let removeRuleSet=removeRuleSet, let getDisabledState=getDisabledState
queryRemoveButton	Override the per-rule remove button.	let rule, let removeRule=removeRule, let getDisabledState=getDisabledState
queryEmptyWarning	Custom empty warning content.	let ruleset, let message=message, let getDisabledState=getDisabledState
queryArrowIcon	Swap the collapse caret icon.	let ruleset, let getDisabledState=getDisabledState

Specify a type when using queryInput to target specific field types: *queryInput="let rule; type: 'date'".

UI customisation examples

Bootstrap-flavoured buttons

<query-builder [(ngModel)]="query" [config]="config" [classNames]="bootstrapClassNames">
  <ng-container *queryButtonGroup="let addRule=addRule; let addRuleSet=addRuleSet">
    <div class="btn-group">
      <button class="btn btn-outline-primary btn-sm" type="button" (click)="addRule()">+ Rule</button>
      <button class="btn btn-outline-primary btn-sm" type="button" (click)="addRuleSet()">+ Group</button>
    </div>
  </ng-container>
</query-builder>

bootstrapClassNames = {
  button: 'btn btn-outline-secondary btn-sm',
  addIcon: 'fa fa-plus me-1',
  removeIcon: 'fa fa-times text-danger',
  rule: 'card card-body p-3 mb-2'
};

Angular Material inputs

<query-builder [(ngModel)]="query" [config]="config">
  <ng-container *queryField="let rule; let fields=fields; let onChange=onChange">
    <mat-form-field appearance="outline">
      <mat-label>Field</mat-label>
      <mat-select [(ngModel)]="rule.field" (ngModelChange)="onChange($event, rule)">
        <mat-option *ngFor="let field of fields" [value]="field.value">{{ field.name }}</mat-option>
      </mat-select>
    </mat-form-field>
  </ng-container>
  <ng-container *queryOperator="let rule; let operators=operators">
    <mat-form-field appearance="outline">
      <mat-label>Operator</mat-label>
      <mat-select [(ngModel)]="rule.operator">
        <mat-option *ngFor="let operator of operators" [value]="operator">{{ operator }}</mat-option>
      </mat-select>
    </mat-form-field>
  </ng-container>
  <ng-container *queryInput="let rule; let options=options; type: 'category'">
    <mat-form-field appearance="outline">
      <mat-label>Value</mat-label>
      <mat-select [(ngModel)]="rule.value" multiple>
        <mat-option *ngFor="let opt of options" [value]="opt.value">{{ opt.name }}</mat-option>
      </mat-select>
    </mat-form-field>
  </ng-container>
</query-builder>

Advanced scenarios

• Entity-aware field lists: supply config.entities and set entity on fields. The default UI shows an entity dropdown when at least one entity is configured.
• Persisting values on field change: enable [persistValueOnFieldChange]="true" or implement calculateFieldChangeValue to migrate values between fields with custom logic.
• Dynamic operator sets: use getOperators or augment [operatorMap] to align operators with your backend semantics.
• Custom validation: attach validator functions on individual fields. Returning a string (or any truthy value) marks the rule invalid and surfaces through Angular’s form validation.
• Programmatic rule management: override addRule, addRuleSet, removeRule, or removeRuleSet in the config to bridge to remote defaults or analytics.

Working with forms

The component implements both ControlValueAccessor and Validator. When registered inside a reactive form, any validation errors produced by field validators flow into FormControl.errors.rules. Use native Angular form APIs (statusChanges, ngModelChange, etc.) to react to updates.

this.form = new FormGroup({
  filter: new FormControl<RuleSet | null>(null, Validators.required)
});

<form [formGroup]="form">
  <query-builder formControlName="filter" [config]="config"></query-builder>
  <pre *ngIf="form.controls.filter.errors as errors">{{ errors | json }}</pre>
</form>

Testing

Run the unit suite to ensure regressions are caught before publishing:

npm install
npm run test   # or: ng test

The specs cover default rule creation, field change behaviour, multi-select coercion, and validator integration.

License

MIT © Solidexpert