Floating Filter Component
Floating Filter components allow you to add your own floating filter types to ag-Grid. Use this:
- When the provided floating filter for a provided filter does not meet your requirements and you want to replace with one of your own.
- When you have a custom filter and want to provide a floating filter for your custom filter.
This page focuses on writing your own floating filters components. To see general information about floating filters in ag-Grid see floating filters.
Floating Filter LifeCycle
Floating filters do not contain filter state, they merely show the state of the actual underlying filter. Floating filters are just another view for the main filter. For this reason the floating filters lifecycle is bound to the visibility of the column. So if you hide a column (either set not visible, or horizontally scroll the column out of view) then the floating filter UI component is destroyed. If the column comes back into view, it is created again. This is different to column filters, where the column filter will exist as long as the column exists, regardless of the columns visibility.
For details on how the floating filter interacts with its associated column filter,
see the methods
onFloatingFilterChanged(change) in the
filter component interface.
To see examples of the different ways to implement floating filters please refer to the examples below.
Floating Filter Interface
init(params) takes a params object with the items listed below. If the user provides
params via the
colDef.floatingFilterComponentParams attribute, these will be additionally added to the
params object, overriding items of the same name if a name clash exists.
Floating Filter Methods on Provided Filters
When the user interacts with a floating filter, the floating filter must set the state of the main parent filter in order for filter changes to take effect. This is done by the floating filter getting a reference to the parent filter instance and calling a method on it.
If you create your own filter and floating filter, it is up to you what method you expose on the filter for the floating filter to call. This contract is between the filter and the floating filter and doesn't go through the grid.
The simple provided filters (text, string, date) provide the following methods that the corresponding provided floating filters then call. This information is useful if a) you want to create your own floating filter that is paired with a provided parent filter or b) you are just interested to know how the interaction works to help build your own filters and floating filters.
Date, Text and Number Filters: All these filters provide a method
onFloatingFilterChanged(type: string, value: string)where type is the type ('lessThan', 'equals' etc) and the value is the text value to use (the number and date filters will convert the text to the corresponding type).
- Set Filter: The floating set filter is not editable, thus no method is exposed on the parent filter for the floating filter to call.
You could also call
setModel() on the filters as an alternative. For
example you could build your own floating filter for the Set Filter that allows
picking all European or Asian countries, or you could provide your own Number floating
filter that allows selecting ranges (the provided Number floating filter does not
allow editing ranges).
Custom Floating Filter Example
In the following example you can see how the columns Gold, Silver, Bronze and Total have a custom floating filter NumberFloatingFilter. This filter substitutes the standard floating filter for a input box that the user can change to adjust how many medals of each column to filter by based on a greater than filter.
Since this example its using standard filters, the object that needs to be passed
to the method
onParentFilterChanged() needs to provide two properties:
- apply: Ignored unless
applyButton=true. If true the filter is changed AND applied, if it is false, is only changed.
- model: The model object that represents the new filter state.
If the user removes the content of the input box, the filter its removed.
Note that in this example:
- The columns with the floating filter are using the standard number filter as the base filter
- Since the parent filter is the number filter, the floating filter methods
currentParentModel():parentModeltake and receive model objects that correspond to the model for the number filter
- Since this floating filters are providing a subset of the functionality of their parent filter, which can
filter for other conditions which are not 'greaterThan' the user is prevented to see the parent filter by adding
floatingFilterParamsfor all the medal columns have an additional param that is used to customise the font color of the floating filter input text box
Custom Filter And Custom Floating Filter Example
This example extends the previous example by also providing its own Custom filter NumberFilter in the gold, silver, bronze and total columns which now its accessible though the column menu. In this example is important to note that:
getModel()returns a Number representing the current greater than filter than.
setModel(model)takes an object that can be of ay type. If the value passed is numeric then the filter gets applied with a condition of greater than
onParentModelChanged(parentModel). Receives the product of
NumberFilter.getModelevery time that the NumberFilter model changes
- NumberFloatingFilter calls on
params.onFloatingFilterChanged(modelToAccept)every time the user changes the slider value. This will cause an automatic call into
- Since NumberFilter
onFloatingFilterChanged(change)IS NOT implemented. Every time the user changes the input value the filter gets updated automatically. If this method was implemented it would get call it every time the floating filter would change, and it would delegate to it the responsibility to perform the filtering.
Custom Filter And Read-Only Floating Filter Example
If you want to provide only a custom filter but don't want to provide a custom floating filter, you can implement the
Filter.getModelAsString() and you will get for free a read-only floating filter.
This example uses the previous custom filter implementing method
how there are no custom floating filters and yet each column using NumberFilter (gold, silver, bronze and total),
have a read-only floating filter that gets updated as you change the values from their parent filter
Complex example with JQuery
The following example illustrates a complex scenario. All the columns have floating filters. The first 6 columns (Athlete to Sport) have the standard provided floating filters. The last 4 (Gold to Total) have custom filters and custom floating filters that use jQuery sliders.
- Athlete has a debounce of 2secs
- Age has no debounce
- All the other columns have the standard 500ms debounce
Angular Floating Filters
It is possible to provide Angular floating filter for ag-Grid to use if you are are using the Angular version of ag-Grid. See registering framework components for how to register framework components.
The below example show how to create a custom floating filter reusing the out of the box number filter with Angular.
React Floating Filters
It is possible to provide React floating filter for ag-Grid to use if you are are using the React version of ag-Grid. See registering framework components for how to register framework components.
The below example show how to create a custom floating filter reusing the out of the box number filter with React.
Vue Floating Filters
It is possible to provide a Vue floating filter for ag-Grid to use if you are are using the Vue version of ag-Grid. See registering framework components for how to register framework components.
The below example show how to create a custom floating filter reusing the out of the box number filter with Vue.