Search

JavaScript Data GridSet Filter - API

Enterprise

This section describes how the Set Filter can be controlled programmatically using API calls.

Set Filter Model

Get and set the state of the Set Filter by getting and setting the model on the filter instance.

// get filter model
const model = api.getColumnFilterModel('country');

// set filter model and update
await api.setColumnFilterModel('country', { values: ['Spain', 'Ireland', 'South Africa'] });

// refresh rows based on the filter (not automatic to allow for batching multiple filters)
api.onFilterChanged();

The filter model contains an array of string values where each item in the array corresponds to an element to be selected from the set.

Properties available on the SetFilterModel interface.

filterType
'set'
'set'
values
SetFilterModelValue
SetFilterModelValue

Set Filter API

The Set Filter instance can be retrieved via the getColumnFilterInstance API method.

// get filter instance
api.getColumnFilterInstance('country').then(countryFilterComponent => {
    // use set filter instance
});

The ISetFilter interface defines the public API for the Set Filter.

Properties available on the ISetFilter<V = string> interface.

getModel
Function
Returns a model representing the current state of the filter, or null if the filter is not active.
setModel
Function
Sets the state of the filter using the supplied model. Providing null as the model will de-activate the filter.

Note: if you are providing values asynchronously to the Set Filter, you need to wait for these changes to be applied before performing any further actions by waiting on the returned grid promise, e.g. filter.setModel({ values: ['a', 'b'] }).then(function() { gridApi.onFilterChanged(); });
getFilterKeys
Function
Returns the full list of unique keys used by the Set Filter.
getFilterValues
Function
Returns the full list of unique values used by the Set Filter.
setFilterValues
Function
Sets the values used in the Set Filter on the fly.
refreshFilterValues
Function
Refreshes the values shown in the filter from the original source. For example, if a callback was provided, the callback will be executed again and the filter will refresh using the values returned.
Refreshing Values
resetFilterValues
Function
Resets the Set Filter to use values from the grid, rather than any values that have been provided directly.
getMiniFilter
Function
Returns the current mini-filter text.
setMiniFilter
Function
Sets the text in the Mini Filter at the top of the filter (the 'quick search' in the popup).
isFilterActive
Function
Returns true if the filter is currently active, otherwise false. If active then 1) the grid will show the filter icon in the column header and 2) the filter will be included in the filtering of the data.
refresh
Function
This method is called when the filter parameters change. The result returned by this method will determine if the filter should be refreshed and reused, or if a new filter instance should be created. This method should return true if the filter should be refreshed and reused instead of being destroyed. This is useful if the new params passed are compatible with the existing filter instance. When false is returned, the existing filter will be destroyed and a new filter will be created. This should be done if the new params passed are not compatible with the existing filter instance.
newParams {IFilterParams} - New filter params.
Returns: {boolean} - true means that the filter should be refreshed and kept. false means that the filter will be destroyed and a new filter instance will be created.
afterGuiAttached
Function
Optional: A hook to perform any necessary operation just after the GUI for this component has been rendered on the screen. If a parent popup is closed and reopened (e.g. for filters), this method is called each time the component is shown. This is useful for any logic that requires attachment before executing, such as putting focus on a particular DOM element.
afterGuiDetached
Function
Optional: A hook to perform any necessary operation just after the GUI for this component has been removed from the screen. If a parent popup is opened and closed (e.g. for filters), this method is called each time the component is hidden. This is useful for any logic to reset the UI state back to the model before the component is reopened.

It is important to note that when updating the Set Filter through the API, it is up to the developer to call filterInstance.applyModel() to apply the changes that have been made to the model and then api.onFilterChanged() at the end of the interaction with the filter.

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

If no call to api.onFilterChanged() is provided the grid will still show the data relevant to the filter before it was updated through the API.

In the example below, you can see how the filter for the Athlete column is modified through the API and how at the end of the interaction a call to api.onFilterChanged() is performed.

Enabling Case-Sensitivity

By default the API is case-insensitive. You can enable case sensitivity by using the caseSensitive: true filter parameter:

const gridOptions = {
    columnDefs: [
        {
            field: 'colour',
            filter: 'agSetColumnFilter',
            filterParams: {
                caseSensitive: true
            }
        }
    ],

    // other grid options ...
}

The caseSensitive option also affects Mini-Filter searches and the values presented in the Filter List.

The following example demonstrates the difference in behaviour between caseSensitive: false (the default) and caseSensitive: true:

  • With caseSensitive: false (the default):
    • setModel() will perform case-insensitive matching against available values to decide what is enabled in the Filter List.
    • setFilterValues() will override the available values and force the case of the presented values in the Filter List to those provided.
      • Selected values will be maintained based upon case-insensitive matching.
  • With caseSensitive: true:
    • setModel() will perform case-sensitive matching against available values to decide what is enabled in the Filter List.
    • setFilterValues() will override the available values and force the case of the presented values in the Filter List to those provided.
      • Selected values will be maintained based upon case-sensitive matching.
  • In both cases getModel() and getFilterValues() will return the values with casing that matches those displayed in the Filter List.

Next Up

Continue to the next section to learn about Multi Filters.