Simple Filters

The grid provides three simple filters for filtering numbers, strings and dates respectively.

Text Filter
 Number Filter
 Date Filter

Each of the filters works in a similar way. This page describes the common parts of the simple provided filters.

Simple Filter Example

The example below demonstrates all three simple filters working. Note the following:

  • Three filter types: 1) text filter, 2) number filter and 3) date filter.
  • filter=false is set on Total to hide the filter on this column

Remember Filtering works with all frameworks eg Angular and React as well as plain JavaScript.

Simple Filter Parts

Each simple filter follows the same layout. The only layout difference is the type of input field presented to the user. For text and number filters a text field is displayed. For date filter a date selector is displayed.

Filter Options

Each filter provides a drop down list of filter options to select from. Each filter option represents a filtering strategy eg 'equals', 'not equals' etc.

Each filters Filter Options is listed below as well as Defining Custom Filter Options.

Filter Value

Each filter option takes zero (a possibility with custom options), one (for most) or two (for 'in rage') values. The value type depends on the filter type eg Date Filter takes Date values.

Condition 1 and Condition 2

Each filter initially displays Condition 1 only. When the user completes the Condition 1 section of the filter then Condition 2 becomes visible.

Join Operator

The Join Operator decides how Condition 1 and Condition 2 are joined, whether to use AND or OR.

Simple Filters Parameters

Simple Filters are configured though the filterParams attribute of the column definition. The list of filter parameters for all simple filters is as follows:

Parameter Description Supported Filters
applyButton
clearButton
resetButton
debounceMs
newRowsAction		 See Provided Filter Params. Text, Number, Date
filterOptions What Filter Options to present to the user. Text, Number, Date
defaultOption The default Filter Options to be selected. Text, Number, Date
suppressAndOrCondition If true, the filter will only offer Condition 1. Text, Number, Date
textCustomComparator Used to override what to filter based on the user input. See textCustomComparator section below. Text
caseSensitive Set to true to make text filtering case sensitive. Otherwise the filtering will be case insensitive Text
textFormatter Formats the text before applying the filter compare logic, useful for instance if substituting accentuated characters or if you want to do case sensitive filtering. Text
inRangeInclusive If true then doing 'inRange' filter option will include values equal to the start and end of the range. Number, Date
includeBlanksInEquals If true then blank (null or undefined) values will pass the 'equals' filter option. Number, Date
includeBlanksInLessThan If true then blank (null or undefined) values will pass the 'lessThan' and 'lessThanOrEqual' filter options. Number, Date
includeBlanksInGreaterThan If true then blank (null or undefined) values will pass the 'greaterThan' and 'greaterThanOrEqual' filter options. Number, Date
comparator Needed if the data for this column are not native JS Date objects. Date
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. Date

Filter Options

Each filter presents a list of options to the user. The list of options for each filter are as follows:

Option Name Option Key Supported Filters
Equals equals Text, Number, Date
Not Equals notEqual Text, Number, Date
Contains contains Text
Not Contains notContains Text
Starts With startsWith Text
Ends With endsWith Text
Less Than lessThan Number, Date
Less Than or Equal lessThanOrEqual Number
Greater Than greaterThan Number, Date
Greater Than or Equal greaterThanOrEqual Number
In Range inRange Number, Date
Empty* empty Text, Number, Date

* 'Empty' is a special filter option. When Empty is displayed, it means the filter is not active.

Default Filter Options

Each of the three filter types has the following default options and default selected option.

Filter Default List of Options Default Selected Option
Text Contains, Not Contains, Equals, Not Equals, Starts With, Ends With. Contains
Number Equals, Not Equals, Less Than, Less Than or Equal, Greater Than, Greater Than or Equal, In Range. Equals
Date Equals, Greater Than, Less Than, Not Equals, In Range. Equals

Simple Filter Models

When saving or restoring state on a filter the filter model is used. The filter model represents the state of the filter. For example the code below first gets and then sets the filter model for the Athlete column:

// get filter instance var filterInstance = gridOptions.api.getFilterInstance('athlete'); // get filter model var model = filterInstance.getModel(); // OR set filter model and update filterInstance.setModel({ type:'endsWith', filter:'thing' }); // tell the grid to refresh rows based on the filter. the filter does not // do this automatically in case multiple filters are going to get set. gridOptions.api.onFilterChanged()

This section explains what the filter model looks like for each of the simple filters. The interface followed by each filter type is as follows:

The best way to understand what the filter models look like is to set a filter via the UI and call api.getFilterModel(). Then observe what the filter model looks like for different variations of the filter. // text filter uses this filter model interface TextFilterModel { // always 'text' for text filter filterType: string; // one of the filter options eg 'equals' type: string; // the text value associated with the filter. // it's optional as custom filters may not // have a text value filter?: string; } // number filter uses this filter model interface NumberFilterModel { // always 'number' for number filter filterType: string; // one of the filter options eg 'equals' type: string; // the number value(s) associated with the filter. // custom filters can have no values (hence both are optional). // range filter has two values (from and to). filter?: number; filterTo?: number; } // date filter uses this filter model interface DateFilterModel { // always 'date' for date filter filterType: string; // one of the filter options eg 'equals' type: string; // the date value(s) associated with the filter. // the type is string and format is always YYYY-MM-DD eg 2019-05-24 // custom filters can have no values (hence both are optional). // range filter has two values (from and to). dateFrom: string; dateTo: string; }

Examples of filter model instances are as follows:

// number filter with one condition, with equals type var numberLessThan35 = { filterType: 'number', type: 'lessThan', filter: 35 }; // number filter with one condition, with inRange type var numberBetween35And40 = { filterType: 'number', type: 'inRange', filter: 35, filterTo: 40 }; The filterType is not used by the grid when you call setFilterModel(). It is provided for information purposes only when you get the filter model. This is useful if you are doing server side filtering, where the filter type may be used in building back end queries.

If the filter has both Condition 1 and Condition 2 set, then two instances of the model are created and wrapped inside a Combined Model. A combined model looks as follows:

// a filter combining two conditions. the 'M' is replace with the type // of filter model, one of TextFilterModel, NumberFilterModel or DateFilterModel interface ICombinedSimpleModel<M> { // the filter type, date, number or text filterType: string; // one of 'AND' or 'OR' operator: string; // two instance of the filter model condition1: M; condition2: M; }

An example of a filter model with two conditions is as follows:

// number filter with two conditions, both are equals type var numberEquals18OrEquals20 = { filterType: "number", operator: "OR" condition1: { filterType: "number", type: "equals", filter: 18 }, condition2: { filterType: "number", type: "equals", filter: 18 } };

Custom Filter Options

For applications that have bespoke filtering requirements, it is also possible to add new custom filtering options to the number, text and date filters. For example, a 'Not Equal (with Nulls)' filter option could be included alongside the built in 'Not Equal' option.

Custom filter options are supplied to the grid via filterParams.filterOptions and must conform to the following interface:

export interface IFilterOptionDef { displayKey: string; displayName: string; test: (filterValue: any, cellValue: any) => boolean; hideFilterInput?: boolean; }

The displayKey should contain a unique key value that doesn't clash with the built-in filter keys. A default displayName should also be provided but can be replaced by a locale specific value using a localeTextFunc.

The custom filter logic is implemented through the test function, which receives the filterValue typed by the user along with the cellValue from the grid, and returns true or false.

It is also possible to hide the filter input field by enabling the optional property hideFilterInput.

Custom FilterOptionDef's can be supplied alongside the built-in filter option string keys as shown below:

{ field: "age", filter: 'agNumberColumnFilter', filterParams: { filterOptions: [ 'lessThan', { displayKey: 'lessThanWithNulls', displayName: 'Less Than with Nulls', test: function(filterValue, cellValue) { return cellValue == null || cellValue < filterValue; } }, 'greaterThan', { displayKey: 'greaterThanWithNulls', displayName: 'Greater Than with Nulls', test: function(filterValue, cellValue) { return cellValue == null || cellValue > filterValue; } } ] } }

The following example demonstrates several custom filter options:

  • The 'Athlete' column contains two custom filter options Starts with "A" and Starts with "B". Both these options take no text filter input.
  • The 'Age' column contains two custom filter options evenNumbers, oddNumbers and blanks. It also has uses the build in 'empty' filter along with suppressAndOrCondition=true.
  • The 'Date' column includes a custom equalsWithNulls filter. Note that a custom comparator is still required for the built-in date filter options, i.e. equals.
  • The 'Country' column includes a custom notEqualNoNulls filter which also removes null values.
  • The 'Country' columns also demonstrates how internationalisation can be achieved via the gridOptions.localeTextFunc() callback function, where the default value replaced for the filter option 'notEqualNoNulls'.
  • Saving and Restoring custom filter options via api.getFilterModel() and api.setFilterModel() can also be tested using the provided buttons.

Blank Cells (Date and Number Filters)

If the row data contains blanks (ie null or undefined) it won't be included in filter results. To change this use the filter params includeBlanksInEquals, includeBlanksInLessThan and includeBlanksInGreaterThan. For example the code snippet below configures a filter to include null for equals, but not for less than or great than:

filterParams = { includeBlanksInEquals: true, includeBlanksInLessThan: false, includeBlanksInGreaterThan: false }

Only less than, greater than and equals allow nulls. In Range will never include null values.

In the following example you can filter by age or date and see how blank values are included. Not the following:

  • Columns Age and Date have both null and undefined values resulting in blank cells.
  • Toggle the controls on the top to see how includeBlanksInEquals, includeBlanksInLessThan and includeBlanksInGreaterThan impact the search result.

Style Header on Filter

Each time a filter is applied to a column the CSS class ag-header-cell-filtered is added to the header. This can be used for adding style to headers that are filtered.

In the example below a background color is added to ag-header-cell-filtered. This means any column you filter on will it's header change background color.