Filtering and Searching

Watch Video

Filter Row

The filter row allows a user to filter data by values of individual columns. Usually, cells in the filter row are text boxes, but in columns that hold date or Boolean values, those cells contain controls more suitable for filtering, like 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 applies automatically 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, pausing on which opens a drop-down list with filters available for the column.

DevExtreme HTML5 JavaScript jQuery Knockout Angular TreeList Filtering FilterRow

The set of available filters can be restricted using the filterOperations option. You can also preselect a filter with the selectedFilterOperation option. Combining these two options, you can preselect a filter and disallow a user to change it, for example:

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        filterRow: { visible: true },
        columns: [{
            // ...
            selectedFilterOperation: "contains",
            filterOperations: []
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxo-filter-row [visible]="true"></dxo-filter-row>
    <dxi-column ...
        selectedFilterOperation="contains"
        [filterOperations]="[]">
    </dxi-column>
</dx-tree-list>
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@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 to/from it. Use a column's filterType option to specify the required mode.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        columns: [{
            // ...
            filterType: "exclude" // or "include"
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxi-column ...
        [filterType]="exclude"> <!-- or "include" -->
    </dxi-column>
</dx-tree-list>
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

The header filter provides a searching capability that you can enable using the headerFilter.allowSearch option. 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 value of the allowFiltering option 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
    ],
    // ...
})

Search 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. For columns that contain string values, entering only a part of a value is enough to find it.

See Also

Filter Builder

The FilterBuilder widget helps a user build a complex filter expression and apply it to all grid columns at once.

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget TreeList FilterBuilder

To integrate the FilterBuilder with the TreeList, first, 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 at least. The following code allows using all 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 build filter expression. The value option stores this expression.

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

API

Initial and Runtime Filtering

The API for filtering differs depending on the UI element that it affects. To specify an initial value for a filter row cell, set a column's selectedFilterOperation and filterValue options. You can also change these options with the columnOption method to assign a new value to a fitler row cell at runtime.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        fitlerRow: { visible: true },
        columns: [{
            // ...
            dataField: "isOnVacation",
            selectedFilterOperation: "=",
            filterValue: true
        }]
    });
});
JavaScript
$("#treeListContainer").dxTreeList("columnOption", "isOnVacation", "filterValue", false);
Angular
HTML
<dx-tree-list ... >
    <dxo-filter-row [visible]="true"></dxo-filter-row>
    <dxi-column ...
        dataField="isOnVacation"
        selectedFilterOperation="="
        [filterValue]="true">
    </dxi-column>
</dx-tree-list>
TypeScript
import { ..., ViewChild } from '@angular/core';
import { DxTreeListModule, DxTreeListComponent } from 'devextreme-angular';
// ...
export class AppComponent {
    @ViewChild(DxTreeListComponent) treeList: DxTreeListComponent;
    setFilterValue (dataFieldName, newValue) {
        this.treeList.instance.columnOption(dataFieldName, "filterValue", newValue);
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

To specify initial values for a header filter, set a column's filterType and filterValues options. You can change these options with the columnOption method at runtime as well.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        headerFilter: { visible: true },
        columns: [{
            // ...
            dataField: "OrderDate",
            filterType: "exclude",
            filterValues: [2014]
        }]
    });
});
JavaScript
$("#treeListContainer").dxTreeList("columnOption", "OrderDate", "filterValues", [2014, 2015]);
Angular
HTML
<dx-tree-list ... >
    <dxo-header-filter [visible]="true"></dxo-header-filter>
    <dxi-column ...
        dataField="OrderDate"
        filterType="exclude"
        [filterValues]="[2014]">
    </dxi-column>
</dx-tree-list>
TypeScript
import { ..., ViewChild } from '@angular/core';
import { DxTreeListModule, DxTreeListComponent } from 'devextreme-angular';
// ...
export class AppComponent {
    @ViewChild(DxTreeListComponent) treeList: DxTreeListComponent;
    setFilterValues (dataFieldName, newValue) {
        this.treeList.instance.columnOption(dataFieldName, "filterValues", newValue);
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

You can specify an initial text for the search panel using the searchPanel.text option. Call the searchByText(text) method to change the text at runtime.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        searchPanel: {
            visible: true,
            text: "Pending"
        }
    });
});
JavaScript
$("#treeListContainer").dxTreeList("searchByText", "Solved");
Angular
HTML
<dx-tree-list ... >
    <dxo-search-panel [visible]="true" text="Pending"></dxo-search-panel>
</dx-tree-list>
TypeScript
import { ..., ViewChild } from '@angular/core';
import { DxTreeListModule, DxTreeListComponent } from 'devextreme-angular';
// ...
export class AppComponent {
    @ViewChild(DxTreeListComponent) treeList: DxTreeListComponent;
    setSearchString (newString) {
        this.treeList.instance.searchByText(newString);
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

All the aforementioned options and methods filter data that was returned by the data source. If you need to pre-filter data in the data source, call the filter(filterExpr) method passing a filter expression as an argument. Note that this filter can be cleared only 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) treeList: DxTreeListComponent;
    filterByCost () {
        this.treeList.instance.filter([
            [ "Cost", ">", 1000 ],
            "and",
            [ "Cost", "<=", 2000 ]
        ]);
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

Since there are many ways to filter data, you may need to get a filter combined from all applied filters. For this, call the getCombinedFilter() method. It returns the filter with getters by default. Call it 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) treeList: DxTreeListComponent;
    getCombinedFilter () {
        return this.treeList.instance.getCombinedFilter(true);
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
See Also

Clear Filtering Settings

Use the clearFilter(filterName) method to clear filtering settings. You can call it with one of the following parameters:

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) treeList: DxTreeListComponent;
    clearSearchPanel () {
        this.treeList.instance.clearFilter("search");
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})