---
product: "AG Grid"
title: "Filter Component"
description: "Filter components allow you to add your own filter types to AG Grid. Use them when the Provided Filters do not meet your requirements."
framework: javascript
version: "36.2.0"
related:
    - title: "Overview"
      url: "https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/filtering-overview/"
    - title: "Column Filters"
      url: "https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/filtering/"
    - title: "Floating Filters"
      url: "https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/floating-filters/"
    - title: "Custom Floating Filters"
      url: "https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/component-floating-filter/"
    - title: "Advanced Filter"
      url: "https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/filter-advanced/"
    - title: "External Filter"
      url: "https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/filter-external/"
    - title: "Quick Filter"
      url: "https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/filter-quick/"
llms: "https://www.ag-grid.com/archive/36.2.0/llms.txt"
---

# Filter 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.

#### Custom Filter Component

```ts
import {
  ClientSideRowModelModule,
  ColDef,
  CustomFilterModule,
  DoesFilterPassParams,
  GridApi,
  GridOptions,
  ModuleRegistry,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import { PersonFilter } from "./personFilter";
import { IOlympicData } from "./interfaces";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableDevValidations();
}

ModuleRegistry.registerModules([CustomFilterModule, ClientSideRowModelModule]);

function doesFilterPass({
  model,
  node,
  handlerParams,
}: DoesFilterPassParams<any, any, string>): boolean {
  // make sure each word passes separately, ie search for firstname, lastname
  let passed = true;
  model
    .toLowerCase()
    .split(" ")
    .forEach((filterWord) => {
      const value = handlerParams.getValue(node);
      if (value.toString().toLowerCase().indexOf(filterWord) < 0) {
        passed = false;
      }
    });

  return passed;
}

const columnDefs: ColDef[] = [
  {
    field: "athlete",
    minWidth: 150,
    filter: { component: PersonFilter, doesFilterPass: doesFilterPass },
  },
  { field: "country", minWidth: 150 },
  { field: "sport" },
  { field: "year", minWidth: 130 },
  { field: "gold" },
  { field: "silver" },
  { field: "bronze" },
  { field: "total" },
];

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  defaultColDef: {
    flex: 1,
    minWidth: 100,
  },
  columnDefs: columnDefs,
  enableFilterHandlers: true,
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data) => {
    gridApi!.setGridOption("rowData", data);
  });
```

[Live example: Custom Filter Component](https://www.ag-grid.com/archive/36.2.0/examples/component-filter/custom-filter/typescript/)

## Implementing a Filter Component

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

> **Note**
>
> If you do not enable the grid option `enableFilterHandlers`, it is still possible to use custom filters, however this will involve embedding your filter logic into the custom component, and is not recommended. See [Legacy Filter Component](https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/component-filter-legacy/).

Implementing a custom filter requires two parts:

- The custom filter component which will be displayed to the user.
- 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](https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/component-filter/#using-buttons).

Custom filter components implement the `FilterDisplayComp` interface. The `getGui()` method returns the filter's DOM element, and `refresh(params)` is called when the filter parameters change. Return `false` from `refresh` to have the grid destroy and recreate the filter; otherwise the existing filter is reused.

Full details of the `FilterDisplayComp` interface are listed below under [API Reference](https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/component-filter/#api-reference).

## Custom Filter Parameters

The `init(params)` method takes a params object with the items listed 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.

Properties available on the `FilterDisplayParams&lt;TData = any, TContext = any, TModel = any, TState = any&gt;` interface.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model` | `TModel \| null` |  |  |  |
| `state` | `FilterDisplayState<TModel, TState>` |  |  |  |
| `onModelChange` | `Function` |  |  |  |
| `onStateChange` | `Function` |  |  |  |
| `onAction` | `Function` |  |  |  |
| `onUiChange` | `Function` |  |  |  |
| `getHandler` | `Function` |  |  |  |
| `source` | `FilterDisplaySource` |  |  |  |
| `additionalEventAttributes` | `any` |  |  |  |
| `column` | `Column` |  |  |  |
| `colDef` | `ColDef` |  |  |  |
| `getValue` | `Function` |  |  |  |
| `doesRowPassOtherFilter` | `Function` |  |  |  |
| `api` | `GridApi` |  |  |  |
| `context` | `TContext` |  |  |  |

## Filter Logic

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.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `component` | `any` |  |  |  |
| `doesFilterPass` | `Function` |  |  |  |
| `handler` | `string \| CreateFilterHandlerFunc<TData, TValue, TContext, TModel, TCustomParams>` |  |  |  |

> **Note**
>
> The filter logic is only used with the [Client-Side Row Model](https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/row-models/). If being used exclusively with other row models, it does not need to be provided as the filtering logic is performed on the server. If a handler is provided, it will still be instantiated, but `doesFilterPass` will not be called.

### doesFilterPass Callback

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

    // other grid options ...
}
```

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:

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model` | `TModel` |  |  |  |
| `handlerParams` | `FilterHandlerBaseParams<TData, TContext, TModel, TCustomParams>` |  |  |  |
| `node` | `IRowNode` |  |  |  |
| `data` | `TData` |  |  |  |

### Filter Handler

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

    // other grid options ...
}
```

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.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `init` | `Function` |  |  |  |
| `refresh` | `Function` |  |  |  |
| `doesFilterPass` | `Function` |  |  |  |
| `getModelAsString` | `Function` |  |  |  |
| `processModelToApply` | `Function` |  |  |  |
| `destroy` | `Function` |  |  |  |
| `onNewRowsLoaded` | `Function` |  |  |  |
| `onAnyFilterChanged` | `Function` |  |  |  |

It is also possible to define filter handlers in the `filterHandlers` grid option, and then refer to them by the string key in the column definition.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `filterHandlers` | `FilterHandlers` |  |  |  |

## Using Buttons

It is possible to use the [Filter Buttons](https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/filter-applying/) for grid-provided filters with custom filter components.

#### Filter Buttons

```ts
import {
  ClientSideRowModelModule,
  ColDef,
  CustomFilterModule,
  DoesFilterPassParams,
  GridApi,
  GridOptions,
  ModuleRegistry,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import { YearFilter } from "./yearFilter";
import { IOlympicData } from "./interfaces";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableDevValidations();
}

ModuleRegistry.registerModules([CustomFilterModule, ClientSideRowModelModule]);

function doesFilterPass({
  model,
  node,
  handlerParams,
}: DoesFilterPassParams<any, any, boolean>): boolean {
  return model ? handlerParams.getValue(node) > 2010 : true;
}

const columnDefs: ColDef[] = [
  {
    field: "athlete",
    minWidth: 150,
  },
  {
    field: "year",
    headerName: "Year Default",
    minWidth: 130,
    filter: { component: YearFilter, doesFilterPass: doesFilterPass },
  },
  {
    field: "year",
    headerName: "Year Apply",
    minWidth: 130,
    filter: { component: YearFilter, doesFilterPass: doesFilterPass },
    filterParams: {
      useForm: true,
      buttons: ["apply"],
      closeOnApply: true,
    },
  },
  {
    field: "year",
    headerName: "Year Reset",
    minWidth: 130,
    filter: { component: YearFilter, doesFilterPass: doesFilterPass },
    filterParams: {
      buttons: ["reset"],
    },
  },
  { field: "sport" },
];

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  defaultColDef: {
    flex: 1,
    minWidth: 100,
  },
  columnDefs: columnDefs,
  enableFilterHandlers: true,
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data) => {
    gridApi!.setGridOption("rowData", data);
  });
```

[Live example: Filter Buttons](https://www.ag-grid.com/archive/36.2.0/examples/component-filter/custom-filter-buttons/typescript/)

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`).

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `buttons` | `FilterAction[]` |  |  |  |
| `closeOnApply` | `boolean` |  |  |  |

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(model)` 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({ model })` 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

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](https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/component-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](https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/component-floating-filter/#example-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](https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/filter-date/#custom-selection-component)

## Using Custom Filters with Grid-Provided Filter Logic

It is possible to use the grid-provided filter logic with custom filter components.

```js
const gridOptions = {
    columnDefs: [
        {
            field: 'year',
            filter: {
                component: YearFilter, // custom filter component
                handler: 'agNumberColumnFilterHandler', // grid-provided Number Filter handler
            },
        }
    ],

    // other grid options ...
}
```

The grid-provided handlers are:

- `'agTextColumnFilterHandler'` - [Text Filter](https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/filter-text/) handler.
- `'agNumberColumnFilterHandler'` - [Number Filter](https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/filter-number/) handler.
- `'agBigIntColumnFilterHandler'` - [BigInt Filter](https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/filter-bigint/) handler.
- `'agDateColumnFilterHandler'` - [Date Filter](https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/filter-date/) handler.

> **Note**
>
> [Set Filter](https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/filter-set/) and [Multi Filter](https://www.ag-grid.com/archive/36.2.0/javascript-data-grid/filter-multi/) are not supported when using custom filters with grid-provided filter logic.

The example below demonstrates using the Number Filter handler with a custom filter component:

#### Use Grid Handlers

```ts
import {
  ClientSideRowModelModule,
  ColDef,
  CustomFilterModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  NumberFilterModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import { YearFilter } from "./yearFilter";
import { IOlympicData } from "./interfaces";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableDevValidations();
}

ModuleRegistry.registerModules([
  CustomFilterModule,
  NumberFilterModule,
  ClientSideRowModelModule,
]);

const columnDefs: ColDef[] = [
  {
    field: "athlete",
    minWidth: 150,
  },
  {
    field: "year",
    headerName: "Year Default",
    minWidth: 130,
    filter: { component: YearFilter, handler: "agNumberColumnFilterHandler" },
  },
  {
    field: "year",
    headerName: "Year Apply",
    minWidth: 130,
    filter: { component: YearFilter, handler: "agNumberColumnFilterHandler" },
    filterParams: {
      useForm: true,
      buttons: ["apply"],
      closeOnApply: true,
    },
  },
  { field: "sport" },
];

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  defaultColDef: {
    flex: 1,
    minWidth: 100,
  },
  columnDefs: columnDefs,
  enableFilterHandlers: true,
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
  .then((response) => response.json())
  .then((data) => {
    gridApi!.setGridOption("rowData", data);
  });
```

[Live example: Use Grid Handlers](https://www.ag-grid.com/archive/36.2.0/examples/component-filter/use-grid-handlers/typescript/)

## Accessing the Component Instance

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 handler via `api.getColumnFilterHandler(colKey)`.

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.

#### Filter Component Instance

```ts
import {
  ClientSideRowModelModule,
  ColDef,
  CustomFilterModule,
  DoesFilterPassParams,
  GridApi,
  GridOptions,
  ModuleRegistry,
  TextEditorModule,
  TextFilterModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import { getData } from "./data";
import { PartialMatchFilter } from "./partialMatchFilter";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableDevValidations();
}

ModuleRegistry.registerModules([
  TextFilterModule,
  TextEditorModule,
  CustomFilterModule,
  ClientSideRowModelModule,
]);

function doesFilterPass({
  model,
  node,
  handlerParams,
}: DoesFilterPassParams<any, any, string>): boolean {
  const value = handlerParams.getValue(node).toString().toLowerCase();
  return model
    .toLowerCase()
    .split(" ")
    .every((filterWord) => value.indexOf(filterWord) >= 0);
}

const columnDefs: ColDef[] = [
  { field: "row" },
  {
    field: "name",
    filter: { component: PartialMatchFilter, doesFilterPass: doesFilterPass },
  },
];

let gridApi: GridApi;

const gridOptions: GridOptions = {
  defaultColDef: {
    editable: true,
    flex: 1,
    minWidth: 100,
    filter: true,
  },
  columnDefs: columnDefs,
  rowData: getData(),
  enableFilterHandlers: true,
};

function onClicked() {
  gridApi!
    .getColumnFilterInstance<PartialMatchFilter>("name")
    .then((instance) => {
      instance!.componentMethod("Hello World!");
    });
}

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).onClicked = onClicked;
}
```

[Live example: Filter Component Instance](https://www.ag-grid.com/archive/36.2.0/examples/component-filter/filter-component/typescript/)

## API Reference

### FilterDisplayComp

Properties available on the `FilterDisplayComp&lt;TData = any, TContext = any, TModel = any&gt;` interface.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `getGui` | `Function` |  |  |  |
| `destroy` | `Function` |  |  |  |
| `init` | `Function` |  |  |  |
| `refresh` | `Function` |  |  |  |
| `afterGuiAttached` | `Function` |  |  |  |
| `afterGuiDetached` | `Function` |  |  |  |
| `onNewRowsLoaded` | `Function` |  |  |  |
| `onAnyFilterChanged` | `Function` |  |  |  |

### FilterDisplayParams

Properties available on the `FilterDisplayParams&lt;TData = any, TContext = any, TModel = any, TState = any&gt;` interface.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model` | `TModel \| null` |  |  |  |
| `state` | `FilterDisplayState<TModel, TState>` |  |  |  |
| `onModelChange` | `Function` |  |  |  |
| `onStateChange` | `Function` |  |  |  |
| `onAction` | `Function` |  |  |  |
| `onUiChange` | `Function` |  |  |  |
| `getHandler` | `Function` |  |  |  |
| `source` | `FilterDisplaySource` |  |  |  |
| `additionalEventAttributes` | `any` |  |  |  |
| `column` | `Column` |  |  |  |
| `colDef` | `ColDef` |  |  |  |
| `getValue` | `Function` |  |  |  |
| `doesRowPassOtherFilter` | `Function` |  |  |  |
| `api` | `GridApi` |  |  |  |
| `context` | `TContext` |  |  |  |