Core Features

Advanced Features

JavaScript Data GridExternal Filter

Version 36.2.0

External filtering allows custom filtering logic to be mixed with the grid's inbuilt filtering.

This form of filtering is only compatible with the Client-Side Row Model, see Row Models for more details.

Implementing External Filtering Copy Link

The example above shows external filters in action. Two methods on gridOptions are required to be implemented: isExternalFilterPresent and doesExternalFilterPass.

isExternalFilterPresentCopy Link
IsExternalFilterPresent
Grid calls this method to know if an external filter is present. Called exactly once every time the grid senses a filter change. Should return true if external filtering is active, otherwise false. If true, doesExternalFilterPass is called while filtering, otherwise it is not called. Supplying a new function reference re-runs external filtering.
doesExternalFilterPassCopy Link
DoesExternalFilterPass
Called once for each row node in the grid. Should return true if external filter passes, otherwise false. If false, the node is excluded from the final set. Only runs if isExternalFilterPresent returns true. Supplying a new function reference re-runs external filtering.

Re-running the External Filter Copy Link

The filter state is held outside the grid, so the grid has to be told when that state has changed. Pick one of the following approaches:

  • Calling onFilterChanged - the callback references are kept stable and the filter is re-run only when the API is called.
  • Supplying New Callbacks - a new callback reference is handed to the grid and the filter is re-run automatically.

Calling onFilterChanged Copy Link

After the filter state has changed call api.onFilterChanged() to ask the grid to run filtering again.

onFilterChangedCopy Link
FilterChangedEventSourceType
Informs the grid that a filter has changed. This is typically called after a filter change through one of the filter APIs. source: The source of the filter change event. If not specified defaults to 'api'.
// Filter state updated now re-run filtering
api.onFilterChanged();

Ensure the callbacks have stable references to avoid triggering filtering excessively.

Supplying New Callbacks Copy Link

isExternalFilterPresent and doesExternalFilterPass are reactive grid properties, so replacing either one with a new function re-runs filtering automatically.

api.setGridOption('doesExternalFilterPass', (node) => node.data.age > 50);

The example on this page takes the first path: the callbacks are stable, and each change to the filter state calls api.onFilterChanged().