Angular DataGrid - columns.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 property.

dataSource

Specifies the header filter's data source.

Type:

Array<any>

|

Function

|

DataSource Configuration

Function parameters:
options:

Object

Data source properties.

Object structure:
Name Type Description
component

Object

The UI component's instance.
dataSource

DataSource Configuration

A DataSource configuration.
Default Value: undefined

The DataGrid generates a header filter's data source automatically based on column values. Use the dataSource property 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 property 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() {
    $("#dataGridContainer").dxDataGrid({
        // ...
        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-data-grid ... >
    <dxi-column>
        <dxo-header-filter
            [dataSource]="headerFilterData">
        </dxo-header-filter>
    </dxi-column>
</dx-data-grid>
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 { DxDataGridModule } from 'devextreme-angular';

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

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

import {
    DxDataGrid,
    DxColumn,
    DxHeaderFilter
} from 'devextreme-vue/data-grid';

export default {
    components: {
        DxDataGrid,
        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 { DataGrid, Column, HeaderFilter } from 'devextreme-react/data-grid';

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 (
            <DataGrid>
                <Column>
                    <HeaderFilter
                        dataSource={headerFilterData}
                    />
                </Column>
            </DataGrid>
        );
    }
}

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 property 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"]
    });

    $("#dataGridContainer").dxDataGrid({
        // ...
        columns: [{
            // ...
            headerFilter: {
                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-data-grid ... >
    <dxi-column>
        <dxo-header-filter
            [dataSource]="headerFilterData">
        </dxo-header-filter>
    </dxi-column>
</dx-data-grid>
import { Component } from '@angular/core';
import ArrayStore from 'devextreme/data/array_store';

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

        this.headerFilterData = {
            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 { DxDataGridModule } from 'devextreme-angular';

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

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

import {
    DxDataGrid,
    DxColumn,
    DxHeaderFilter
} from 'devextreme-vue/data-grid';
import ArrayStore from 'devextreme/data/array_store';

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

export default {
    components: {
        DxDataGrid,
        DxColumn,
        DxHeaderFilter
    },
    data() {
        return {
            headerFilterData: {
                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 { DataGrid, Column, HeaderFilter } from 'devextreme-react/data-grid';
import ArrayStore from 'devextreme/data/array_store';

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

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

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

export default App;

Change the Generated Data Source

To change the generated data source, set the dataSource property to a function. This function accepts an object whose dataSource field contains a DataSource configuration. 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() {
    $("#dataGridContainer").dxDataGrid({
        // ...
        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-data-grid ... >
    <dxi-column>
        <dxo-header-filter
            [dataSource]="customizeHeaderFilterData">
        </dxo-header-filter>
    </dxi-column>
</dx-data-grid>
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 { DxDataGridModule } from 'devextreme-angular';

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

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

import {
    DxDataGrid,
    DxColumn,
    DxHeaderFilter
} from 'devextreme-vue/data-grid';

export default {
    components: {
        DxDataGrid,
        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 { DataGrid, Column, HeaderFilter } from 'devextreme-react/data-grid';

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

    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>";
    }

    $("#dataGridContainer").dxDataGrid({
        // ...
        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-data-grid ... >
    <dxi-column>
        <dxo-header-filter
            [dataSource]="headerFilterData">
        </dxo-header-filter>
    </dxi-column>
    <div *dxTemplate="let data of 'boldFont'">
        <b>{{data.text}}</b>
    </div>
</dx-data-grid>
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 { DxDataGridModule } from 'devextreme-angular';

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

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

import {
    DxDataGrid,
    DxColumn,
    DxHeaderFilter
} from 'devextreme-vue/data-grid';

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: {
        DxDataGrid,
        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 { DataGrid, Column, HeaderFilter } from 'devextreme-react/data-grid';

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 (
            <DataGrid>
                <Column>
                    <HeaderFilter
                        dataSource={headerFilterData}
                    />
                </Column>
                 <Template name="boldFont" render={renderBoldText} />
            </DataGrid>
        );
    }
}

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 property 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 property. 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 property when the UI component 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 property when the UI component 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