The grid provides three simple filters for filtering numbers, strings and dates respectively.
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=falseis set on Total to hide the filter on this column
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.
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 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.
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:
|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|
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|
|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:
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:
Examples of filter model instances are as follows:
filterTypeis 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:
An example of a filter model with two conditions is as follows:
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
displayKey should contain a unique key value that doesn't clash with the built-in filter keys.
displayName should also be provided but can be replaced by a locale specific value using a
The custom filter logic is implemented through the
test function, which receives the
typed by the user along with the
cellValue from the grid, and returns
It is also possible to hide the filter input field by enabling the optional property
FilterOptionDef's can be supplied alongside the built-in filter option
as shown below:
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
blanks. It also has uses the build in 'empty' filter along with
- The 'Date' column includes a custom
equalsWithNullsfilter. Note that a custom
comparatoris still required for the built-in date filter options, i.e.
- The 'Country' column includes a custom
notEqualNoNullsfilter 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.setFilterModel()can also be tested using the provided buttons.
Blank Cells (Date and Number Filters)
If the row data contains blanks (ie
undefined) it won't be included in
filter results. To change this use the filter params
For example the code snippet below configures a filter to include null for equals,
but not for less than or great than:
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
undefinedvalues resulting in blank cells.
Toggle the controls on the top to see how
includeBlanksInGreaterThanimpact 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.