Column Filter

Data in ag-Grid can be filtered in the following ways:

1. 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 filter element if floating filters are turned on.
2. Quick Filter: The quick filter is a simple text filter that filters across all columns.
3. 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

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.

gridOptions = { // turn on filtering enableFilter: true, ... columnDefs: [ {headerName: "Athlete", field: "athlete", filter: "text"}, // text filter {headerName: "Age", field: "age", filter: "number"}, // number filter {headerName: "Sport", field: "sport", suppressFilter: true} // NO filter ] }

Filter Types

The following filter options can be set for a column definition:

Filter	Description
number	A Number Filter for number comparisons.
text	A Text Filter for string comparisons.
date	A Date Filter for date comparisons.
set	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.

Filter Parameters

Each filter can take additional filter params by setting colDef.filterParams. 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.

columnDefinition = { headerName: 'Athlete', field: 'athlete' // set the column to use text filter filter: 'text', // pass in additional parameters to the text filter filterParams: {apply: true, newRowsAction: 'keep'} }

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-filtered class, 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

Apply Function

If you want the user to hit an 'Apply' button before the filter is actioned, add apply=true 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).

Filter Events

Filtering results in the following events getting emitted:

filterChanged	Filter has changed.
filterModified	Gets called when filter has been modified but filterChanged not necessarily called. This is useful when using an apply button inside the filter, as this event fires when the filter is modified, and then filterChanged is fired when the apply button is pressed.

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.

Filtering Animation

To enable animation of the rows after filtering, set grid property animateRows=true.

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 api.getFilterInstance(colKey).

// Get a reference to the name filter instance var nameFilterInstance = api.getFilterInstance('name');

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
• gridOptions.api.onFilterChanged();

The following are the appropriate methods for the corresponding filter types:

Filter Type	Action
number	filterComponent.setModel(null);
text	filterComponent.setModel(null);
set	filterComponent.selectEverything();

Reset All Filters

You can reset all filters by doing the following:

gridOptions.api.setFilterModel(null);

Get / Set All Filter Models

It is possible to get and set the state of all the filters via the api methods api.getFilterModel() and api.setFilterModel(). These methods manage the filters states via the getModel() and setModel() 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

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 floatingFilter=true:

gridOptions = { // turn on floating filters floatingFilter: true ... }

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 getModel() and setModel() 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 columnDef.filterParams.nullComparator The null comparator is an object used to tell if nulls should be included when filtering data, its interface it's like this: export interface NullComparator{ equals?:boolean lessThan?:boolean greaterThan?:boolean }

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 columnDef.filterParams.nullComparator

Note that inRange will never include null.