Angular-QueryBuilder

A modernized Angular 4+ query builder based on jQuery QueryBuilder. Support for heavy customization with Angular components and provides a flexible way to handle custom data types.

Getting Started

Install

• Angular 9, use 0.6.0
• Angular 8, use 0.5.1
• Angular 6-7, use 0.4.2
• Angular 4-5, use 0.3.2

npm install angular2-query-builder

Demo

Play with the Demo here.

Editable Demo

Documentation

Documentation link

Examples

Basic Usage

app.module.ts

import { QueryBuilderModule } from "angular2-query-builder";
import { AppComponent } from "./app.component"

@NgModule(imports: [
  ...,
  QueryBuilderModule,
  IonicModule.forRoot(AppComponent) // (Optional) for IonicFramework 2+
])
export class AppModule { }

app.component.html

...
<query-builder [(ngModel)]='query' [config]='config'></query-builder>
...

app.component.ts

import { QueryBuilderConfig } from 'angular2-query-builder';

export class AppComponent {
  query = {
    condition: 'and',
    rules: [
      {field: 'age', operator: '<=', value: 'Bob'},
      {field: 'gender', operator: '>=', value: 'm'}
    ]
  };

  config: QueryBuilderConfig = {
    fields: {
      age: {name: 'Age', type: 'number'},
      gender: {
        name: 'Gender',
        type: 'category',
        options: [
          {name: 'Male', value: 'm'},
          {name: 'Female', value: 'f'}
        ]
      }
    }
  }
}

Custom Input Components

app.component.html

<query-builder [(ngModel)]='query' [config]='config'>
  <ng-container *queryInput="let rule; type: 'date'">
    <custom-datepicker [(ngModel)]="rule.value"></custom-datepicker>
  </ng-container>
</query-builder>

app.component.ts

query = {
  condition: 'and',
  rules: [
    {field: 'birthday', operator: '=', value: new Date()}
  ]
};

config: QueryBuilderConfig = {
  fields: {
    birthday: {name: 'Birthday', type: 'date', operators: ['=', '<=', '>']
      defaultValue: (() => return new Date())
    },
  }
}

Custom Styling (with Bootstrap 4)

Bootstrap demo.

app.component.html

<query-builder [(ngModel)]='query' [config]='config' [classNames]='classNames'></query-builder>

app.component.ts

classNames: QueryBuilderClassNames = {
  removeIcon: 'fa fa-minus',
  addIcon: 'fa fa-plus',
  arrowIcon: 'fa fa-chevron-right px-2',
  button: 'btn',
  buttonGroup: 'btn-group',
  rightAlign: 'order-12 ml-auto',
  switchRow: 'd-flex px-2',
  switchGroup: 'd-flex align-items-center',
  switchRadio: 'custom-control-input',
  switchLabel: 'custom-control-label',
  switchControl: 'custom-control custom-radio custom-control-inline',
  row: 'row p-2 m-1',
  rule: 'border',
  ruleSet: 'border',
  invalidRuleSet: 'alert alert-danger',
  emptyWarning: 'text-danger mx-auto',
  operatorControl: 'form-control',
  operatorControlSize: 'col-auto pr-0',
  fieldControl: 'form-control',
  fieldControlSize: 'col-auto pr-0',
  entityControl: 'form-control',
  entityControlSize: 'col-auto pr-0',
  inputControl: 'form-control',
  inputControlSize: 'col-auto'
}

Customizing with Angular Material

Example of how you can completely customize the query component with another library like Angular Material. For the full example, please look at the source code provided in the demo.

app.component.html

<query-builder [(ngModel)]='query' [config]='config'>
  <ng-container *queryButtonGroup="let ruleset; let addRule=addRule; let addRuleSet=addRuleSet; let removeRuleSet=removeRuleSet">
    <button type="button" mat-button (click)="addRule()">+ Rule</button>
    <button type="button" mat-button (click)="addRuleSet()">+ Ruleset</button>
    <button type="button" mat-button (click)="removeRuleSet()">- Ruleset</button>
  </ng-container>
  <ng-container *queryRemoveButton="let rule; let removeRule=removeRule">
    <button type="button" mat-icon-button color="accent" (click)="removeRule(rule)">
      <mat-icon>remove</mat-icon>
    </button>
  </ng-container>
  <ng-container *querySwitchGroup="let ruleset">
    <mat-radio-group *ngIf="ruleset" [(ngModel)]="ruleset.condition">
      <mat-radio-button value="and">And</mat-radio-button>
      <mat-radio-button value="or">Or</mat-radio-button>
    </mat-radio-group>
  </ng-container>
  <ng-container *queryField="let rule; let fields=fields; let onChange=onChange">
    <mat-form-field>
      <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>
      <mat-select [(ngModel)]="rule.operator">
        <mat-option *ngFor="let value of operators" [value]="value">{{value}}</mat-option>
      </mat-select>
    </mat-form-field>
  </ng-container>
  <!-- Override input component for 'boolean' type -->
  <ng-container *queryInput="let rule; type: 'boolean'">
    <mat-checkbox [(ngModel)]="rule.value"></mat-checkbox>
  </ng-container>
  <!-- Override input component for 'category' type -->
  <ng-container *queryInput="let rule; let field=field; let options=options; type: 'category'">
    <mat-form-field>
      <mat-select [(ngModel)]="rule.value" [placeholder]="field.name">
        <mat-option *ngFor="let opt of options" [value]="opt.value">
          {{ opt.name }}
        </mat-option>
      </mat-select>
    </mat-form-field>
  </ng-container>
  ...
</query-builder>

Property Bindings Quick Reference

See documentation for more details on interfaces and properties.

query-builder

Structural Directives

Use these directives to replace different parts of query builder with custom components. See example, or demo to see how it's done.

queryInput

Used to replace the input component. Specify the type/queryInputType to match specific field types to input template.

queryOperator

Used to replace the query operator selection component.

queryField

Used this directive to replace the query field selection component.

queryEntity

Used to replace entity selection component.

querySwitchGroup

Useful for replacing the switch controls, for example the AND/OR conditions. More custom conditions can be specified by using this directive to override the default component.

queryArrowIcon

Directive to replace the expand arrow used in collapse/accordion mode of the query builder.

queryEmptyWarning

Can be used to customize the default empty warning message, alternatively can specify the emptyMessage property binding.

queryButtonGroup

For replacing the default button group for Add, Add Ruleset, Remove Ruleset buttons.

queryRemoveButton

Directive to replace the default remove single rule button component.

Dependencies

• Angular 8+

That's it.

Workflow

See the angular-library-seed project for details on how to build and run tests.

Angular2-QueryBuilder Changelog

Version 0.5.0

• Upgrade to Angular 8
• Add option to persist value on rule change (see documentation for details)

Version 0.4.0

• Fix issue switching operators changing select to multiple and causing invalid value error. (#69)
• Add a coerceValueForOperator to handle value changes between operator switches to config object.
• Add treeContainer, collapsed, arrowIcon, arrowIconButton fields to classNames object.
• Add queryArrowIcon structural directive to override collapse arrow icon.
• Added allowCollapse to enable accordion/collapse mode. (#66)

Version 0.3.3

• Fix queryEmptyWarning directive not being passed to nested rules

Version 0.3.2

• Add queryEmptyWarning directive for customizing empty warning messages
• Add [emptyMessage] to change the default empty message text

Version 0.3.1

• Change: add Rule will use defaultValue of Field as the default
• Updated Angular Materials to 6.0 in demos
• Fix touched state not being updated when changing the query condition (AND/OR)
• Add [disabled] feature #61
• Tweaks to Vanilla CSS styling

Version 0.3.0

• Breaking: Renamed changeField callback to onChange for queryField directive.
• Add onChange callback to queryEntity, queryInput, queryOperator, queryInput for proper reactive form validation and touched behavior on custom components
• Add proper touched behavior to reactive form usage (See #49)
• Add entity mode (See #22)
• Fix [value] unrecognized property binding
• Fix QueryBuilderClassNames not being exported as interface
• Fix in operator causing multi-select to be displayed for all types (only limited to category, boolean now)
• Minor tweaks to CSS styling of default component

Version 0.2.5

• Fix root remove ruleset button showing
• Fix default value bug where only the first character of the operator is shown
• Fix inability to override multiselect operators (is in, is not in)

Version 0.2.4

• Fix serious issue with validation causing ngModel value to be wrong
• New QueryBuilderClassNames interface
• Rewrite CSS for more extensible CSS classes
• New bootstrap 4 example

Version 0.2.3

• Fix IE11 not working (target ES5)
• Fix invalid/valid state
• New validator function on Field config