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:

Complex Objects - keyCreator

If you are providing complex objects as values, then you need to provide a colDef.keyCreator function to convert the objects to strings. This string is used to compare objects when filtering, and to render a label in the filter UI, so it should return a human-readable 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 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.

Set Filter Values with Live Data

The set filter will refresh it's values after any of the following:

1. Edit the data (eg through the grid UI).
2. Update the data using Transaction Updates
3. Update the data using Delta Row Mode.

The strategy for updating values after update mimics how similar filters in spreadsheets work. The rules for the update are as follows:

• When no filter is active, everything in the filter is selected. Adding and removing values will keep the list updated with everything selected.
• When a filter is active, new items (either new data into the grid, or edits to current data with new values not previously seen) will get added to the filter but will not be selected.

This will be somewhat strange when editing data as filtering does not re-execute when editing, so the row will not be filtered out even though the value in the cell is not selected in the filter.

If you do not want the set filter to update it's list of values after the data changes, then set suppressSyncValuesAfterDataChange=true. This will mean the filter will be out of date (ie a new value created after edit will be missing from the filter) and it is up to the application how it wishes for the filter to update. This is to handle some users having different requirements to the default handling, some of which are presented in the example below.

The example below shows different approaches on handling data changes for set filters. The first columns has no special handling, thus values in the set filter stay in sync automatically with the grids rows. All other rows have suppressSyncValuesAfterDataChange=true and demonstrate different application strategies for keeping the filter in sync. To understand the example it's best test one column at a time - once finished with that column, refresh the example and try another column and notice the difference. From the example, the following can be noted:

• All columns have set filter with different responses to data changing.
• All 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 and loaded with values for the grid's row data.
• Column 1 has no special handling of new values. Updates to column 1 will get reflected in the filter keeping the filter automatically in sync.
• Column 2 has suppressSyncValuesAfterDataChange=true and no special handling, so updates to column 2 will have no effect on the filter. The filter list will become stale.
• Column 3 has suppressSyncValuesAfterDataChange=true and after an update: a) gets the filter to update.
• Column 4 has suppressSyncValuesAfterDataChange=true and after an update: a) gets the filter to update and b) makes sure the new value is selected.
• Column 5 has suppressSyncValuesAfterDataChange=true and 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 2 and 3 will not have their filters updated. Column 1 will have it's filter updated by the grid. Columns 4 and 5 will have their filters updated by the application.

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

Set Filter Model

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

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:

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.
• applyModel(): Applies the model from the UI.

Is important to note that when updating the set filter through the API is up to the developer to call filterInstance.applyModel() and then gridOptions.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 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).

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.