Filter API

You can interact with filters either directly, by getting a reference to the filter instance, or indirectly, by getting and setting all filter models through the grid API. This page details how to do both.

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 (i.e. what was created after ag-Grid called new on your filter). You get a reference to a filter instance by calling api.getFilterInstance(colKey).

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

All of the methods of the filter are present. If using a custom filter, any other methods you have added will also be present, allowing bespoke behaviour to be added to your filter.

For filters that are created asynchronously including React 16+ components, getFilterInstance will return null if the filter has not already been created. If your app uses asynchronous components, use the optional callback function which will be invoked with the filter instance when it is available.

// Get a reference to an asynchronously created filter instance gridApi.getFilterInstance('name', function(filterInstance) { ... use filterInstance here });

Re-running Grid Filtering

When a filter has been changed via its API, the method gridOptions.api.onFilterChanged() is required to be called to tell the grid to filter the rows again. If gridOptions.api.onFilterChanged() is not called, the grid will still show the data relevant to the filter before it was updated through the API.

// Get a reference to the 'name' filter instance var filterInstance = gridApi.getFilterInstance('name'); // Set the model for the filter filterInstance.setModel({ type: 'endsWith', filter: 'g' }); // Tell grid to run filter operation again gridApi.onFilterChanged();

Applying the Model

If you call filterInstance.setModel() this will both set and apply the model. However if changes are made either in the UI when the Apply button is active, or via other API methods whether the Apply button is active or not, you must call filterInstance.applyModel() if you want to ensure the UI is applied.

Applying the model is then typically followed by calling gridOptions.api.onFilterChanged() to have the grid re-run the filtering.

// Get a reference to the 'name' filter instance var filterInstance = gridApi.getFilterInstance('name'); // Apply the model to ensure any changes in the UI or via API methods are recognised filterInstance.applyModel(); // Tell grid to run filter operation again gridApi.onFilterChanged();

If no call is made to filterInstance.applyModel() then the filter UI will show any changes, but they won't be reflected in the filter model. This will appear as if the user never hit the Apply button (regardless of whether the Apply button is active or not).

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 if you want a filter to be created again with new initialisation values.

(Note: the example uses the Enterprise-only set filter).

Reset Individual Filters

You can reset a filter to its original state by getting the filter instance and setting the model to null.

For all the filter types the sequence would be:

// Get a reference to the filter instance var filterInstance = gridApi.getFilterInstance('filter_name'); // set the model to null filterInstance.setModel(null); // Tell grid to run filter operation again gridApi.onFilterChanged();

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 getFilterModel() and 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 stage. 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 set that into the filters.

(Note: the example uses the Enterprise-only set filter).