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 two custom filters. The first is on the Athlete
column and demonstrates a filter with "fuzzy" matching and the second is on the Year
column with preset options.
Implementing a Filter Component
To configure custom filters, first enable the grid option reactiveCustomComponents
.
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.
To implement the filtering logic, a custom filter needs to implement the doesFilterPass
callback, and provide it to the useGridFilter
hook.
export default ({ model, onModelChange, getValue }) => {
const doesFilterPass = useCallback(({ node }) => {
// filtering logic
return getValue(node).contains(model);
}, [model]);
// register filter callbacks with the grid
useGridFilter({ doesFilterPass });
return (
<div>
<input
type="text"
value={model || ''}
onChange={({ target: { value }}) => onModelChange(value === '' ? null : value)}
/>
</div>
);
}
Enabling reactiveCustomComponents
affects all custom components. If you have custom components built in an imperative way instead of setting the reactiveCustomComponents
option, they may need to be rebuilt to take advantage of the new features that reactiveCustomComponents
offers. Using custom components built in an imperative way is now deprecated, and in AG Grid v32 the reactiveCustomComponents
option will be true
by default. See Migrating to Use reactiveCustomComponents. For the legacy imperative documentation, see Imperative Filter Component.
Custom Filter Parameters
Filter Props
The following props are passed to the custom filter components (CustomFilterProps
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
The following callbacks can be passed to the useGridFilter
hook (CustomFilterCallbacks
interface). The hook must be used for filters to work. The doesFilterPass
callback is mandatory, but all others are optional.
Associating Floating Filter
If you create your own filter you have two options to get floating filters working for that filter:
- You can create your own Custom Floating Filter.
- You can implement the
getModelAsString()
method in your custom filter. 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
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
AG Grid allows you to get a reference to the filter instances via api.getColumnFilterInstance(colKey)
. This returns a wrapper component that matches the provided grid filter components that implement IFilter
. 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.
// 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: