Data in ag-Grid can be filtered in the following ways:
- Column Filter: A column filter is associated with a column and filters data based
on the value of that column only. The column filter is accessed via the column's menu and
may also have a
floating filterelement if floating filters are turned on.
- Quick Filter: The quick filter is a simple text filter that filters across all columns.
- External Filter: External filters is a way for your application to apply bespoke filtering with no restriction to the columns.
Column filters are tied to a column. Quick filter and external filter are not tied to a column. This section of the documentation talks about column filters only. For quick filter and external filter, see the relevant sections of the documentation.
You have two options for filtering, one is use one of the default built-in filters (easy but restricted to what's provided), or bake your own custom filters (no restrictions, build what you want, but takes more time).
Enable filtering by setting grid property
enableFilter=true. This turns on filtering on all columns.
To turn off filtering for particular columns, set
suppressFilter=true on the individual column definition.
When a filter is active on a column, the filter icon appears before the column name in the header.
The following filter options can be set for a column definition:
|agNumberColumnFilter||A Number Filter for number comparisons.|
|agTextColumnFilter||A Text Filter for string comparisons.|
|agDateColumnFilter||A Date Filter for date comparisons.|
|agSetColumnFilter||A Set Filter, influenced by how filters work in Microsoft Excel. This is an ag-Grid-Enterprise feature.|
|-custom-||A Filter Component where you can provide you own filter written in a framework of your choice.|
If no filter type is specified, the default is 'text' for ag-Grid (free versions) and 'set' for ag-Grid Enterprise.
Each filter can take additional filter params by setting
What parameters each filter type takes is explained in the section on each filter.
As an example, the following sets parameters for the text filter.
Built In Filters Example
The example below demonstrates:
- Three filter types 1) text filter, 2) number filter and 3) date filter.
- Using the
ag-header-cell-filteredclass, which is applied to the header cell when the header is filtered. By default, no style is applied to this class, the example shows applying a different color background to this style.
- 'suppressFilter' is set on Total to hide the filter on this column
If you want the user to hit an 'Apply' button before the filter is actioned, add
to the filter parameters. The example below shows this in action for the first three columns.
This is handy if the filtering operation is taking a long time (usually it doesn't), or if doing server side filtering (thus preventing unnecessary calls to the server).
Filtering results in the following events getting emitted:
|filterChanged||Filter has changed.|
Gets called when filter has been modified but
Example: Apply Button and Filter Events
The example below also demonstrates using the apply button and filter events as follows:
- onFilterModified gets called when the filter changes regardless of the apply button.
- onFilterChanged gets called after a new filter is applied.
To enable animation of the rows after filtering, set grid property
Accessing Filter Component Instances
It is possible to access the filter components directly if you want to interact with the specific
filter. This also works for your own custom filters, where you can
get a reference to the underlying filtering instance (ie what was created after ag-Grid called 'new'
on your filter). You get a reference to the filter instance by calling
All of the methods of the IFilter interface are present, assuming the underlying filter implements the method. Your custom filters can add their own methods here that ag-Grid will not use but your application can use. What these extra methods do is up to you and between your customer filter and your application.
Example Filter API
The example below shows controlling the country and age filters via the API.
The example also shows 'gridApi.destroyFilter(col)' which completely destroys a filter. Use this is if you want a filter to be created again with new initialisation values.
(Note: the example uses the enterprise set filter).
Reset Individual Filters
You can reset a filter to its original state by getting the filter instance and then performing the action that makes sense for the filter type.
For all the filter types the sequence would be:
var filterComponent = gridOptions.api.getFilterInstance('filter_name');
- perform reset action for filter type
The following are the appropriate methods for the corresponding filter types:
Reset All Filters
You can reset all filters by doing the following:
Get / Set All Filter Models
It is possible to get and set the state of all the filters via the api methods
api.setFilterModel(). These methods manage the filters states via the
methods of the individual filters.
This is useful if you want to save the filter state and apply it at a later state. It is also useful for server side filtering, where you want to pass the filter state to the server.
Example - Get / Set All Filter Models
The example below shows getting and setting all the filter models in action. The 'save' and 'restore' buttons mimic what you would do to save and restore the state of the filters. The big button (Name = 'Mich%'... etc) shows how you can hand craft a model and then set that into the filters.
(Note: the example uses the enterprise set filter).
Floating Filters are an additional row under the column headers where the user will be able to see and optionally edit the filters associated to each column.
Floating filters are activated by setting grid property
Floating filters are an accessory to the main column filters. They do not contain their own state,
rather they display the state of the main filter, and if editable they set state on the main filter.
Underneath the hood this is done by using the main filters
methods. For this reason, there is no api for getting or setting state of the floating filters.
All the default filters provided by ag-Grid provide their own implementation of a floating filter.
All you need to do to enable these floating filters is set the
floatingFilter=true grid property.
Every floating filter also takes a parameter to show/hide automatically a button that will open the main filter.
To see the specifics on what are all the parameters and the interface for a floating filter check out the docs for floating filter components.
The following example shows the following features of floating filters:
- Text filter: Have out of the box read/write floating filters (Sport column)
- Set filter: Have out of the box read floating filters (Country column)
- Date and number filter: Have out of the box read/write floating filters for all filter except when switching to in range filtering, then the floating filter is read only (Age and date columns)
- Columns with the applyButton require the user to press enter on the floating filter for the filter to take effect (Gold column)
- Changes made from the outside are reflected automatically in the floating filters (Press any button)
- Columns with custom filter have automatic read only filter if the custom filter implements the method getModelAsString. (Athlete column)
- The user can configure when to show/hide the button that shows the rich filter (Silver and Bronze columns)
- Columns with suppressFilter=true don't have floating filters (Total column)
- Combining suppressMenu and suppressFilter lets you control where the user access to the rich filter. In this example suppressMenu = true for all the columns except Silver and Bronze
Server Side Filtering
Some of the row models (pagination and infinite scrolling) have further information on how to implement server side filtering. For details on this, see the the sections pagination and infinite scrolling.
Filtering null values in Date and Number filters
If your underlying data representation for a row contains
null it won't be included in the filter results. If
you want to change this behaviour, you can configure the property
The null comparator is an object used to tell if nulls should be included when filtering data, its interface it's like
If any of this properties is specified as true, the grid will include
null values when doing the according filtering.
In the following example you can filter by age or date and see how
null values are included in the filter based
on the combination of filter type and your
inRange will never include