Date Filter

Date filters allow users to filter data based on the dates contained in the column where this filter is defined. To create a new date filter in a column, all you need to do is:

The date filter uses your own date component if you have one registered automatically. So both in the rich filter and the floating filter it will be used to let the user pick dates. Isn't that nice :)
  1. Enable filtering on that column
  2. Set the filter type to date
  3. Specify the date comparator to use if the data in this column are not native Javascript dates. See section date filter parameters below

In order to set the filter type to date you need to add the following to your column definition

colDef: { filter: 'agDateColumnFilter' }

Date Filter Parameters

A date filter can take the following parameters:

  • newRowsAction: What to do when new rows are loaded. The default is to reset the filter. If you want to keep the filter status between row loads, then set this value to 'keep'.
  • applyButton: Set to true to include an 'Apply' button with the filter and not filter automatically as the selection changes.
  • clearButton: Set to true to include a 'Clear' button with the filter which when cliked will remove the filter conditions to this filter.
  • comparator: Needed if the data for this column are not native JS objects. See section below
  • inRangeInclusive: Set to true so that when doing inRange date filters it will include the dates you specify as minimum and maximum, otherwise it selects only the dates in between.
  • filterOptions: If specified, limits the amount of options presented in the filter UI, it must be a string array containing some of the following values {equals, notEqual, lessThanOrEqual, greaterThan, greaterThanOrEqual, inRange}
  • defaultOption: If specified, changes the default filter option to one of {equals, notEqual, lessThanOrEqual, greaterThan, greaterThanOrEqual, inRange}. If not specified the default type is {equals}, if {equals} is not available because is removed using filterOptions, then the default is the first item in the filterOptions
  • nullComparator: If specified, it will be used to specify if null values should be included when filtering. See: Null filtering
  • browserDatePicker: This is only taking into consideration if there isn’t a date component provided. By default the grid will use the browser date picker in Chrome and a plain text box for all other browsers (this is because Chrome is the only browser providing a decent out of the box date picker). If this property is true, the browser date picker will be used regardless of the browser type.
  • suppressAndOrCondition If true, the filter won't offer the ability to add an additional filter condition

Date Filter Comparator

Dates can be represented in your data in many ways e.g. as a JavaScript Date object, or as a string in the format eg "26-MAR-2020" or something else different. How you represent dates will be particular to your application. If you are filtering JavaScript date objects the filter will work automatically, but if you are representing your date in any other format you will have to provide your own comparator callback.

The comparator callback takes two parameters. The first parameter is a Javascript date object with the local date at midnight selected in the filter. The second parameter is the current value of the cell being evaluated. The callback 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.

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

Date Filter Model

Get and set the state of the date filter by getting and setting the model on the filter instance.

// get filter instance var dobFilterComponent = gridOptions.api.getFilterInstance('dob'); // get filter model var model = dobFilterComponent.getModel(); // OR set filter model and update dobFilterComponent.setModel({ type:'equals', dateFrom:'2008-08-24' }); gridOptions.api.onFilterChanged() // NOTE number filter allows for ranges dobFilterComponent.setModel({ type:'inRange', dateFrom:'2008-08-24' dateTo:'2012-08-24' }); gridOptions.api.onFilterChanged()

The dates for the date filter model are always serialised and expected to be a string with the format yyyy-mm-dd

The number filter model has the following attributes:

  • type: The type of date filter to apply. One of: {equals, notEqual, lessThanOrEqual, greaterThan, greaterThanOrEqual, inRange}
  • date: The actual filter date to apply, or the start of the range if the filter type is inRange
  • dateTo: The end range of the filter if the filter type is inRange, otherwise has no effect.

Combined filter AND/OR

The date filter supports specifying an additional filter condition, if that is the case, then the filter model looks like this

{ condition1:{ type:'lessThan', dateFrom:'2008-08-24' }, condition2:{ type:'greaterThan', dateFrom:'2008-08-24' }, // one of 'AND' / 'OR' operator:'OR' )

Note that in this scenario, condition1 and condition2 each contains the individual model for the filter condition and operator takes one of 'AND' or 'OR'

It can be forced for a column to only ever have one condition for filtering by passing to the column filterParams.suppressAndOrCondition = true

Floating Date Filter

If your grid has floatingFilter enabled, your columns with number filter will automatically show below the header a new column that will show two elements:

  • Filter input box: Dates represented here need to be entered in the following format: yyyy-mm-dd. This input box serves two purposes:
    1. Lets the user change directly the filtering date that will be used for filtering, if the filter type is inRange, the dateTo property will only be accessible from the filter rich menu or by setting the model through the code.
    2. It reflects any change made to the filtering date from anywhere within the application. This includes changes on the rich filter for this column made by the user directly or changes made to the filter through a call to setModel to this filter component
  • Filter button: This button is a shortcut to show the rich filter editor

Common Column Filtering Functionality And Examples

The following can be found in the column filtering documentation page

  • Common filtering params
  • Enabling/Disabling filtering in a column
  • Enabling/Disabling floating filter
  • Adding apply and clear button to a column filter
  • Filtering animation
  • Examples