Filtering

You have two options for filtering, one is use on of the default built-in filters (easy but restricted to what's provided), or bake your own custom filters (no restrictions, build what you want, but takes more time).

This page discusses filtering outside of the context of paging. To see how to implement server side filtering, see the sections pagination and virtual paging

Enable Filtering

Turn filtering on for the grid by enabling filtering in the grid options. When on, each column header will have the filter menu icon appear when the mouse hovers over it. When clicked, a filter menu will appear. The menu will either contain a default provided filter, or your own custom built filter.

When a filter is active on a column, the filter icon appears before the column name in the header.

Default Built-In Filters

The following filter options can be set for a column definition:

Filter	Description
set	A set filter, influenced by how filters work in Microsoft Excel. Set filters can be provided with additional options through the filterParams attribute.
number	A number comparison filter. Functionality for matching on {equals, less than, greater than}.
text	A string comparison filter. Functionality for mating on {contains, starts with, ends with, equals}.

If no filter type is specified, the default 'set' filter is used.

Filter Parameters

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

columnDefinition = {
    headerName: "Athlete",
    field: "athlete",
    filter: 'set',
    filterParams: {cellRenderer: countryFilterCellRenderer, cellHeight: 20, values: ['A','B','C'], newRowsAction: 'keep'}
}

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

Set Filter Parameters

The filter parameters for set filter have the following meaning:

cellRenderer: Same as cell renderer for grid (you can use the same one in both locations). Setting it separatly here allows for the value to be rendered differently in the filter.
cellHeight: The height of the cell.
values: The values to display in the filter. If this is not set, then the filter will takes it's 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 dataset 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).

Text and Number Filter Parameters

The filter parameters for set filter have the following meaning:

newRowsAction: What to do when new rows are loaded. The default is to reset the filter, to keep it in line with 'set' filters. If you want to keep the selection, then set this value to 'keep'.
apply: Set to true to include an 'Apply' button with the filter and not filter automatically as the selection changes.

Quick Filter

In addition to the column specific filtering, a 'quick filter' (influenced by how filtering is done in Google GMail) can also be applied. Set the quick filter text into the grid options and tell the grid, via the API, to filter the data (which will include the new quick filter).

Built In Filters Example

The example below shows the three types of built in filters, as well as the quick filter, in action. 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.

Apply Function

If you want the user to hit an 'Apply' button before the filter is actioned, add apply=true to the filter parameters. The example below shows this in action for the first three columns.

This is handy if the filtering operation is taking a long time (usually it doesn't), or if doing server side filtering (thus preventing unnecessary calls to the server).

The example below also demonstrates the filter hook callbacks (see your browser dev console).

onFilterModified gets called when the filter changes regardless of the apply button.

onBeforeFilterChanged gets called before a new filter is applied.

onAfterFilterChanged gets called after a new filter is applied.

External Filtering

It is common for you to want to have widgets on the top of your grid that influence the grids filtering. External filtering allows you to mix your own 'outside of the grid' filtering with the grids filtering.

The example below shows external filters in action. There are two methods on gridOptions you need to implement: cbIsExternalFilterPresent() and cbDoesExternalFilterPass(node).

isExternalFilterPresent is called exactly once every time the grid senses a filter change. It should return true if external filtering is active, otherwise false. If you return true, then doesExternalFilterPass() will be called while filtering, otherwise doesExternalFilterPass() will not be called.
doesExternalFilterPass is called once for each row node in the grid. If you return false, the node will be excluded from the final set.

If the external filter changes, then you need to call api.onFilterChanged() to tell the grid

The example below shows the external filters in action.

Custom Column Filtering

If the filters provided don't provide what you want, then it's time to build your own filter class.

To provide a custom filter, instead of providing a string (eg set, text or number) for the filter in the column definition, provide a function. ag-Grid will call 'new' on this function and use the generated class as a filter. ag-Grid expects the filter class to have the following interface:


    // Class function.
    function MyCustomFilter() {}

    // mandatory methods
    MyCustomFilter.prototype.init = function (params) {}
    MyCustomFilter.prototype.getGui = function () {}
    MyCustomFilter.prototype.isFilterActive = function() {}
    MyCustomFilter.prototype.doesFilterPass = function (params) {}
    MyCustomFilter.prototype.getApi = function () {}

    // optional methods
    MyCustomFilter.prototype.afterGuiAttached = function(params) {}
    MyCustomFilter.prototype.onNewRowsLoaded = function () {}
    MyCustomFilter.prototype.onAnyFilterChanged = function () {}

Method	Description
init(params)	Init method called on the filter once after 'new' is called on the function. Takes one parameter with the following attributes: colDef: The col def this filter is for. rowModel: The internal row model inside ag-Grid. This should be treated as read only. If the filter needs to know which rows are a) in the table b) currently visible (ie not already filtered), c) what groups d) what order - all of this can be read from the rowModel. filterChangedCallback(): A function callback, to be called, when the filter changes, to inform the grid to filter the data. The grid will respond by filtering the data. filterModifiedCallback(): A function callback, to be optionally called, when the filter changes, but before 'Apply' is pressed. The grid does nothing except call gridOptions.filterModified(). valueGetter(node): A function callback, call with a node to be given the value for that filters column for that node. The callback takes care of selecting the right colDef and deciding whether to use valueGetter or field etc. doesRowPassOtherFilter(node): A function callback, call with a node to be told whether the node passes all filters except the current filter. This is useful if you want to only present to the user values that this filter can filter given the status of the other filters. The set filter uses this to remove from the list, items that are no longer available due to the state of other filters (like Excel type filtering). filterParams: The filter parameters, as provided in the column definition. context: The context for this grid. See section on Context $scope: If the grid options angularCompileFilters is set to true, then a new child scope is created for each column filter and provided here.
getGui	Returns the GUI for this filter. The GUI can be a) a string of html or b) a DOM element or node.
isFilterActive	This is used to show the filter icon in the header. If true, the filter icon will be shown.
doesFilterPass	The grid will ask each active filter, in turn, whether each row in the grid passes. If any filter fails, then the row will be excluded from the final set. The method is provided the value (the value to be checked), the row node, the row data and the filter model (for the filter, as provided by the 'get model' below - for now, the model can be ignored).
afterGuiAttached(params)	Gets called every time the popup is shown, after the gui returned in getGui is attached to the DOM. If the filter popup is closed and reopened, this method is called each time the filter is shown. This is useful for any logic that requires attachment before executing, such as putting focus on a particular DOM element. The params has one callback method 'hidePopup', which you can call at any later point to hide the popup - good if you have an 'Apply' button and you want to hide the popup after it is pressed.
onNewRowsLoaded	Gets called when new rows are inserted into the grid. If the filter needs to change it's state after rows are loaded, it can do it here.
getApi	Returns the API for the filter. Useful if you want your filter manipulated via an API. MyCustomFilter.prototype.getApi = function () { // mandatory method - called by api.getFilterModel() getModel: function() { // return how you want your model to look when someone // either calls getModel() directly on this filter, // or somoen calles 'getFilterModel' on the main api var model = {value: theFitler.value}; }, // mandatory method - called by api.setFilterModel(model) setModel: function(model) { // this will be passed the model that was returned in // get model. theFilter.value = model.value; }, // then add as many of your own methods that you want, // only you will be calling these. clearMyValues: function() { } }

Custom Filter Example

The example below shows a custom filter on the Athlete column.

Filter API

It is possible to set filters via the API. You do this by first getting an API to the filter in question (ie for a particular column) and then making calls on the filter API. Getting the API is done via the gridOptions api method getFilterApiForColDef(colDef).

Each column has it's own private filter and associated API. So if you want to change filters on more than one column, you have to call getFilterApiForColDef(colDef) for each column.

Each filter type has it's own API. So if it's a set filter, the filter API is specific to set filters. If it's a custom filter, it's up to you to provide the API. The below details the filter API for each of the built in filter types.

Set Filter API

The set filter API is as follows:

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
getModel() / setModel(): Gets the filter as a model, good for saving and restoring.

Number Filter API

The number filter API is as follows:

getType() / setType(type): Gets / Sets the type. Select from the provided constants on the API of EQUALS, LESS_THAN and GREATER_THAN
getFilter() / setFilter(filter): Gets / Sets the filter text (which should be a number).
getModel() / setModel(): Gets / Sets the filter as a model, good for saving and restoring.

Text Filter API

The text filter API is as follows:

getType() / setType(type): Gets / Sets the type. Select from the provided constants on the API of EQUALS, CONTAINS, STARTS_WITH and ENDS_WITH
getFilter() / setFilter(filter): Gets / Sets the filter text (a string).
getModel() / setModel(): Gets / Sets the filter as a model, good for saving and restoring.

Custom Filter API

You can provide any API methods you wish on your custom filters. There is only one resriction, you must implement the following if you want your filter to work with the gridOptions.api.setModel and gridOptions.api.getModel methods:

getModel() / setModel(): Gets / Sets the filter as a model, good for saving and restoring.

Example Filter API

The example below shows controlling the country and age filters via the API.

Get / Set All Filter Models

It is possible to get and set the state of all the filters via the api methods gridOptions.api.getFilterModel and gridOptions.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.