Vue Data GridFilter Component

Filter components allow you to add your own filter types to AG Grid. Use them when the Provided Filters do not meet your requirements.

The example below shows a custom filter on the Athlete column with "fuzzy" matching.

Implementing a Filter Component Copy Link

To configure custom filters, first enable the grid option enableFilterHandlers.

Implementing a custom filter requires two parts:

• The custom filter component which will be displayed to the user.
• The the logic to run the filter.

The custom filter component receives a filter model as part of the params (which is updated when the refresh method is called). When the model is changed via the UI, it should pass model updates back to the grid via the onModelChange callback.

A filter model of null means that no filter is applied (the filter displays as inactive). Note that the filter is applied immediately when onModelChange is called. This behaviour can be changed by Using Buttons.

interface FilterDisplay {
    // Optional methods

    // Gets called when new rows are inserted into the grid. If the filter needs to change its
    // state after rows are loaded, it can do it here. For example the set filters uses this
    // to update the list of available values to select from (e.g. 'Ireland', 'UK' etc for
    // Country filter). To get the list of available values from within this method from the
    // Client Side Row Model, use gridApi.forEachLeafNode(callback)
    onNewRowsLoaded?(): void;

    // Called whenever any filter is changed.
    onAnyFilterChanged?(): void;

    // When defined, this method is called whenever the parameters provided in colDef.filterParams
    // change. The result returned by this method will determine if the filter should be 
    // refreshed and reused, or if a new filter instance should be created.
    // 
    // When true is returned, the existing filter instance should be refreshed and reused instead
    // of being destroyed. This is useful if the new params passed are compatible with the
    // existing filter instance. When false is returned, the existing filter will be destroyed 
    // and a new filter instance will be created. This should be done if you do not wish to reuse
    // the existing filter instance.
    // 
    // When this method is not provided, the default behaviour is to destroy and recreate the
    // filter instance everytime colDef.filterParams changes.
    refresh?(newParams: FilterDisplayParams): boolean;

    // Gets called when the column is destroyed. If your custom filter needs to do
    // any resource cleaning up, do it here. A filter is NOT destroyed when it is
    // made 'not visible', as the GUI is kept to be shown again if the user selects
    // that filter again. The filter is destroyed when the column it is associated with is
    // destroyed, either when new columns are set into the grid, or the grid itself is destroyed.
    destroy?(): void;

    // 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 re-opened, 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 a
    // 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.
    afterGuiAttached?(params?: IAfterGuiAttachedParams): void;

    // Gets called every time the popup is hidden, after the GUI returned in getGui is detached
    // from the DOM. If the filter popup is closed and re-opened, this method is called each time
    // the filter is hidden. This is useful for any logic to reset the UI state back to the model
    // before the component is reopened.
    afterGuiDetached?(): void;
}

Custom Filter Parameters Copy Link

When a Vue component is instantiated the grid will make the grid APIs, a number of utility methods as well as the cell and row values available to you via this.params - the interface for which is provided is documented below.

If custom params are provided via the colDef.filterParams property, these will be additionally added to the params object, overriding items of the same name if a name clash exists.

Filter Logic Copy Link

The logic to run the filter can be provided in one of two ways:

• As a doesFilterPass callback for simple filter cases.
• As a filter handler object for more complex filter cases.

The logic is passed via the filter property along with the custom component as a ColumnFilter object.

doesFilterPass Callback Copy Link

<ag-grid-vue
    :columnDefs="columnDefs"
    /* other grid options ... */>
</ag-grid-vue>

this.columnDefs = [
    {
        field: 'year',
        filter: {
            component: YearFilter, // custom filter component
            doesFilterPass: (params) => {
                // evaluate filter for row here
                return model === params.handlerParams.getValue(params.node);
            },
        },
    }
];

The callback doesFilterPass(params) will be called for each row when filtering is performed (and the filter is active), and takes the following as a parameter:

Filter Handler Copy Link

<ag-grid-vue
    :columnDefs="columnDefs"
    /* other grid options ... */>
</ag-grid-vue>

this.columnDefs = [
    {
        field: 'year',
        filter: {
            component: YearFilter, // custom filter component
            handler: (params) => ({
                doesFilterPass: (params) => {
                    // evaluate filter for row here
                    return passes;
                },
                // other handler methods
            }),
        },
    }
];

The filter handler function should return a FilterHandler which will be created when the filter is active. The doesFilterPass method on the evaluator will be called for each row when filtering is performed (and the filter is active).

The filter handler is useful for when the filter model needs parsing to allow for fast comparison of values. The handler is passed the latest filter model via the init / refresh methods, which can then process the model before doesFilterPass is called.

Using Buttons Copy Link

It is possible to use the Filter Buttons for grid-provided filters with custom filter components.

The example above demonstrates using filters with buttons via the same custom filter component:

• The Year Default column does not use buttons.
• The Year Apply column uses the apply button, and additionally closes the filter popup on apply.
• The Year Reset column uses the reset button, which will set the filter back to the default model and apply it.

The buttons are configured by passing additional parameters to the filter (interface FilterWrapperParams).

When the buttons are pressed, the custom filter state parameter will be updated via the refresh(params) method, with state.model being the model that should be displayed in the filter.

With the Apply button present, the filter component no longer needs to call onModelChange as the grid will apply the model when the button is clicked (although it can still be called if the component wants to apply a model in some other way). Instead, the filter component will call onStateChange with the model that is currently displayed in the filter component. This is the model that the grid will apply when the button is clicked. If the filter is being used without buttons, it can also call onAction('apply') to apply the model set via the state.

Associating Floating Filter Copy Link

If you create your own filter you have two options to get floating filters working for that filter:

1. You can create your own Custom Floating Filter.
2. You can implement the getModelAsString() method on your filter evaluator. If you implement this method and don't provide a custom floating filter, AG Grid will automatically provide a read-only version of a floating filter. See Custom Filter And Read-Only Floating Filter.

If you don't provide either of these two options for your custom filter, the display area for the floating filter will be empty.

Custom Filters Containing a Popup Element Copy Link

Sometimes you will need to create custom components for your filters that also contain popup elements. This is the case for Date Filter as it pops up a Date Picker. If the library you use anchors the popup element outside of the parent filter, then when you click on it the grid will think you clicked outside of the filter and hence close the column menu.

There are two ways you can get fix this problem:

• Add a mouse click listener to your floating element and set it to preventDefault(). This way, the click event will not bubble up to the grid. This is the best solution, but you can only do this if you are writing the component yourself.
• Add the ag-custom-component-popup CSS class to your floating element. An example of this usage can be found here: Custom Date Component

Accessing the Component Instance Copy Link

AG Grid allows you to get a reference to the filter component instances via the api.getColumnFilterInstance(colKey) method.

Similarly, you can get a reference to the filter evaluator via api.getColumnFilterEvaluator(colKey).

// let's assume a VueJS component as follows
export default {
    template: `<input style="height: 20px" :ref="'input'" v-model="text">`,
    data() {
        ...data
    },
    methods: {
        myMethod() {
            // does something
        },
        ...other methods
    },

    // later in your app, if you want to execute myMethod()...
    laterOnInYourApplicationSomewhere() {
        // assume filter on name column
        api.getColumnFilterInstance('name').then(filterInstance => {
            filterInstance.myMethod();
        });
    }

The example below illustrates how a custom filter component can be accessed and methods on it invoked. If you click on the Invoke Filter Instance Method button, it will invoke the instance componentMethod, which logs to the developer console.

Next Up Copy Link

Continue to the next section to learn about Floating Filters.