All docs
V19.1
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
18.2
18.1
17.2
A newer version of this page is available. Switch to the current version.

DevExtreme jQuery - Filtering and Searching

Filter Row

The filter row allows a user to filter data by individual columns' values. Usually, the filter row's cells are text boxes, but the cells of columns that hold date or Boolean values contain other filtering controls (calendars or select boxes).

DevExtreme HTML5 JavaScript jQuery Knockout Angular TreeList Filtering FilterRow

View Demo

To make the filter row visible, assign true to the filterRow.visible option. You can set a column's allowFiltering option to false if data should never be filtered by it.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        filterRow: { visible: true },
        columns: [{
            // ...
            allowFiltering: false
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxo-filter-row [visible]="true"></dxo-filter-row>
    <dxi-column [allowFiltering]="false" ... ></dxi-column>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

A user-specified filter is automatically applied with a delay by default. Alternatively, it can be applied by a click on the "Apply Filter" button if you set the filterRow.applyFilter option to "onClick".

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        filterRow: {
            visible: true,
            applyFilter: "onClick"
        }
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxo-filter-row
        [visible]="true"
        applyFilter="onClick">
    </dxo-filter-row>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

Each cell in the filter row contains a magnifying glass icon. Hovering the mouse pointer over it opens a drop-down list with the column's available filter operations.

DevExtreme HTML5 JavaScript jQuery Knockout Angular TreeList Filtering FilterRow

The set of available filter operations can be restricted using the filterOperations option. You can also preselect a filter operation and specify the initial filter value with the selectedFilterOperation and filterValue options. Call the columnOption method at runtime to change these options:

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        filterRow: { visible: true },
        columns: [{
            dataField: "Status",
            filterOperations: ["contains", "="],
            selectedFilterOperation: "contains",
            filterValue: "Pending"
        }]
    });
});
JavaScript
$("#treeListContainer").dxTreeList("columnOption", "Status", {
    selectedFilterOperation: "=",
    filterValue: "Finished"
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxo-filter-row [visible]="true"></dxo-filter-row>
    <dxi-column 
        dataField="Status"
        [filterOperations]="['contains', '=']"
        [(selectedFilterOperation)]="selectedOperation"
        [(filterValue)]="filterValue">
    </dxi-column>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    selectedOperation: string = "contains";
    filterValue: any = "Pending";
    applyFilter (operation, value) {
        this.selectedOperation = operation;
        this.filterValue = value;
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
See Also

Header Filter

A header filter allows a user to filter values in an individual column by including or excluding them from the applied filter. Clicking a header filter icon invokes a popup menu with all the column's unique values. A user includes or excludes values from the filter by selecting or clearing their selection in this menu.

DevExtreme HTML5 JavaScript jQuery Knockout Angular TreeList Filtering HeaderFilter

View Demo

Assign true to the headerFilter.visible option to make header filter icons visible for all columns. Set a column's allowHeaderFiltering option to false if its header filter should not be available. Note that this option inherits the allowFiltering option's value by default.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        headerFilter: { visible: true },
        columns: [{
            // ...
            allowHeaderFiltering: false
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxo-header-filter [visible]="true"></dxo-header-filter>
    <dxi-column [allowHeaderFiltering]="false" ... ></dxi-column>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

A user can change the applied filter by including or excluding values. Use a column's filterType option to specify the required mode. You can specify the initial filter by combining this option and the filterValues option. To change it at runtime, call the columnOption method:

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            dataField: "OrderDate",
            filterType: "exclude", // or "include"
            filterValues: [2014]
        }]
    });
});
JavaScript
$("#treeListContainer").dxTreeList("columnOption", "OrderDate", {
    filterType: "include",
    filterValues: [2014, 2015]
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxi-column 
        dataField="OrderDate"
        [(filterValues)]="filterValues"
        [(filterType)]="filterType"> 
    </dxi-column>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    filterValues: Array<any> = [2014];
    filterType: string = "exclude";    // or "include"
    applyFilter (filterType, values) {
        this.filterType = filterType;
        this.filterValues = values;
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

You can use the headerFilter.allowSearch option to enable the header filter's searching capability. The same option can be declared in a column's configuration object, in which case it controls searching in that column's header filter.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        headerFilter: { 
            visible: true,
            allowSearch: true
        },
        columns: [{
            // ...
            headerFilter: { 
                allowSearch: false
            }
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxo-header-filter [visible]="true" [allowSearch]="true"></dxo-header-filter>
    <dxi-column ... >
        <dxo-header-filter [allowSearch]="false"></dxo-header-filter>
    </dxi-column>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

A header filter's popup menu lists all column values by default. You can group them using the headerFilter.groupInterval option if they are numbers or dates. You can also provide a custom data source for a header filter using the dataSource option. Refer to the option's description for details.

See Also

Search Panel

The search panel allows searching for values in several columns at once. Search is case-insensitive.

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget TreeList SearchPanel

View Demo

To make the search panel visible, assign true to the searchPanel.visible option. You can set a column's allowSearch option to false if it should be excluded from searching. Note that this option inherits the allowFiltering option's value by default.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        searchPanel: { visible: true },
        columns: [{
            // ...
            allowSearch: false
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxo-search-panel [visible]="true"></dxo-search-panel>
    <dxi-column [allowSearch]="false" ... ></dxi-column>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

Use the searchPanel.text option to predefine the search value. You can also change it at runtime by calling the searchByText(text) method:

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        searchPanel: {
            visible: true,
            text: "4/1/2015"
        }
    });
});
JavaScript
$("#treeListContainer").dxTreeList("searchByText", "1/29/2016");
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxo-search-panel 
        [visible]="true" 
        [(text)]="searchText">
    </dxo-search-panel>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    searchText: string = "4/1/2015";
    setSearchValue (searchText) {
        this.searchText = searchText;
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

Searching is performed differently depending on a column's data type. Numeric, Boolean, and date columns require that a user enters a full value into the search panel. Searching columns containing string values and specifying the search value using the API requires entering only a part of a value.

See Also

Filter Panel with Filter Builder

The filter panel displays the applied filter expression.

DevExtreme HTML5 JavaScript jQuery Angular Knockout TreeList Filter Panel

You can click the filter expression to open the integrated filter builder.

DevExtreme HTML5 JavaScript jQuery Angular Knockout TreeList Filter Panel

View Demo

Set the filterPanel.visible option to true to make the filter panel visible.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        filterPanel: { visible: true }
    });
});
Angular
HTML
<dx-tree-list ... >
    <dxo-filter-panel [visible]="true"></dxo-filter-panel>
</dx-tree-list>

If a user changes the filter expression in the filter panel or filter builder, the changes are reflected in the filter row and header filter, and vice versa. Set the filterSyncEnabled option to false to disable this synchronization. In this case, the filter panel remains synchronized with the filter builder.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        filterSyncEnabled: false
    });
});
Angular
HTML
<dx-tree-list ...
    [filterSyncEnabled]="false">
</dx-tree-list>

You can define the filter expression programmatically with the filterValue option. See the option's description for the full list of available filter operations and their peculiarities.

The filterValue is updated when a user changes the filter expression from the UI. Use the option method to update it from the API:

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        filterValue: ["SaleAmount", "<>", null],
        filterPanel: { 
            visible: true
        }
    });
});
JavaScript
$("#treeListContainer").dxTreeList("option", "filterValue", ["Employee", "contains", "Clark"]);
Angular
HTML
TypeScript
<dx-tree-list ...
    [(filterValue)]="filterValue">
    <dxo-filter-panel 
        [visible]="true">
    </dxo-filter-panel>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    filterValue: Array<any> = ['SaleAmount', '<>', null];
    applyFilter (filterExpression) {
        this.filterValue = filterExpression;
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

The TreeList provides the filterBuilder and filterBuilderPopup objects that configure the integrated filter builder and the popup in which it appears. These objects can contain the FilterBuilder's and Popup's options. In the following code, the filter builder has an additional filter operation Is Zero; the filter builder's popup is customized and displayed on a button click:

jQuery
JavaScript
$(function() {
    var treeList = $("#treeListContainer").dxTreeList({
        // ...
        filterPanel: { visible: false },
        filterSyncEnabled: true,
        filterBuilder: {
            customOperations: [{
                name: "isZero",
                caption: "Is Zero",
                dataTypes: ["number"],
                hasValue: false,
                calculateFilterExpression: function(filterValue, field) {
                    return [field.dataField, "=", 0];
                }
            }]
        }, 
        filterBuilderPopup: {
            width: 400,
            title: "Synchronized Filter"
        }
    }).dxTreeList("instance");
    $("#button").dxButton({
        text: "Show Filter Builder",
        onClick: function () {
            treeList.option("filterBuilderPopup", { visible: true });
        }
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... 
    [filterSyncEnabled]="true">
    <dxo-filter-panel [visible]="false"></dxo-filter-panel>
    <dxo-filter-builder 
        [customOperations]="customOperations">
    </dxo-filter-builder>
    <dxo-filter-builder-popup 
        [width]="400"
        title="Synchronized Filter"
        [(visible)]="popupVisible">
    </dxo-filter-builder-popup>
</dx-tree-list>
<dx-button
    text="Show Filter Builder"
    (onClick)="showFilterBuilder()">
</dx-button>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    popupVisible: boolean = false;
    customOperations = [{
        name: "isZero",
        caption: "Is Zero",
        dataTypes: ["number"],
        hasValue: false,
        calculateFilterExpression: function(filterValue, field) {
            return [field.dataField, "=", 0];
        }
    }];
    showFilterBuilder () {
        this.popupVisible = true;
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
See Also

Standalone Filter Builder

The TreeList widget has an integrated filter builder that can be invoked using the filter panel. You can also use the FilterBuilder widget as a standalone component. Pass an array of columns that should be filtered to the FilterBuilder's fields option. Each item in this array should at least have the dataField. The following code allows using TreeList columns in the FilterBuilder:

jQuery
JavaScript
var columns = [{
    caption: "ID",
    dataField: "Product_ID",
    dataType: "number"
}, {
    dataField: "Product_Name"
}, {
    caption: "Cost",
    dataField: "Product_Cost",
    dataType: "number",
    format: "currency"
}];

$(function () {
    $("#treeList").dxTreeList({
        dataSource: products, 
        columns: columns
    });
    $("#filterBuilder").dxFilterBuilder({
        fields: columns
    });
});
Angular
HTML
TypeScript
<dx-filter-builder 
    [fields]="columns">
</dx-filter-builder>
<dx-tree-list 
    [dataSource]="products"  
    [columns]="columns">
</dx-tree-list>
import { DxTreeListModule, DxFilterBuilderModule } from "devextreme-angular";
// ...
export class AppComponent {
    columns = [{
        caption: "ID",
        dataField: "Product_ID",
        dataType: "number"
    }, {
        dataField: "Product_Name"
    }, {
        caption: "Cost",
        dataField: "Product_Cost",
        dataType: "number",
        format: "currency"
    }];
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule,
        DxFilterBuilderModule
    ],
    // ...
})

Then, add a button that updates a filter of the TreeList's data source according to the filter expression:

jQuery
JavaScript
$(function () {
    // ...
    $("#button").dxButton({
        text: "Apply Filter",
        onClick: function () {
            var filter = $("#filterBuilder").dxFilterBuilder("instance").getFilterExpression();
            $("#treeList").dxTreeList("instance").filter(filter);
        }
    });
});
Angular
TypeScript
HTML
import { 
    DxTreeListModule, 
    DxFilterBuilderModule, 
    DxTreeListComponent, 
    DxFilterBuilderComponent 
} from "devextreme-angular";
// ...
export class AppComponent {
    @ViewChild(DxTreeListComponent, { static: false }) treeList: DxTreeListComponent;
    @ViewChild(DxFilterBuilderComponent, { static: false }) filterBuilder: DxFilterBuilderComponent;
    // Prior to Angular 8
    // @ViewChild(DxTreeListComponent) treeList: DxTreeListComponent;
    // @ViewChild(DxFilterBuilderComponent) filterBuilder: DxFilterBuilderComponent;
    // ...
    buttonClick() {
        this.treeList.instance.filter(this.filterBuilder.instance.getFilterExpression());
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule,
        DxFilterBuilderModule
    ],
    // ...
})
<dx-button 
    text="Apply Filter"
    (onClick)="buttonClick()">
</dx-button>   
See Also

API

Initial and Runtime Filtering

The initial and runtime filtering API depends on the UI element and is described in the topics above. This API is designed to filter data the data source returns. If you need to pre-filter data in the data source, call the filter(filterExpr) method by passing a filter expression as an argument. Note that this filter can only be cleared programmatically.

jQuery
JavaScript
$("#treeListContainer").dxTreeList("filter", [
    [ "Cost", ">", 1000 ],
    "and",
    [ "Cost", "<=", 2000 ]
]);
Angular
TypeScript
import { ..., ViewChild } from "@angular/core";
import { DxTreeListModule, DxTreeListComponent } from "devextreme-angular";
// ...
export class AppComponent {
    @ViewChild(DxTreeListComponent, { static: false }) treeList: DxTreeListComponent;
    // Prior to Angular 8
    // @ViewChild(DxTreeListComponent) treeList: DxTreeListComponent;
    filterByCost () {
        this.treeList.instance.filter([
            [ "Cost", ">", 1000 ],
            "and",
            [ "Cost", "<=", 2000 ]
        ]);
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

You can create a filter that combines all the applied filters by calling the getCombinedFilter() method. It returns a filter with getters by default. Call it by passing true as the argument to get the combined filter with data fields.

jQuery
JavaScript
$("#treeListContainer").dxTreeList("getCombinedFilter", true);
Angular
TypeScript
import { ..., ViewChild } from "@angular/core";
import { DxTreeListModule, DxTreeListComponent } from "devextreme-angular";
// ...
export class AppComponent {
    @ViewChild(DxTreeListComponent, { static: false }) treeList: DxTreeListComponent;
    // Prior to Angular 8
    // @ViewChild(DxTreeListComponent) treeList: DxTreeListComponent;
    getCombinedFilter () {
        return this.treeList.instance.getCombinedFilter(true);
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
See Also

Clear Filtering Settings

The clearFilter(filterName) method allows you to clear different filter settings depending on the argument. Acceptable arguments are listed in the method's description.

jQuery
JavaScript
// Clears the search panel
$("#treeListContainer").dxTreeList("clearFilter", "search");
Angular
TypeScript
import { ..., ViewChild } from "@angular/core";
import { DxTreeListModule, DxTreeListComponent } from "devextreme-angular";
// ...
export class AppComponent {
    @ViewChild(DxTreeListComponent, { static: false }) treeList: DxTreeListComponent;
    // Prior to Angular 8
    // @ViewChild(DxTreeListComponent) treeList: DxTreeListComponent;
    clearSearchPanel () {
        this.treeList.instance.clearFilter("search");
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
See Also