Filter API

You can interact either with filters 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 (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 filterInstance = gridApi.getFilterInstance('name');

All of the methods of the filter are present. If using a custom filter then 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', filterInstance => { ... use filterInstance here });

Re-running Grid Filtering

When a filter has been changed via it's API, the method gridOptions.api.onFilterChanged() is required to get 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' }); // Get 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 using other methods provided by the filter instance (eg most of the Set Filter API methods) then you must call filterInstance.applyModel() to have the model applied. This step is necessary regardless of the Apply Button active or not.

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'); // Call some methods on Set Filter API that don't apply the filter filterInstance.selectNothing(); filterInstance.selectValue('Ireland'); // APPLY THE MODEL!!!! filterInstance.applyModel(); // Get grid to run filter operation again gridApi.onFilterChanged();

If no call is made to filterInstance.applyModel() then the filter UI will show the changes, but it 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 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:


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).