Framework:Javascript Data GridAngular Data GridReact Data GridVue Data Grid

JavaScript Data Grid: Date Filter

Date filters allow you to filter date data. The Provided Filters and Simple Filters pages explain the parts of the date filter that are the same as the other provided filters. This page builds on that and explains some details that are specific to the date filter.

Date Filter Parameters

Date Filters are configured though the filterParams attribute of the column definition. All of the parameters from Provided Filters are available:

Specifies the buttons to be shown in the filter, in the order they should be displayed in. The options are:
  • 'apply': If the Apply button is present, the filter is only applied after the user hits the Apply button.
  • 'clear': The Clear button will clear the (form) details of the filter without removing any active filters on the column.
  • 'reset': The Reset button will clear the details of the filter and any active filters on that column.
  • 'cancel': The Cancel button will discard any changes that have been made to the filter in the UI, restoring the applied model.
  • buttons: FilterButtonType[];
    type FilterButtonType = 
        | 'clear' 
        | 'reset' 
        | 'cancel'
    If the Apply button is present, the filter popup will be closed immediately when the Apply or Reset button is clicked if this is set to true.
    Default: false
    Overrides the default debounce time in milliseconds for the filter. Defaults are:
  • TextFilter and NumberFilter: 500ms. (These filters have text field inputs, so a short delay before the input is formatted and the filtering applied is usually appropriate).
  • DateFilter and SetFilter: 0ms
  • readOnly
    If set to true, disables controls in the filter to mutate its state. Normally this would be used in conjunction with the Filter API. See Read-only Filter UI.
    Default: false

    In addition, the following parameters are also available for Date filters:

    Required if the data for the column are not native JS Date objects.
    This is only used if a date component is not provided. By default the grid will use the browser date picker in Chrome and Firefox and a plain text box for all other browsers (This is because Chrome and Firefox are the only current browsers providing a decent out-of-the-box date picker). If this property is set to true, the browser date picker will be used regardless of the browser type. If set to false, a plain text box will be used for all browsers.
    This is the minimum year that may be entered in a date field for the value to be considered valid.
    Default: 1000
    This is the maximum year that may be entered in a date field for the value to be considered valid. Default is no restriction.
    Defines the date format for the floating filter text when an in range filter has been applied.
    Default: YYYY-MM-DD
    inRangeFloatingFilterDateFormat: string;

    MonthM1 2 ... 11 12
    Mo1st 2nd ... 11th 12th
    MM01 02 ... 11 12
    MMMJan Feb ... Nov Dec
    MMMMJanuary February ... November December
    Day of MonthD1 2 ... 30 31
    Do1st 2nd ... 30th 31st
    DD01 02 ... 30 31
    Day of Weekd0 1 ... 5 6
    do0th 1st ... 5th 6th
    ddSu Mo ... Fr Sa
    dddSun Mon ... Fri Sat
    ddddSunday Monday ... Friday Saturday
    YearYY70 71 ... 29 30
    YYYY1970 1971 ... 2029 2030
    Y1970 1971 ... 9999 +10000 +10001

    If true, the 'inRange' filter option will include values equal to the start and end of the range.
    If true, blank (null or undefined) values will pass the 'equals' filter option.
    If true, blank (null or undefined) values will pass the 'lessThan' and 'lessThanOrEqual' filter options.
    If true, blank (null or undefined) values will pass the 'greaterThan' and 'greaterThanOrEqual' filter options.
    If true, blank (null or undefined) values will pass the 'inRange' filter option.
    (IFilterOptionDef | ISimpleFilterModelType)[]
    Array of filter options to present to the user. See Filter Options.
    The default filter option to be selected.
    By default, the two conditions are combined using AND. You can change this default by setting this property. Options: AND, OR
    If true, the filter will only allow one condition.
    Default: false
    By default, only one condition is shown, and a second is made visible once a first condition has been entered. Set this to true to always show both conditions. In this case the second condition will be disabled until a first condition has been entered.
    Default: false

    Date Selection Component

    By default the grid will use the browser-provided date picker for Chrome and Firefox (as we think it's nice), but for all other browsers it will provide a simple text field. To override this and provide a custom date picker, see Date Component.

    Date Filter Comparator

    Dates can be represented in your data in many ways e.g. as a JavaScript Date object, as a string in a particular format such as '26-MAR-2020', or something else. How you represent dates will be particular to your application.

    By default, the date filter assumes you are using JavaScript Date objects. If this is the case, the date filter will work out of the box. However, if your date is in any other format you will have to provide your own comparator to perform the date comparisons.

    Required if the data for the column are not native JS Date objects.

    The comparator function takes two parameters. The first parameter is a JavaScript Date object for the selected date in the filter (with the time set to midnight). The second parameter is the current value of the cell in the row being evaluated. The function must return:

    • Any number < 0 if the cell value is less than the filter date.
    • 0 if the dates are the same.
    • Any number > 0 if the cell value is greater than the filter date.

    This pattern is intended to be similar to the JavaScript compareTo(a, b) function.

    Below is an example of using a date filter with a comparator.

    const gridOptions = {
        columnDefs: [
            // column definition configured to use a date filter
                field: 'date',
                filter: 'agDateColumnFilter',
                // add extra parameters for the date filter
                filterParams: {
                    // provide comparator function
                    comparator: (filterLocalDateAtMidnight, cellValue) => {
                        const dateAsString = cellValue;
                        if (dateAsString == null) {
                            return 0;
                        // In the example application, dates are stored as dd/mm/yyyy
                        // We create a Date object for comparison against the filter date
                        const dateParts = dateAsString.split('/');
                        const year = Number(dateParts[2]);
                        const month = Number(dateParts[1]) - 1;
                        const day = Number(dateParts[0]);
                        const cellDate = new Date(year, month, day);
                        // Now that both parameters are Date objects, we can compare
                        if (cellDate < filterLocalDateAtMidnight) {
                            return -1;
                        } else if (cellDate > filterLocalDateAtMidnight) {
                            return 1;
                        return 0;
        // other grid options ...

    Once the date comparator callback is provided, then the Date Filter is able to perform all the comparison operations it needs, e.g. 'Less Than', 'Greater Than' and 'Equals'.

    Date Model vs Comparison Types

    It should be noted that the Date Filter Model represents the Date as a string in format 'YYYY-MM-DD', however when doing comparisons the date is provided as a JavaScript Date object as that's what date pickers typically work with. The model uses string representation to make it easier to save and avoid any timezone issues.

    Example: Date Filter

    The example below shows the date filter in action, using some of the configuration options discussed above:

    • The Date column is using a Date Filter.
    • A custom comparator is provided to parse the data and allow date comparisons to be made.
    • The native date picker is forced to be used in every browser.
    • The minimum valid year is set to 2000, and maximum valid year is 2021. Dates outside this range will be considered invalid, and will:

      • Deactivate the column filter. This avoids the filter getting applied as the user is typing a year - for example suppose the user is typing the year 2008, the filter doesn't execute for values 2, 20 or 200 (as the text 2008 is partially typed).
      • Be highlighted with a red border (default theme) or other theme-appropriate highlight.
    • the inRangeFloatingFilterDateFormat property has been set to define a custom date format, this is only shown in the floating filter panel when an in-range filter has been applied.