Set Filter

Set filters allow you to filter on set data, influenced by how filters work in Microsoft Excel. The page Provided Filters explains the common parts of all provided filters. This page builds on that and explains some details that are specific to the set filter.

Set Filter Parameters

The set filter params are as follows:

Parameter Description
applyButton
clearButton
debounceMs
newRowsAction
See Provided Filter Params.
cellHeight The height of the cell.
cellRenderer Similar to the cell renderer for the grid (you can use the same one in both locations). Setting it separately here allows for the value to be rendered differently in the filter. Note that the cell renderer for the set filter only receives the value as a parameter, as opposed to the cell renderer in the colDef that receives more information.
values The values to display in the filter. If this is not set, then the filter will takes its values from what is loaded in the table. Setting it allows you to set values where a) the value may not be present in the list (for example, if you want to show all states in America so that the user is not confused by missing states, even though states are missing from the data set in the grid) and b) the list is not available (happens when doing server side filtering in pagination and infinite scrolling).
suppressRemoveEntries Set to true to stop the filter from removing values that are no longer available (like what Excel does).
comparator(a,b)

Comparator for sorting. If not provided, the colDef comparator is used. If colDef also not provided, the default (agGrid provided) comparator is used.

The comparator for a set filter is only provided the values as the first two parameters, whereas the comparator for the colDef is also provided the row data as additional parameters. This is because when sorting rows, row data exists. For example, take 100 rows split across the color values [white, black]. The colDef comparator will be sorting 100 rows, however the filter will be only sorting two values.

If you are providing a comparator that depends on the row data, and you are using set filter, be sure to provide the set filter with an alternative comparator that doesn't depend on the row data.

suppressSorting If true, sorting will not be done on the set filter values. Use this if providing your own values and don't want them sorted as you are providing in the order you want.
suppressMiniFilter Set to false(default)/true to show/hide the input text box to filter the set entries displayed in the filter.
selectAllOnMiniFilter Set to false(default)/true so that the checkbox "select all" applies to: all the filters items/just the ones filtered by the mini filter.
textFormatter If specified, formats the text before applying the mini filter compare logic, useful for instance if substituting accentuated characters or if you want to do case sensitive mini filtering. This matches the text formatter used for text filters.

Complex Objects - keyCreator

If you are providing complex objects as values, then you need to provide colDef.keyCreator method in your object for the set filter to work, giving a unique value for the object. This is because the set filter needs a string key to identify the value. The example below demonstrates keyCreator with the country column by replacing the country name in the data with a complex object of country name and code. If the keyCreator was not provided on the colDef, the set filter would not work.

Set Filter - Search Field

The text box in the set filter is to allow filtering of displayed filter items, but doesn't actually change the applied filter.

The expected flow when using the search box would be uncheck "Select All", type what you're after in the search box and then finally select the filter entries you want to actually filter on.

Set Filters Example

The example below demonstrates the set filter. Notice that the athlete column is given the set of filters, providing some filter options for which no corresponding rows exist - this can be used if you are missing items in what would otherwise be a complete list, if listing days of the week, and no data for Wednesday exists, then presenting the filter to the user could give the impression that the filter is broken because it is missing Wednesday as an option.

The example also demonstrates 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.

The column sport has also the property suppressMiniFilter set to true, hiding the text input box for the set filter in this column (compare this set filter with athlete which suppressMiniFilter is the default = false).

The column country has the property selectAllOnMiniFilter set to true, you can see how the select all only applies to the items filtered by the mini filter search box.

The column athlete has a debounce of 1000ms before the selected options are filtered out

Asynchronous Values

In addition to being able to specify a hardcoded list of values for your setFilter, you can provide a callback to load the values asynchronously. The callback receives a parameter object. The interface for this parameter object is like this:

export interface SetFilterValuesFuncParams { // The function to call with the values to load for the filter once that they are ready success: (values: string[])=>void; // The column definition object from which the set filter is invoked colDef: ColDef, } a success callback function that you can callback as soon as the values for the setFilter are ready.

This can be observed in the next example. Note that:

  • colDef.filterParams.values specifies the values for the set filter in a callback and introduces a 5 second delay filterParams: { values: (params)=>{ setTimeout(()=>{ params.success(['value 1', 'value 2']) }, 5000) } }
  • While the data is obtained, (the 5s delay), the setFilter is showing a loading message
  • The loading message can be configured, check our internationalisation docs. The key for this string is loadingOoo
  • The callback is only invoked the first time the filter is opened. The next time the filter is opened the values are not loaded again.

Sorting And Formatting Set Filter Values List

Values inside a set filter will be sorted by their string value by default. If you want a different sort order than the natural string sort order, you need to provide a comparator.

The example below shows sorting on the age columns. The age column is repeated with one difference, the first instance has a comparator, the second has not. The second iteration has the numbers ordered by the default string ordering which is not correct (ie the sequence is 0,1,10,11,2 instead of 0,1,2,3...).

It also shows the athlete column using a text formatter so that 'o' will match 'Bjørk' in the mini filter. You can check this by searching for 'bjo'in the mini-filter box.

Refresh After Edit or Transcation Update

The set filter does NOT refresh after you a) edit the data (eg through the grid UI) or 2) update the data using Transaction Updates. If the data is changing and you want the set filter values to also change, it is up to your application to get the filter to change.

The grid does not update the filters for you as the as there are two many use cases that are open to different interpretation. For example, different users will have different requirements on how to handle new values or how to handle row refresh (eg if a filter is active, should the data be filtered again after the value is added).

The example below shows different approaches on handling data changes for set filters. From the example, the following can be noted:

  • All 4 columns have set filter with different responses to data changing.
  • All four columns have their filters initialised when the grid is loaded by calling getFilterInstance() when the gridReady event is received. This means when you edit, the filter is already created.
  • Column 1 has no special handling of new values.
  • Column 2 after an update: a) gets the filter to update.
  • Column 3 after an update: a) gets the filter to update and b) makes sure the new value is selected.
  • Column 4 after an update: a) gets the filter to update and b) makes sure the new value is selected and c) refreshes the rows based on the new filter value. So for example if you first set the filter on Col 4 to 'A' (notice that 'B' rows are removed), then change a value from 'A' to 'B', then the other rows that were previously removed are added back in again.
  • Click 'Add C Row' to add a new row. Columns 3 and 4 will have their filters updated. Columns 1 and 2 will not have their filters updated.

Why do we do this? The reason is if the filters were changing as the editing was happening, then this would cause the following issues:

  • Rows could disappear while editing if there was a filter set and the edit make a row fail a filter that was previously passing the filter.
  • Values could be split, eg if

New Rows Action and Values Example

Below demonstrates using New Rows Action and Values. The example is not meant to make business sense, it just demonstrates the filters with random unrelated data. The example has the columns configured as follows:

  • Column Fruit - Normal
  • Column Animal - Using newRowsAction = Keep
  • Column Color - Using values
  • Column Location - Using values and using newRowsAction = Keep

The 'Set New Data' button sets new data into the grid. It is suggested you set the filters and then observe what happens when you hit 'Set New Data'.

Although the example works, it demonstrates one dangerous situation, which is mixing newRowsAction=keep without providing values. This is dangerous and if you do not provide values, then the grid will create the values for you based on the data inside the grid (which is normally great). The problem is that when new values enter the grid, if the set of values is different, then this makes it impossible for the grid to keep the same filter selection. If the set of values is different, then newRowsAction=keep breaks down. In this situation, the grid will keep the same selected values, however it will loose information about previously selected values that no longer exist in the new set.

Set Filter Model

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

// get filter instance var countryFilterComponent = gridOptions.api.getFilterInstance('country'); // get filter model var model = countryFilterComponent.getModel(); // OR set filter model and update countryFilterComponent.setModel({ type: 'set', values: ['Spain','Ireland','South Africa','Australia','England'] }); gridApi.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:

In version 17.1.x of ag-Grid, the set filter model change. If you are using version 17.1.x or later, you don't need to be concerned. The following outlines the old and new models side by side: // OLD model was simple string array var model = ['Value 1', 'Value 2']; // NEW model is object with type and values var model = { type: 'set', values: ['Value 1', 'Value 2'] }; The setModel() method will work with both model versions. The getModel() will provide the new version.

To disable this change and have the grid exclusively work with the old model, set grid property enableOldSetFilterModel=true.

Both models will be supported for releases for the next 6 months. After this one major ag-Grid release will have the old model deprecated and then the following release will have it dropped.

Set Filter API

The set filter has on top of the getModel and setModel methods common to all the filters the following API:

  • setMiniFilter(newMiniFilter): Sets the filter at the top of the filter (the 'quick search' in the popup)
  • getMiniFilter(): Gets the mini filter text.
  • selectEverything(): Selects everything
  • selectNothing(): Clears the selection
  • isFilterActive(): Returns true if anything except 'everything selected'
  • unselectValue(value): Unselects a value
  • selectValue(value): Selects a value
  • isValueSelected(value): Returns true if a value is selected
  • isEverythingSelected(): Returns true if everything selected (inverse of isFilterActive())
  • isNothingSelected(): Returns true if nothing is selected
  • getUniqueValueCount(): Returns number of unique values. Useful for iterating with getUniqueValue(index)
  • getUniqueValue(index): Returns the unique value at the given index
  • setFilterValues(arrayOfStringOptions): Useful if you want to change on the fly the available options
  • resetFilterValues(): Useful if you want to rebuild the filter options based on the underlying data
  • setLoading(loading): Useful if you want to show/hide the loading overlay in the set filter.

Is important to note that when updating the set filter through the API is up to the developer to call gridOptions.api.onFilterChanged() at the end of the interaction with the filter. If no call to gridOptions.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 gridOptions.api.onFilterChanged() is performed.