Expand All

  Getting Started

  Reference

  Features

  Row Models

  Themes

  Components

  Examples

  Third Party

Misc

Github stars make projects look great. Please help, donate a star, it's free.
Read about ag-Grid's Partnership with webpack.
Get informed on releases and other ag-Grid news only - never spam.
Follow on Twitter

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 GUI 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 getModelAsString() and 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

To provide a custom floating filter you have to provide it either through the column definition property floatingFilterComponent if using plain JS, or via floatingFilterComponentFramework if you are using a framework (such as React or Angular).

For plain JS (floatingFilterComponent) it needs to be provided in the form of a function. ag-Grid will call 'new' on this function and treat the generated class instance as a floating filter component. A floating filter component class can be any function /class that implements the following interface:

interface IFloatingFilterComp { // mandatory methods // The init(params) method is called on the floating filter once. See below for details on the parameters. init(params: IFilterFloatingParams): void; <span class="codeComment">// This is a method that ag-Grid will call every time the model from the associated rich filter // for this floating filter changes. Typically this would be used so that you can refresh your UI and show // on it a visual representation of the latest model for the filter as it is being updated somewhere else.</span> onParentModelChanged(parentModel:any) // Returns the dom html element for this floating filter. getGui(): HTMLElement; // optional methods <span class="codeComment">// Gets called when the floating filter is destroyed. // Like column headers, the floating filter life span is only when the column is visible, // so gets destroyed if column is made not visible or when user scrolls column out of // view with horizontal scrolling.</span> destroy?(): void; }

IFloatingFilterParams

The method 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.

interface IFloatingFilterParams { // The column this filter is for column: Column; <span class="codeComment">// This is the callback you need to invoke from your component every time that you want // to update the model from your parent rich filter. In order to make this call you need to be able to produce a // model object like the one this rich filter will produce through getModel(). After this call is completed, // the parent rich filter will be updated and the data on the grid filtered accordingly if applyButton=false.</span> onFloatingFilterChanged(change:any): void; // This is a shortcut to invoke getModel on the parent rich filter.. currentParentModel(): any; <span class="codeComment">// Boolean flag to indicate if the button in the floating filter that opens the rich // filter in a popup should be displayed</span> suppressFilterButton: boolean; // Amount in ms to debounce key presses before the filter is fired defaults to 500 debounceMs?:number; // The grid API api: any; }

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:

  1. The columns with the floating filter are using the standard number filter as the base filter
  2. Since the parent filter is the number filter, the floating filter methods onFloatingFilterChanged(parentModel), and currentParentModel():parentModel take and receive model objects that correspond to the model for the number filter
  3. 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 suppressFilterButton:true in the floatingFilterComponentParams and suppressMenu:true in the colDef
  4. floatingFilterParams for 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:

  1. NumberFilter getModel() returns a Number representing the current greater than filter than.
  2. NumberFilter 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
  3. NumberFloatingFilter onParentModelChanged(parentModel). Receives the product of NumberFilter.getModel every time that the NumberFilter model changes
  4. NumberFloatingFilter calls on params.onFloatingFilterChanged(modelToAccept) every time the user changes the slider value. This will cause an automatic call into NumberFilter.setModel(modelToAccept)
  5. 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 method Filter.getModelAsString() and you will get for free a read-only floating filter.

This example uses the previous custom filter implementing method NumberFilter.getModelAsString(). Note 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 rich filter

Complex example with JQuery

The following example illustrates a complex scenario where all columns have ag-Grid floating filters, except for the columns: gold, silver, bronze and total, that have custom filter and custom floating filters that use jquery sliders

Note that:

  • Athlete has a debounce of 2secs debounceMs:2000
  • Age has no debounce debounceMs:0
  • All the other columns have the standard 500ms debounce

Angular Floating Filters

This section explains how to utilise ag-Grid floatingFilter using Angular 2+. You should read about how Floating filter works in ag-Grid first before trying to understand this section.

See example below on how to create a custom floating filter reusing the out of the box number filter with angular

The full ag-grid-angular-example repo shows many more examples for rendering, including grouped rows, full width renderer's and so on, as well as examples on using Angular Components with both Cell Editors and Filters