React 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.

Custom filter components are controlled components, which receive a filter model as part of the props, and 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.

export default ({ model, onModelChange, getValue }) => {
    return (
        <div>
            <input
                type="text"
                value={model || ''}
                onChange={({ target: { value }}) => onModelChange(value === '' ? null : value)}
            />
        </div>
    );
}

Custom Filter Parameters Copy Link

Filter Props Copy Link

The following props are passed to the custom filter components (CustomFilterDisplayProps interface). If custom props are provided via the colDef.filterParams property, these will be additionally added to the props object, overriding items of the same name if a name clash exists.

Filter Callbacks Copy Link

The following callbacks can be passed to the useGridFilterDisplay hook (CustomFilterDisplayCallbacks interface). All the callbacks are optional. The hook only needs to be used if callbacks are provided.

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

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

<AgGridReact columnDefs={columnDefs} />

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

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

<AgGridReact columnDefs={columnDefs} />

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 api.getColumnFilterInstance(colKey). This returns a wrapper component that matches the provided grid filter components that implement FilterDisplay. To get the React custom filter component, the helper function getInstance can be used with this. As React components are created asynchronously, it is necessary to use a callback for both methods.

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

// let's assume a React component as follows
export default forwardRef((props, ref) => {
    useImperativeHandle(ref, () => {
        return {
            ... // required filter methods

            // put a custom method on the filter
            myMethod() {
                // does something
            }
        }
    });

    ... // rest of component
}

// later in your app, if you want to execute myMethod()...
laterOnInYourApplicationSomewhere() {
    // get reference to the AG Grid Filter component on name column
    api.getColumnFilterInstance('name').then(filterInstance => {
        getInstance(filterInstance, comp => if (comp != null) {
            comp.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.