Framework:Javascript Data GridAngular Data GridReact Data GridVue Data Grid

JavaScript Data Grid: Provided Filters

This section describes the functionality common to all filters that are provided by the grid.

The grid provides four filters out of the box: three Simple Filters (Text, Number and Date), and an advanced Set Filter which is available in the Enterprise version of the grid.

Follow the links below to learn more about each specific filter:

The rest of this section will cover concepts that are common to every provided filter.

Structure of Provided Filters

The diagram below outlines the structure of the filters. Each box represents a filter type with the functions listed in it. For example, all provided filters have button logic, but only the Date filter has a Date Comparator or a Date Picker.

Provided Filters

Provided Filter UI

Each provided filter is displayed in a UI with optional buttons at the bottom.

Filter Content

Provided Filter Params

All the provided filters have the following parameters:

buttons
FilterButtonType[]
Specifies the buttons to be shown in the filter, in the order they should be displayed in. The options are:
  • 'apply': If the Apply button is present, the filter is only applied after the user hits the Apply button.
  • 'clear': The Clear button will clear the (form) details of the filter without removing any active filters on the column.
  • 'reset': The Reset button will clear the details of the filter and any active filters on that column.
  • 'cancel': The Cancel button will discard any changes that have been made to the filter in the UI, restoring the applied model.
  • buttons: FilterButtonType[];
    
    type FilterButtonType = 
          'apply' 
        | 'clear' 
        | 'reset' 
        | 'cancel'
    
    closeOnApply
    boolean
    If the Apply button is present, the filter popup will be closed immediately when the Apply or Reset button is clicked if this is set to true.
    Default: false
    debounceMs
    number
    Overrides the default debounce time in milliseconds for the filter. Defaults are:
  • TextFilter and NumberFilter: 500ms. (These filters have text field inputs, so a short delay before the input is formatted and the filtering applied is usually appropriate).
  • DateFilter and SetFilter: 0ms
  • readOnly
    boolean
    If set to true, disables controls in the filter to mutate its state. Normally this would be used in conjunction with the Filter API. See Read-only Filter UI.
    Default: false

    Provided Filter API

    Provided Filters provide the following methods:

    applyModel
    Function
    Applies the model shown in the UI (so that getModel() will now return what was in the UI when applyModel() was called).
    applyModel = () => boolean;
    getModelFromUi
    Function
    Returns the filter model from the UI. If changes have been made to the UI but not yet applied, this model will reflect those changes.
    getModelFromUi = () => any;
    isFilterActive
    Function
    Returns true if the filter is currently active, otherwise false. If active then 1) the grid will show the filter icon in the column header and 2) the filter will be included in the filtering of the data.
    isFilterActive = () => boolean;
    getModel
    Function
    Returns a model representing the current state of the filter, or null if the filter is not active. The grid calls getModel() on all active filters when gridApi.getFilterModel() is called.
    getModel = () => any;
    setModel
    Function
    Sets the state of the filter using the supplied model. Providing null as the model will de-activate the filter.
    setModel = (model: any) => void | AgPromise<void>;

    Apply, Clear, Reset and Cancel Buttons

    Each of the provided filters can optionally include Apply, Clear, Reset and Cancel buttons.

    When the Apply button is used, the filter is only applied once the Apply button is pressed. This is useful if the filtering operation will take a long time because the dataset is large, or if using server-side filtering (thus preventing unnecessary calls to the server).

    The Clear button clears just the filter UI, whereas the Reset button clears the filter UI and removes any active filters for that column.

    The Cancel button will discard any changes that have been made in the UI, restoring the state of the filter to match the applied model.

    The buttons will be displayed in the order they are specified in the buttons array.

    The example below demonstrates using the different buttons. It also demonstrates the relationship between the buttons and filter events. Note the following:

    • The Athlete and Age columns have filters with Apply and Reset buttons, but different orders.
    • The Country column has a filter with Apply and Clear buttons.
    • The Year column has a filter with Apply and Cancel buttons.
    • The Age and Year columns have closeOnApply set to true, so the filter popup will be closed immediately when the filter is applied, reset or cancelled.
    • onFilterOpened is called when the filter is opened.
    • onFilterModified is called when the filter changes regardless of whether the Apply button is present.
    • onFilterChanged is called only after a new filter is applied.
    • Looking at the console, it can be noted when a filter is changed, the result of getModel() and getModelFromUi() are different. The first reflects the active filter, while the second reflects what is in the UI (and not yet applied).

    Applying the UI Model

    Provided filters maintain a separate model representing what is shown in the UI, which might change without having yet been applied, for example when an Apply button is present and the user has made changes in the UI but not yet clicked Apply. Calling getModelFromUi() will always return a model representing the current UI, whereas getModel() will return the applied model that is currently being used for filtering.

    If any changes are made in the UI when the Apply button is active, or via other API methods whether the Apply button is active or not, you must call filterInstance.applyModel() if you want to ensure the UI is applied.

    Applying the model is then typically followed by calling gridApi.onFilterChanged() to tell the grid to re-run the filtering.

    // Get a reference to the 'name' filter instance
    const filterInstance = gridOptions.api.getFilterInstance('name'); 
    
    // Apply the model to ensure any changes in the UI or via API methods are recognised
    filterInstance.applyModel();
    
    // Tell grid to run filter operation again
    gridOptions.api.onFilterChanged();

    If no call is made to filterInstance.applyModel() then the filter UI will show any changes that have been made, but they won't be reflected in the filter model and therefore won't be reflected in the filtering. This will appear as if the user never hit the Apply button (regardless of whether the Apply button is active or not).