All docs
V19.2
24.1
The page you are viewing does not exist in version 24.1.
23.2
The page you are viewing does not exist in version 23.2.
23.1
The page you are viewing does not exist in version 23.1.
22.2
The page you are viewing does not exist in version 22.2.
22.1
The page you are viewing does not exist in version 22.1.
21.2
The page you are viewing does not exist in version 21.2.
21.1
The page you are viewing does not exist in version 21.1.
20.2
The page you are viewing does not exist in version 20.2.
20.1
The page you are viewing does not exist in version 20.1.
19.2
19.1
The page you are viewing does not exist in version 19.1.
18.2
The page you are viewing does not exist in version 18.2.
18.1
The page you are viewing does not exist in version 18.1.
17.2
The page you are viewing does not exist in version 17.2.
Vue
A newer version of this page is available. Switch to the current version.

jQuery FilterBuilder - fields

Configures fields.

Default Value: []

This option accepts an array of objects, each configuring a filter condition's appearance. Each condition consists of a data field, operation and value. A logical operation can combine conditions on the same level in a group.

DevExtreme HTML5 JavaScript Filter Builder Fields

See the Field section for details on fields you can specify in each object.

View Demo

calculateFilterExpression

Specifies the field's custom filtering rules.

Type:

Function

Function parameters:
filterValue: any

A user input value.

selectedFilterOperation:

String

The selected filter operation.

Return Value:

Filter Expression

A filter expression.

NOTE
When configuring the filter builder integrated in the DataGrid or TreeList, specify the calculateFilterExpression in the column with the same dataField instead.

This function must return a filter expression. The simplest filter expression has the following format:

[selector, selectedFilterOperation, filterValue]
  • selector
    A data source field to be filtered.
  • selectedFilterOperation
    A comparison operator. One of the following: "=", "<>", ">", ">=", "<", "<=", "between", "startswith", "endswith", "contains", "notcontains".

    NOTE
    For the "between" operator, the returned filter expression has a slightly different format: [[selector, ">=", startValue], "and", [selector, "<=", endValue]].
  • filterValue
    A user input value. Values the selector provides are compared to this value.

In the following code, the calculateFilterExpression function implements an exclusive between operation. This is done by overriding the default inclusive implementation.

jQuery
JavaScript
$(function() {
    $("#filterBuilderContainer").dxFilterBuilder({
        // ...
        fields: [{
            calculateFilterExpression: function (filterValue, selectedFilterOperation) {
                if (selectedFilterOperation === "between" && $.isArray(filterValue)) {
                    var filterExpression = [
                        [this.dataField, ">", filterValue[0]], 
                        "and", 
                        [this.dataField, "<", filterValue[1]]
                    ];
                    return filterExpression;
                }
                // Invokes the default filtering behavior
                return this.defaultCalculateFilterExpression.apply(this, arguments);
            },
            // ...
        }]
    });
});
Angular
TypeScript
HTML
import { DxFilterBuilderModule } from "devextreme-angular";
// ...
export class AppComponent {
    calculateFilterExpression (filterValue, selectedFilterOperation) {
        let field = this as any;
        if (selectedFilterOperation === "between" && Array.isArray(filterValue)) {
            var filterExpression = [
                [field.dataField, ">", filterValue[0]], 
                "and", 
                [field.dataField, "<", filterValue[1]]
            ];
            return filterExpression;
        }
        // Invokes the default filtering behavior
        return field.defaultCalculateFilterExpression.apply(field, arguments);
    }
}
@NgModule({
    imports: [
        // ...
        DxFilterBuilderModule
    ],
    // ...
})
<dx-filter-builder ... >
    <dxi-field [calculateFilterExpression]="calculateFilterExpression" ... ></dxi-field>
</dx-filter-builder>

In the previous code, the defaultCalculateFilterExpression function invokes the default behavior. You can omit the function call if you do not need it.

NOTE
The this keyword refers to the field's configuration.

caption

Specifies the data field's caption.

Type:

String

Default Value: undefined

If you do not specify this option, the FilterBuilder generates the caption based on the dataField option. For example, if dataField is "fullName", the caption is "Full Name".

customizeText

Customizes the input value's display text.

Type:

Function

Function parameters:
fieldInfo:

Object

The field's data.

Object structure:
Name Type Description
value

String

|

Number

|

Date

The unformatted value (as specified using the editor or in the lookup's data source).

valueText

String

The value with the format applied.

Return Value:

String

The input value's text.

NOTE
The this keyword refers to the field's configuration.

dataField

Specifies the name of a field to be filtered.

Type:

String

Default Value: undefined

dataType

Casts field values to a specific data type.

Type:

String

Default Value: 'string'
Accepted Values: 'string' | 'number' | 'date' | 'boolean' | 'object' | 'datetime'

Use the FilterBuilderFieldDataType enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: String, Number, Date, DateTime, Boolean, and Object.

editorComponent

An alias for the editorTemplate property specified in React. Accepts a custom component. Refer to Using a Custom Component for more information.

editorOptions

Configures the widget used to edit the field value.

Type:

Object

Depending on the dataType, the FilterBuilder offers a user different widgets for editing: TextBox, DateBox, Lookup, etc. In the editorOptions object, you can specify options for the widget.

Because editorOptions depend on the dataType, they cannot be typed and are not implemented as nested configuration components in Angular, Vue, and React. In these frameworks, specify editorOptions with an object. We recommend that you declare the object outside the configuration component in Vue and React to prevent possible issues caused by unnecessary re-rendering.

Angular
app.component.html
app.module.ts
<dx-filter-builder ... >
    <dxi-field ...
        [editorOptions]="{ format: 'currency', showClearButton: true }">
    </dxi-field>
</dx-filter-builder>
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxFilterBuilderModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxFilterBuilderModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxFilterBuilder ... >
        <DxField ...
            :editor-options="fieldEditorOptions"
        />
    </DxFilterBuilder>
</template>

<script>
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import DxFilterBuilder, {
    DxField
} from 'devextreme-vue/filter-builder';

export default {
    components: {
        DxFilterBuilder,
        DxField
    },
    data() {
        return {
            fieldEditorOptions: { format: 'currency', showClearButton: true }
        }
    }
}
</script>
React
App.js
import React from 'react';

import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import FilterBuilder, {
    Field
} from 'devextreme-react/filter-builder';

class App extends React.Component {
    fieldEditorOptions = { format: 'currency', showClearButton: true };

    render() {
        return (
            <FilterBuilder ... >
                <Field ...
                    editorOptions={this.fieldEditorOptions}
                />
            </FilterBuilder>
        );
    }
}
export default App;
NOTE

Do not specify the onValueChanged option in this object. If you need to add custom logic to the standard value change handler, override the handler in the onEditorPreparing function in the following manner.

jQuery
JavaScript
$(function() {
    $("#filterBuilderContainer").dxFilterBuilder({
        // ...
        onEditorPreparing: function(e) {
            if (e.dataField == "requiredDataField") {
                var standardHandler = e.editorOptions.onValueChanged;
                e.editorOptions.onValueChanged = function(e) { // Overriding the standard handler
                    // ...
                    // Custom commands go here
                    // ...
                    standardHandler(e); // Calling the standard handler to save the edited value
                }
            }
        }
    });
});
Angular
TypeScript
HTML
import { DxFilterBuilderModule } from "devextreme-angular";
// ...
export class AppComponent {
    onEditorPreparing (e) {
        if (e.dataField == "requiredDataField") {
            let standardHandler = e.editorOptions.onValueChanged;
            e.editorOptions.onValueChanged = function (e) { // Overriding the standard handler
                // ...
                // Custom commands go here
                // ...
                standardHandler(e); // Calling the standard handler to save the edited value
            }
        }
    }
}
@NgModule({
    imports: [
        // ...
        DxFilterBuilderModule
    ],
    // ...
})
<dx-filter-builder ... 
    (onEditorPreparing)="onEditorPreparing($event)">
</dx-filter-builder>

editorRender

An alias for the editorTemplate property specified in React. Accepts a rendering function. Refer to Using a Rendering Function for more information.

editorTemplate

Specifies the editor's custom template.

Type:

template

Template Data:
Name Type Description
field

FilterBuilder Field

The condition's configuration.

filterOperation

String

The condition's operation.

setValue

Function

A method you should call to change the field value after the editor's value is changed.

value

String

|

Number

|

Date

The condition's data field value.

See Also

falseText

Specifies the false value text. Applies only if dataType is "boolean".

Type:

String

Default Value: 'false'

filterOperations

Specifies a set of available filter operations.

Type:

Array<String>

Default Value: undefined
Accepted Values: '=' | '<>' | '<' | '<=' | '>' | '>=' | 'contains' | 'endswith' | 'isblank' | 'isnotblank' | 'notcontains' | 'startswith' | 'between'

The following table lists default operations by data type:

dataType filterOperations
"string" [ "contains", "notcontains", "startswith", "endswith", "=", "<>", "isblank", "isnotblank" ]
"numeric" [ "=", "<>", "<", ">", "<=", ">=", "between", "isblank", "isnotblank" ]
"date", "datetime" [ "=", "<>", "<", ">", "<=", ">=", "between", "isblank", "isnotblank" ]
"boolean" [ "=", "<>", "isblank", "isnotblank" ]
"object" [ "isblank", "isnotblank" ]

The "isblank" operation returns null values and empty strings; "isnotblank" returns other values.

NOTE
Lookup's default operations are [ "=", "<>", "isblank", "isnotblank" ] regardless of the data type.

Use the FilterBuilderFieldFilterOperations enum to specify this option when the widget is used as an ASP.NET MVC 5 Control or a DevExtreme-Based ASP.NET Core Control. This enum accepts the following values: Equal, NotEqual, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, Between, NotContains, Contains, StartsWith, EndsWith, IsBlank, and IsNotBlank.

format

Formats a value before it is displayed.

Type:

Format

Default Value: ''

This option also controls the user input in cells that use the DateBox widget for editing. For cells that use other widgets, you can specify the editorOptions.format option.

jQuery
JavaScript
$(function(){
    $("#filterBuilderContainer").dxFilterBuilder({
        fields: [{
            dataField: "SaleAmount",
            format: "currency",
            editorOptions: {
                format: "$ #,##0.##"
            }
        }, 
        // ...
        ]
    });
});
Angular
TypeScript
HTML
import { DxFilterBuilderModule } from "devextreme-angular";
// ...
export class AppComponent {
    fields = [{
        dataField: "SaleAmount",
        format: "currency",
        editorOptions: {
            format: "$ #,##0.##"
        }
    }, 
    // ...
    ];
}
@NgModule({
    imports: [
        // ...
        DxFilterBuilderModule
    ],
    // ...
})
<dx-filter-builder
    [fields]="fields">
</dx-filter-builder>
See Also

lookup

Configures the lookup field.

Type:

Object

Default Value: undefined

Use the lookup field to limit the available filter values.

See Also

name

Specifies the field's name. Use it to distinguish the field from other fields when they have identical dataField values.

Type:

String

Default Value: undefined

trueText

Specifies the true value text. Applies only if dataType is "boolean".

Type:

String

Default Value: 'true'