Skip to main content

Date Filter

  • 8 minutes to read

The Date Filter dashboard item allows you to filter dashboard data based on the selected data range. The range can be relative (Last 3 Months), use fixed dates (01-01-2018), or presets (Month-to-date). You can also filter dates before or after a specified date.

Run Demo: Date Filter

The Date Filter item displays a set of intervals that can be used as quick filters.

Date Filter

End-users can click the button to invoke the Date Picker:

Date Filter - Date Picker Drop-Down

Add a New Date Filter to the Dashboard

Bind to Data

Filter Type

A filter can be a DateTime value, DateTime range or infinite interval before or after a specified date.

You can specify the filter type as follows:

  • in the dashboard designer, click the drop-down Filter Type in the ribbon (Date Filter Tools contextual tab-> Design page -> Layout group):


  • in code, use the DateFilterDashboardItem.FilterType property.

Date Picker

Date Picker

The DateFilter item contains a Date Picker - a button with a drop-down calendar. This button initially displays “Click to set filter”. To change the text, provide the DateFilterDatePickerButtonDefaultText localization string or handle the DashboardViewer.DashboardItemControlCreated event and subscribe to the DateFilterControl.CustomDisplayText event.

The calendar drops down when the end user:

  • clicks the button without a specified range (the button with the “Click to set filter” caption)
  • clicks the edit-date-filter-icon icon on the button with the specified datetime range.

A drop-down calendar may contain a single calendar control (the Filter Type is Exact, Before or After) or two calendar controls (the Filter Type is Between).

When the user selects the date, the Date Picker caption displays information about that date (date range) and an edit-date-filter-icon icon. The caption text is constructed from a custom string with date placeholders. If the user clicks the caption, The Date Picker button acts as a checked button to apply the date range (checked) or reset the date filter (unchecked) to its default value. When the user clicks the icon, the drop-down calendar appears and enables the user to select another date range.

The Date Picker component can be located at the near end of the Quick Button series, at its far end, or it can be hidden. To change the Date Picker location:

  • in the dashboard designer, click the Date Picker Location check button in the ribbon (Date Filter Tools contextual tab-> Design page -> Layout group):

  • in code, set the DateFilterDashboardItem.DatePickerLocation property.

Display Format

To specify the date-time value format:

  • in the dashboard designer, use the Format submenu in the data item menu, as described in the Formatting Data topic.

  • in code, use the dimension’s DateTimeFormat property.

To specify a custom string displayed in the Date Picker component:

  • in the dashboard designer, use the Edit Names dialog. To invoke the dialog, right-click the DateFilter item and click the Edit Names… menu item or click the Edit Names button in the Design Ribbon tab.


  • in code, use the DateFilterDashboardItem.DisplayTextPattern property.

You can include placeholders in a custom string. The {0} placeholder is the interval’s start, the {1} placeholder is the interval’s end.

Create Quick Filters

Quick Filters are buttons displayed within the DateFilter item. Each button has a DateTime range assigned to it. You can click the button to apply that range as a Date filter. The button is checked until the end-user clicks the same button once more to reset the filter to its default value. The button becomes unchecked if the end user clicks another button.

Quick Filters

The item’s context menu contains commands with the same captions that act as quick filters.

A newly created DateFilter dashboard item has no quick filters. To add a quick filter:

  • in the dashboard designer, click the Options button (the BoundImageAttributeOptionsButton icon) next to the Argument placeholder

    • or select the Edit Periods command in the context menu
    • or click the Edit Periods in the ribbon (Date Filter Tools contextual tab-> Design page -> Interactivity group):


This invokes the Edit Periods dialog. You can select a predefined range or add a custom period, specify the quick filter’s range and caption.


Arrange Quick Filters

Quick filters in the DateFilter item can be arranged horizontally or vertically. The default mode is auto height, in which quick filters are displayed horizontally and the dashboard item shrinks automatically to fit the items and save space.

To specify the arrangement mode:

  • in the dashboard designer, click the Arrangement Mode drop-down in the ribbon (Date Filter Tools contextual tab-> Design page -> Layout group):


  • in code, set the DateFilterDashboardItem.ArrangementMode property.

Customize Underlying Controls

You can customize the appearance of the DateFilter’s buttons and drop-down calendar. To do this, access the underlying DateFilterControl as described in the Access to Underlying Controls topic and change its settings.

View Example: How to Customize the Date Filter Dashboard Item


This code snippet creates a DateFilter dashboard item in code.

View Example: How to Create a Dashboard with DateFilterDashboardItem in Code

using DevExpress.DashboardCommon;
using DevExpress.DashboardWin.Localization;
using DevExpress.DataAccess.Excel;
using DevExpress.XtraEditors;
using System;

namespace DateFilterDashboardItemSample
    public partial class Form1 : XtraForm
        public Form1()

        private void Form1_Load(object sender, EventArgs e)
            DashboardExcelDataSource excelDataSource = CreateExcelDataSource();
            Dashboard dBoard = new Dashboard();

            // Create dashboard items.
            ChartDashboardItem chart = CreateChart(excelDataSource);
            DateFilterDashboardItem dateFilterItem = CreateDateFilterItem(excelDataSource);
            DashboardItemGroup group = CreateGroup();
            group.AddRange(dateFilterItem, chart);
            // Create the layout tree.
            DashboardLayoutItem dateFilterLayoutItem = new DashboardLayoutItem(dateFilterItem, 30);
            DashboardLayoutItem chartLayoutItem = new DashboardLayoutItem(chart, 70);
            DashboardLayoutGroup groupLayoutItem = new DashboardLayoutGroup(group, 100);
            groupLayoutItem.ChildNodes.AddRange(dateFilterLayoutItem, chartLayoutItem);
            DashboardLayoutGroup rootGroup = new DashboardLayoutGroup(null, 100);
            rootGroup.Orientation = DashboardLayoutGroupOrientation.Vertical;
            dBoard.LayoutRoot = rootGroup;

            dashboardViewer1.Dashboard = dBoard;

        private DashboardItemGroup CreateGroup()
            DashboardItemGroup group = new DashboardItemGroup();
            group.Name = "Sales by Date";
            return group;

        private DateFilterDashboardItem CreateDateFilterItem(DashboardExcelDataSource excelDataSource)
            DateFilterDashboardItem dateFilter = new DateFilterDashboardItem();
            dateFilter.Name = string.Empty;
            dateFilter.ShowCaption = false;
            dateFilter.DataSource = excelDataSource;
            dateFilter.Dimension = new Dimension("orderDateId", "OrderDate", DateTimeGroupInterval.DayMonthYear);
            dateFilter.Dimension.DateTimeFormat.DateTimeFormat = DateTimeFormat.Short;
            dateFilter.ArrangementMode = DateFilterArrangementMode.Vertical;
            dateFilter.FilterType = DateFilterType.Between;
            dateFilter.DatePickerLocation = DatePickerLocation.Far;
                DateTimePeriod.CreateNextDays("Next 7 Days", 7),
                new DateTimePeriod
                    Name = DashboardWinLocalizer.GetString(DashboardWinStringId.PeriodMonthToDate),
                    Start = new FlowDateTimePeriodLimit
                        Interval = DateTimeInterval.Month,
                        Offset = 0
                    End = new FlowDateTimePeriodLimit
                        Interval = DateTimeInterval.Day,
                        Offset = 1
                new DateTimePeriod
                    Name = "Jul-18-2018 - Jan-18-2019",
                    Start = new FixedDateTimePeriodLimit
                        Date = new DateTime(2018, 7, 18)
                    End = new FixedDateTimePeriodLimit
                        Date = new DateTime(2019, 1, 18)
            return dateFilter;

        private ChartDashboardItem CreateChart(DashboardExcelDataSource excelDataSource)
            ChartDashboardItem chart = new ChartDashboardItem();
            chart.Name = string.Empty;
            chart.ShowCaption = false;
            chart.DataSource = excelDataSource;
            chart.Arguments.Add(new Dimension("OrderDate", DateTimeGroupInterval.DayMonthYear));
            chart.Panes.Add(new ChartPane());
            SimpleSeries salesAmountSeries = new SimpleSeries(SimpleSeriesType.Line);
            salesAmountSeries.Value = new Measure("Extended Price");
            return chart;

        private DashboardExcelDataSource CreateExcelDataSource()
            DashboardExcelDataSource excelDataSource = new DashboardExcelDataSource();
            excelDataSource.FileName = "SalesPerson.xlsx";
            ExcelWorksheetSettings worksheetSettings = new ExcelWorksheetSettings("Data");
            excelDataSource.SourceOptions = new ExcelSourceOptions(worksheetSettings);
            return excelDataSource;
See Also