ngx-query-builder

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.

Forked from (https://github.com/zebzhao/Angular-QueryBuilder) as the original project has stopped updating and does not support the latest Angular versions, so I will continue to maintain it and support the latest versions of Angular.

Getting Started

Install

• Angular latest, use 0.6.3+

npm install @kerwin612/ngx-query-builder

• 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

See https://github.com/zebzhao/Angular-QueryBuilder for more details on the usage of the old version.

Examples

Basic Usage

app.module.ts

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

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

app.component.html

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

app.component.ts

import { QueryBuilderConfig } from 'ngx-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

<ngx-query-builder [(ngModel)]='query' [config]='config'>
  <ng-container *queryInput="let rule; type: 'date'">
    <custom-datepicker [(ngModel)]="rule.value"></custom-datepicker>
  </ng-container>
</ngx-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())
    },
  }
}

Property Bindings Quick Reference

ngx-query-builder

|Name| Type |Required| Default |Description| |:--- |:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--- |:---------------------------------|:--- | |allowRuleset| boolean |Optional| true | Displays the + Ruleset button if true. | |allowCollapse| boolean |Optional| false | Enables collapsible rule sets if true. | |classNames| QueryBuilderClassNames |Optional| | CSS class names for different child elements in query-builder component. | |config| QueryBuilderConfig |Required| | Configuration object for the main component. | |data| Ruleset |Optional| { condition: 'and', rules: [] } | (Use ngModel or value instead.) | |emptyMessage| string |Optional| | Message to display for an empty Ruleset if empty rulesets are not allowed. | |ngModel| Ruleset |Optional| { condition: 'and', rules: [] } | Object that stores the state of the component. Supports 2-way binding. | |operatorMap| { [key: string]: string[] } |Optional| | Used to map field types to list of operators. | |persistValueOnFieldChange| boolean |Optional| false | If true, when a field changes to another of the same type, and the type is one of: string, number, time, date, or boolean, persist the previous value. This option is ignored if config.calculateFieldChangeValue is provided. | |config.calculateFieldChangeValue| (currentField: Field, nextField: Field, currentValue: any) => any |Optional| | Used to calculate the new value when a rule's field changes. | |value| Ruleset |Optional| { condition: 'and', rules: [] } | Object that stores the state of the component. |

Structural Directives

Use these directives to replace different parts of query builder with custom components.

queryArrowIcon

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

|Context Name|Type| Description | |:--- |:--- |:------------------------------------------------------------| |$implicit|RuleSet| Current rule set object which contain a list of child rules | |getDisabledState|() => boolean| Retrieves or determines the disabled state of the 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.

|Context Name|Type| Description | |:--- |:--- |:-----------------------------------------------------------| |$implicit|RuleSet| Current rule set object which contain a list of child rules| |onChange|() => void| Callback to handle changes to the switch group component | |getDisabledState|() => boolean| Retrieves or determines the disabled state of the component|

queryButtonGroup

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

|Context Name|Type| Description | |:--- |:--- |:------------------------------------------------------------| |$implicit|RuleSet| Current rule set object which contain a list of child rules | |parentValue|RuleSet| For parent node's data if exists | |addRule|() => void| Function to handle adding a new rule | |addRuleSet|() => void| Function to handle adding a new rule set | |removeRuleSet|() => void| Function to handle removing the current rule set | |getDisabledState|() => boolean| Retrieves or determines the disabled state of the component |

queryRulesetAddRuleButton

For replacing the default button for Add Rule.

|Context Name|Type| Description | |:--- |:--- |:-----------------------------------------------------------| |$implicit|RuleSet| Current rule set object which contain a list of child rules| |addRule|() => void| Function to handle adding a new rule | |getDisabledState|() => boolean| Retrieves or determines the disabled state of the component|

queryRulesetAddRulesetButton

For replacing the default button for Add Ruleset.

|Context Name|Type| Description | |:--- |:--- |:-----------------------------------------------------------| |$implicit|RuleSet| Current rule set object which contain a list of child rules| |addRuleSet|() => void| Function to handle adding a new rule set | |getDisabledState|() => boolean| Retrieves or determines the disabled state of the component|

queryRulesetRemoveButton

For replacing the default button for Remove Ruleset.

|Context Name|Type| Description | |:--- |:--- |:-----------------------------------------------------------| |$implicit|RuleSet| Current rule set object which contain a list of child rules| |removeRuleSet|() => void| Function to handle removing the current rule set | |getDisabledState|() => boolean| Retrieves or determines the disabled state of the component|

queryEntity

Used to replace entity selection component.

|Context Name|Type| Description | |:--- |:--- |:----------------------------------------------------------------| |$implicit|Rule| Current rule object which contains the field, value, and operator| |entities|Entity[]| List of entities for the component, specified by config | |onChange|(entityValue: string, rule: Rule) => void| Callback to handle changes to the entity component | |getDisabledState|() => boolean| Retrieves or determines the disabled state of the component |

queryField

Used this directive to replace the query field selection component.

|Context Name|Type| Description | |:--- |:--- |:----------------------------------------------------------------| |$implicit|Rule| Current rule object which contains the field, value, and operator| |getFields|(entityName: string) => void| Get the list of fields corresponding to an entity | |fields|Field[]| List of fields for the component, specified by config | |onChange|(fieldValue: string, rule: Rule) => void| Callback to handle changes to the field component | |getDisabledState|() => boolean| Retrieves or determines the disabled state of the component |

queryOperator

Used to replace the query operator selection component.

|Context Name|Type| Description | |:--- |:--- |:-------------------------------------------------------------------------------------------------------------| |$implicit|Rule| Current rule object which contains the field, value, and operator | |operators|string[]| List of operators for the field, returned by getOperators | |onChange|() => void| Callback to handle changes to the operator component | |getDisabledState|() => boolean| Retrieves or determines the disabled state of the component |

queryInput

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

|Context Name|Type| Description | |:--- |:--- |:----------------------------------------------------------------| |$implicit|Rule| Current rule object which contains the field, value, and operator| |field|Field| Current field object which contains the field's value and name | |options|Option[]| List of options for the field, returned by getOptions | |onChange|() => void| Callback to handle changes to the input component | |getDisabledState|() => boolean| Retrieves or determines the disabled state of the component |

queryRuleRemoveButton

Directive to replace the default remove single rule button component.

|Context Name|Type| Description | |:--- |:--- |:----------------------------------------------------------------| |$implicit|Rule| Current rule object which contains the field, value, and operator| |removeRule|(rule: Rule) => void| Function to handle removing a rule | |getDisabledState|() => boolean| Retrieves or determines the disabled state of the component |

queryEmptyWarning

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

|Context Name|Type| Description | |:--- |:--- |:-----------------------------------------------------------| |$implicit|RuleSet| Current rule set object which contain a list of child rules| |message|string| Value passed to emptyMessage | |getDisabledState|() => boolean| Retrieves or determines the disabled state of the component|

Dependencies

• Angular 18+

Development

dev

• pnpm watch
• pnpm start
• vist http://localhost:4200 to see the demo

demo preview

build

• pnpm build

publish

cd dist/ngx-query-builder
npm publish --access public

For use in other local projects

cd dist/ngx-query-builder
npm link

cd /path/to/other/project
npm link ngx-query-builder

That's it.