Set Filter

A set filter, influenced by how filters work in Microsoft Excel. Set filters can be provided with additional options through the filterParams attribute.

Set Filter Parameters

An additional attribute on the column definition, filterParams, can be used to provide extra information to the set filter. Set the filterParams on the columnDefinition as follows:

The set filter params are specific to each filter and have the following meanings:

• 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.
• cellHeight: The height of the cell.
• 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).
• newRowsAction: What to do when new rows are loaded. The default is to reset the filter, as the set of values to select from can have changed. If you want to keep the selection, then set this value to 'keep'. This can be useful if you are using values (above) or otherwise know that the list to select from will not change. If the list does change, then it can be confusing what to do with new values into the set (should they be selected or not??).
• apply: Set to true to include an 'Apply' button with the filter and not filter automatically as the selection changes.
• 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.
• 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
• debounceMs: If specified, the filter will wait this amount of ms after the user stops selecting optoins in the mini filter before is triggered. If not specified there won't be any debounce.

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

The set filter does NOT refresh after you edit the data. 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 hand 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'.

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.

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.

Floating Set Filter

If your grid has floatingFilter enabled, your columns with set filter will automatically show below the header a new column that will show two elements:

• Filter input box: It reflects any change made to the set filtering from anywhere within the application. This includes changes on the rich filter for this column made by the user directly or changes made to the filter through a call to setModel or the API to this filter component
• Filter button: This button is a shortcut to show the rich filter editor

Common Column Filtering Functionality And Examples

The following can be found in the column filtering documentation page

• Common filtering params
• Enabling/Disabling filtering in a column
• Enabling/Disabling floating filter
• Adding apply and clear button to a column filter
• Filtering animation
• Examples