headerFilter

Specifies data settings for the header filter.

Type:

Object

Default Value: undefined

See Also

allowSearch

Specifies whether searching is enabled in the header filter.

Type:

Boolean

Default Value: false

NOTE
With the ODataStore, searching a numeric column requires additional configuration: set the column's headerFilter.searchMode to "equals" and specify the type of the column's data field in the store's fieldTypes option.

dataSource

Specifies the header filter's data source.

Function parameters:
options:

Object

Data source options.

Object structure:
Name Type Description
component

Object

The widget's instance.

dataSource

DataSource Configuration

A DataSource instance.

Default Value: undefined

The TreeList generates a header filter's data source automatically based on column values. Use the dataSource option to change the generated data source or specify a custom data source.

Specify a Custom Data Source

To define a data source, set the dataSource option to an array of objects. Each object configures one header filter item and should have the following fields:

  • text
    A text string that represents the item in the header filter.

  • value
    A filter that the item applies. It can be a single value (for example, 0) or a filter expression. Refer to the filter help topic for information on the filter expression syntax.

The following code shows how to specify a custom data source:

jQuery
index.js
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            // ...
            headerFilter: {
                dataSource: [{
                    text: "Zero",
                    value: 0
                }, {
                    text: "Less than $3000",
                    value: ["SaleAmount", "<", 3000]
                }, {
                    text: "More than $3000",
                    value: ["SaleAmount", ">", 3000]
                }]
            }
        }]
    });
});
Angular
app.component.html
app.component.ts
app.module.ts
<dx-tree-list ... >
    <dxi-column>
        <dxo-header-filter
            [dataSource]="headerFilterData">
        </dxo-header-filter>
    </dxi-column>
</dx-tree-list>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    headerFilterData: any;
    constructor() {
        this.headerFilterData = [{
            text: "Zero",
            value: 0
        }, {
            text: "Less than $3000",
            value: ["SaleAmount", "<", 3000]
        }, {
            text: "More than $3000",
            value: ["SaleAmount", ">", 3000]
        }];
    }
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxTreeListModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxTreeListModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxTreeList>
        <DxColumn>
            <DxHeaderFilter
                :data-source="headerFilterData"
            />
        </DxColumn>
    </DxTreeList>
</template>

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

import {
    DxTreeList,
    DxColumn,
    DxHeaderFilter
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn,
        DxHeaderFilter
    },
    data() {
        return {
            headerFilterData: [{
                text: 'Zero',
                value: 0
            }, {
                text: 'Less than $3000',
                value: ['SaleAmount', '<', 3000]
            }, {
                text: 'More than $3000',
                value: ['SaleAmount', '>', 3000]
            }]
        };
    }
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { TreeList, Column, HeaderFilter } from 'devextreme-react/tree-list';

const headerFilterData = [{
    text: 'Zero',
    value: 0
}, {
    text: 'Less than $3000',
    value: ['SaleAmount', '<', 3000]
}, {
    text: 'More than $3000',
    value: ['SaleAmount', '>', 3000]
}];

class App extends React.Component {
    render() {
        return (
            <TreeList>
                <Column>
                    <HeaderFilter
                        dataSource={headerFilterData}
                    />
                </Column>
            </TreeList>
        );
    }
}

export default App;

View Demo

Map Data Source Fields

Header filter data objects should have the text and value fields. However, data objects fetched from a server may not have these fields. In this case, map the original data source to the text + value structure. A mapped data source should also include key fields from the original data source.

NOTE
We recommend that you keep the allowSearch option set to false because searching produces incorrect results when data source fields are mapped.

In the following code, the categoryName and categoryId fields are mapped to the text and value fields. The mapped objects also contain the categoryId and categoryCode key fields:

jQuery
index.js
$(function() {
    const categoriesStore = new DevExpress.data.ArrayStore({
        data: [
            { categoryName: "...", categoryId: 1, categoryCode: "..." },
            // ...
        ],
        key: ["categoryId", "categoryCode"]
    });

    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            // ...
            headerFilter: {
                dataSource: new DevExpress.data.DataSource({
                    store: categoriesStore,
                    map: function (item) {
                        return {
                            text: item.categoryName,
                            value: item.categoryId,
                            categoryId: item.categoryId,
                            categoryCode: item.categoryCode
                        }
                    }
                })
            }
        }]
    });
});
Angular
app.component.html
app.component.ts
app.module.ts
<dx-tree-list ... >
    <dxi-column>
        <dxo-header-filter
            [dataSource]="headerFilterData">
        </dxo-header-filter>
    </dxi-column>
</dx-tree-list>
import { Component } from '@angular/core';
import ArrayStore from 'devextreme/data/array_store';
import DataSource from 'devextreme/data/data_source';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    headerFilterData: DataSource;
    constructor() {
        const categoriesStore = new ArrayStore({
            data: [
                { categoryName: "...", categoryId: 1, categoryCode: "..." },
                // ...
            ],
            key: ["categoryId", "categoryCode"]
        });

        this.headerFilterData = new DataSource({
            store: categoriesStore,
            map: (item) => {
                return {
                    text: item.categoryName,
                    value: item.categoryId,
                    categoryId: item.categoryId,
                    categoryCode: item.categoryCode
                }
            }
        });
    }
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxTreeListModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxTreeListModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxTreeList>
        <DxColumn>
            <DxHeaderFilter
                :data-source="headerFilterData"
            />
        </DxColumn>
    </DxTreeList>
</template>

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

import {
    DxTreeList,
    DxColumn,
    DxHeaderFilter
} from 'devextreme-vue/tree-list';
import ArrayStore from 'devextreme/data/array_store';
import DataSource from 'devextreme/data/data_source';

const categoriesStore = new ArrayStore({
    data: [
        { categoryName: "...", categoryId: 1, categoryCode: "..." },
        // ...
    ],
    key: ["categoryId", "categoryCode"]
});

export default {
    components: {
        DxTreeList,
        DxColumn,
        DxHeaderFilter
    },
    data() {
        return {
            headerFilterData: new DataSource({
                store: categoriesStore,
                map: (item) => {
                    return {
                        text: item.categoryName,
                        value: item.categoryId,
                        categoryId: item.categoryId,
                        categoryCode: item.categoryCode
                    }
                }
            })
        };
    }
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { TreeList, Column, HeaderFilter } from 'devextreme-react/tree-list';
import ArrayStore from 'devextreme/data/array_store';
import DataSource from 'devextreme/data/data_source';

const categoriesStore = new ArrayStore({
    data: [
        { categoryName: "...", categoryId: 1, categoryCode: "..." },
        // ...
    ],
    key: ["categoryId", "categoryCode"]
});

const headerFilterData = new DataSource({
    store: categoriesStore,
    map: (item) => {
        return {
            text: item.categoryName,
            value: item.categoryId,
            categoryId: item.categoryId,
            categoryCode: item.categoryCode
        }
    }
});

class App extends React.Component {
    render() {
        return (
            <TreeList>
                <Column>
                    <HeaderFilter
                        dataSource={headerFilterData}
                    />
                </Column>
            </TreeList>
        );
    }
}

export default App;

Change the Generated Data Source

To change the generated data source, set the dataSource option to a function. This function accepts an object whose dataSource field contains a DataSource instance. Define the DataSource's postProcess function in which you can change header filter items.

In the following code, the postProcess function adds a custom item to the generated data source:

jQuery
index.js
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            // ...
            headerFilter: {
                dataSource: function (options) {
                    options.dataSource.postProcess = function (results) {
                        results.push({
                            text: "Weekends",
                            value: [
                                ['OrderDay', "=", 0],
                                    "or",
                                ['OrderDay', "=", 6]
                            ]
                        });
                        return results;
                    }
                }
            }
        }]
    });
});
Angular
app.component.html
app.component.ts
app.module.ts
<dx-tree-list ... >
    <dxi-column>
        <dxo-header-filter
            [dataSource]="customizeHeaderFilterData">
        </dxo-header-filter>
    </dxi-column>
</dx-tree-list>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    customizeHeaderFilterData(options) {
        options.dataSource.postProcess = (results) => {
            results.push({
                text: "Weekends",
                value: [
                    ['OrderDay', "=", 0], 
                        "or", 
                    ['OrderDay', "=", 6]
                ]
            });
            return results;
        }
    }
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxTreeListModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxTreeListModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxTreeList>
        <DxColumn>
            <DxHeaderFilter
                :data-source="customizeHeaderFilterData"
            />
        </DxColumn>
    </DxTreeList>
</template>

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

import {
    DxTreeList,
    DxColumn,
    DxHeaderFilter
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn,
        DxHeaderFilter
    },
    methods: {
        customizeHeaderFilterData(options) {
            options.dataSource.postProcess = (results) => {
                results.push({
                    text: 'Weekends',
                    value: [
                        ['OrderDay', '=', 0],
                            'or',
                        ['OrderDay', '=', 6]
                    ]
                });
                return results;
            }
        }
    }
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { TreeList, Column, HeaderFilter } from 'devextreme-react/tree-list';

class App extends React.Component {
    render() {
        return (
            <TreeList>
                <Column>
                    <HeaderFilter
                        dataSource={this.customizeHeaderFilterData}
                    />
                </Column>
            </TreeList>
        );
    }

    customizeHeaderFilterData(options) {
        options.dataSource.postProcess = function(results) {
            results.push({
                text: 'Weekends',
                value: [
                    ['OrderDay', '=', 0],
                        'or',
                    ['OrderDay', '=', 6]
                ]
            });
            return results;
        };
    }
}

export default App;

View Demo

Customize Item Appearance

You can use templates to customize the appearance of individual items. In the following code, a template makes the Today item bold:

jQuery
index.js
$(function() {
    const now = new Date();
    const startOfWeek = new Date(
        now.setDate(now.getDate() - now.getDay() - 1 + (now.getDay() === 0 ? -6 : 1))
    );
    const startOfDay = new Date(now.setHours(0,0,0,0));
    const boldFont = (data) => {
        return "<b>" + data.text + "</b>";
    }

    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            // ...
            headerFilter: {
                dataSource: [{
                    text: 'Today',
                    value: [['OrderDate', '>=', startOfDay], 'and', ['OrderDate', '<=', now]],
                    template: boldFont
                }, {
                    text: 'This week',
                    value: [['OrderDate', '>=', startOfWeek], 'and', ['OrderDate', '<', startOfDay]]
                }, {
                    text: 'Earlier',
                    value: ['OrderDate', '<', startOfWeek]
                }]
            }
        }]
    });
});
Angular
app.component.html
app.component.ts
app.module.ts
<dx-tree-list ... >
    <dxi-column>
        <dxo-header-filter
            [dataSource]="headerFilterData">
        </dxo-header-filter>
    </dxi-column>
    <div *dxTemplate="let data of 'boldFont'">
        <b>{{data.text}}</b>
    </div>
</dx-tree-list>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    headerFilterData: any;
    constructor() {
        const now = new Date();
        const startOfWeek = new Date(
            now.setDate(now.getDate() - now.getDay() - 1 + (now.getDay() === 0 ? -6 : 1))
        );             
        const startOfDay = new Date(now.setHours(0,0,0,0));

        this.headerFilterData = [{
            text: 'Today',
            value: [['OrderDate', '>=', startOfDay], 'and', ['OrderDate', '<=', now]],
            template: 'boldFont'
        }, {
            text: 'This week',
            value: [['OrderDate', '>=', startOfWeek], 'and', ['OrderDate', '<', startOfDay]]
        }, {
            text: 'Earlier',
            value: ['OrderDate', '<', startOfWeek]
        }];
    }
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxTreeListModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxTreeListModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxTreeList>
        <DxColumn>
            <DxHeaderFilter
                :data-source="headerFilterData"
            />
        </DxColumn>
        <template #bold-font="{ data }">
            <b>{{data.text}}</b>
        </template>
    </DxTreeList>
</template>

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

import {
    DxTreeList,
    DxColumn,
    DxHeaderFilter
} from 'devextreme-vue/tree-list';

const now = new Date();
const startOfWeek = new Date(
    now.setDate(now.getDate() - now.getDay() - 1 + (now.getDay() === 0 ? -6 : 1))
);             
const startOfDay = new Date(now.setHours(0,0,0,0));

export default {
    components: {
        DxTreeList,
        DxColumn,
        DxHeaderFilter
    },
    data() {
        return {
            headerFilterData: [{
                text: 'Today',
                value: [['OrderDate', '>=', startOfDay], 'and', ['OrderDate', '<=', now]],
                template: 'bold-font'
            }, {
                text: 'This week',
                value: [['OrderDate', '>=', startOfWeek], 'and', ['OrderDate', '<', startOfDay]]
            }, {
                text: 'Earlier',
                value: ['OrderDate', '<', startOfWeek]
            }]
        };
    }
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.common.css';
import 'devextreme/dist/css/dx.light.css';

import { TreeList, Column, HeaderFilter } from 'devextreme-react/tree-list';

const now = new Date();
const startOfWeek = new Date(
    now.setDate(now.getDate() - now.getDay() - 1 + (now.getDay() === 0 ? -6 : 1))
);
const startOfDay = new Date(now.setHours(0, 0, 0, 0));

const renderBoldText = (data) => <b>{data.text}</b>;

const headerFilterData = [{
    text: 'Today',
    value: [['OrderDate', '>=', startOfDay], 'and', ['OrderDate', '<=', now]],
    template: 'boldFont'
}, {
    text: 'This week',
    value: [['OrderDate', '>=', startOfWeek], 'and', ['OrderDate', '<', startOfDay]]
}, {
    text: 'Earlier',
    value: ['OrderDate', '<', startOfWeek]
}];

class App extends React.Component {
    render() {
        return (
            <TreeList>
                <Column>
                    <HeaderFilter
                        dataSource={headerFilterData}
                    />
                </Column>
                 <Template name="boldFont" render={renderBoldText} />
            </TreeList>
        );
    }
}

export default App;

groupInterval

Specifies how the header filter combines values into groups.

Type:

String

|

Number

Default Value: undefined
Accepted Values: 'day' | 'hour' | 'minute' | 'month' | 'quarter' | 'second' | 'year'

For date columns, set this option to one of the string values. Groups in date columns are hierarchical, and the string value indicates up to which level the hierarchy is formed. The default level is "day", which means that each group has the following structure: "year" → "months" → "days".

For numeric columns, assign a number to this option. This number designates a step with which groups should be generated. Column values are classified into these groups.

Use the HeaderFilterGroupInterval 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: Year, Quarter, Month, Day, Hour, Minute, and Second.

height

Specifies the height of the popup menu containing filtering values.

Type:

Number

Default Value: undefined

searchMode

Specifies a comparison operation used to search header filter values.

Type:

String

Default Value: 'contains'
Accepted Values: 'contains' | 'startswith' | 'equals'

Use the CollectionSearchMode 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: Contains, StartsWith, and Equals.

width

Specifies the width of the popup menu containing filtering values.

Type:

Number

Default Value: undefined