---
title: "Quick Filter"
framework: javascript
version: "36.1.0"
---

# Quick Filter

Quick Filter is a piece of text given to the grid that is used to filter rows by comparing against the data in all columns. It can be used in addition to column-specific filtering.

## Enable the Quick Filter

### Using the Quick Access Toolbar  (Enterprise)

The recommended way to add a Quick Filter input is as a [Quick Access Toolbar](https://www.ag-grid.com/javascript-data-grid/toolbar/) item. This keeps the Quick Filter integrated with the grid and requires no additional markup.

#### Quick Filter with Toolbar

```ts
import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  QuickFilterModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import { ToolbarModule } from "ag-grid-enterprise";

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

ModuleRegistry.registerModules([
  QuickFilterModule,
  ToolbarModule,
  ClientSideRowModelModule,
]);

let gridApi: GridApi;

const gridOptions: GridOptions = {
  columnDefs: [
    { field: "athlete" },
    { field: "country" },
    { field: "sport" },
    { field: "age", minWidth: 100 },
    { field: "gold", minWidth: 100 },
    { field: "silver", minWidth: 100 },
    { field: "bronze", minWidth: 100 },
  ],
  defaultColDef: {
    flex: 1,
  },
  toolbar: {
    items: ["agQuickFilterToolbarItem"],
  },
};

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: IOlympicData[]) => gridApi!.setGridOption("rowData", data));
```

[Live example: Quick Filter with Toolbar](https://www.ag-grid.com/examples/filter-quick/quick-filter-toolbar/typescript)

```js
const gridOptions = {
    toolbar: {
        items: ['agQuickFilterToolbarItem'],
    },

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

### Using Grid Options

Call `setGridOption('quickFilterText', text)` to filter rows.

```js
api.setGridOption('quickFilterText', 'new filter text');
```

The initial Quick Filter text can also be set via the `quickFilterText` grid option.

#### Quick Filter

```ts
import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  QuickFilterModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";

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

ModuleRegistry.registerModules([QuickFilterModule, ClientSideRowModelModule]);

let gridApi: GridApi;

const gridOptions: GridOptions = {
  columnDefs: [
    { field: "athlete" },
    { field: "country" },
    { field: "sport" },
    { field: "age", minWidth: 100 },
    { field: "gold", minWidth: 100 },
    { field: "silver", minWidth: 100 },
    { field: "bronze", minWidth: 100 },
  ],
  defaultColDef: {
    flex: 1,
  },
};

function onFilterTextBoxChanged() {
  gridApi!.setGridOption(
    "quickFilterText",
    (document.getElementById("filter-text-box") as HTMLInputElement).value,
  );
}

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: IOlympicData[]) => gridApi!.setGridOption("rowData", data));

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

[Live example: Quick Filter](https://www.ag-grid.com/examples/filter-quick/quick-filter/typescript)

## Quick Filter Value

The filter text is split into words, and each word is compared against every column value (case-insensitive). All words must match a row for it to be included. For example, searching "Tony Ireland" will only show rows containing both "Tony" and "Ireland".

### Checking the Quick Filter

When the Quick Filter is set via `quickFilterText`, the state is maintained outside the grid. When the Quick Access Toolbar item is used, the input is owned by the grid. In either case, use `isQuickFilterPresent()` to check whether the Quick Filter is applied, and `getQuickFilter()` to read the current text.

### Overriding the Quick Filter Value

If your data contains complex objects, the Quick Filter will end up comparing against `[object Object]` instead of searchable string values. In this case you will need to implement `getQuickFilterText` to extract a searchable string from your complex object.

Alternatively, you might want to format string values specifically for searching (e.g. replace accented characters in strings, or remove commas from numbers).

Finally, if you want a column to be ignored by the Quick Filter, have `getQuickFilterText` return an empty string `''`.

```js
const gridOptions = {
    columnDefs: [
        {
            field: 'country',
            getQuickFilterText: params => {
                return params.value.name;
            }
        }
    ],

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

> **Note**
>
> The Quick Filter will work 'out of the box' in most cases, so you should only override the Quick Filter value if you have a particular problem to resolve.

## Quick Filter Cache

By default, the Quick Filter checks each column's value, including running value getters if present, every time the Quick Filter is executed. If your data set is large, you may wish to enable the Quick Filter cache by setting `cacheQuickFilter = true`.

When the cache is enabled, a 'Quick Filter text' is generated for each node by concatenating all the values for each column. For example, a table with columns of "Employee Name" and "Job" could have a row with Quick Filter text of `'NIALL CROSBY\nCOFFEE MAKER'`. The grid then performs a simple string search, so if you search for `'Niall'`, it will find our example text. Joining all the column values into one string gives a performance boost. The values are joined after the Quick Filter is requested for the first time and stored in the `rowNode` - the original data that you provide is not changed.

### Reset Cache Text

When in use, the Quick Filter cache text can be manually reset in one of the following ways:

- Each Row Node has a `resetQuickFilterAggregateText()` method on it, which can be called to reset the cache text.
- `api.resetQuickFilter()` will reset the cache text on every Row Node.

[Updating Data](https://www.ag-grid.com/javascript-data-grid/data-update/), [Cell Editing](https://www.ag-grid.com/javascript-data-grid/cell-editing/), [Excluding/Including Hidden Columns](#include-hidden-columns) from the Quick Filter, and [Updating Column Definitions](https://www.ag-grid.com/javascript-data-grid/column-updating-definitions/) will automatically reset the cache text on any affected Row Nodes.

## Include Hidden Columns

By default the Quick Filter will only check visible column values. If you want to check hidden column values, then you can set the grid option `includeHiddenColumnsInQuickFilter = true`. Note that if you have a large number of hidden columns then this can have a performance impact.

This can also be set via the API method `setGridOption('includeHiddenColumnsInQuickFilter', toInclude)`.

## Quick Filter Parser

By default the Quick Filter splits the text into a list of words which are then compared against each row. You may want to override this behaviour, for example to allow using quotes to search for exact string values. This is possible by providing a `quickFilterParser`. Note that the value passed to the parser will have already been converted to upper case.

```js
const gridOptions = {
    // split words by comma instead of space
    quickFilterParser: (quickFilter) => quickFilter.split(','),

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

## Quick Filter Matcher

The default behaviour of the Quick Filter is to check whether every search term in the parsed Quick Filter text appears in the [Quick Filter Value](#overriding-the-quick-filter-value) for any column. The matching logic can be overridden by providing a `quickFilterMatcher`, e.g. to perform searches via regular expressions.

The `rowQuickFilterAggregateText` parameter passed to the matcher function is a concatenation of all the Quick Filter Values (using the [Quick Filter Cache](#quick-filter-cache) if enabled). Note that this value will be upper case.

```js
const gridOptions = {
    // perform a regular expression search
    quickFilterMatcher: (quickFilterParts, rowQuickFilterAggregateText) => {
        return quickFilterParts.every(part => rowQuickFilterAggregateText.match(part));
    },

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

## Example: Quick Filter Configuration

The example below shows the Quick Filter working on different data types. Each column demonstrates something different as follows:

- `Name` - Simple column, nothing complex.
- `Age` - Complex object with 'dot' in field, Quick Filter works fine.
- `Country` - Complex object and value getter used, again Quick Filter works fine.
- `Results` - Complex object, Quick Filter would call `toString` on the complex object, so `getQuickFilterText` is provided.
- `Hidden` - A hidden column with all values being the string 'hidden'. Search `hidden` in the toolbar and no rows will be matched. Click the `Include Hidden Columns` button to set `includeHiddenColumnsInQuickFilter = true`, and all rows will be matched. Note the Quick Filter cache will be cleared automatically when the option is changed.

A `quickFilterParser` is defined to allow exact searches using quotes, e.g. `"gold: 1"` will only match `Results` with that value. A `quickFilterMatcher` is also defined to allow regular expressions to be entered, e.g. `2[012]` will match `Age` 20, 21 and 22.

The example also demonstrates having the Quick Filter cache turned on. The grid works very fast even when the cache is turned off, so you probably don't need it for small data sets. For large data sets (e.g. over 10,000 rows), turning the cache on will improve Quick Filter speed. Tweaking the `cacheQuickFilter` option in the example allows both modes to be experimented with:

- **Cache Quick Filter (example default):** The cache is used. Value getters are executed the first time the Quick Filter is run. Hitting 'Print Quick Filter Cache Texts' will return back the Quick Filter text for each row which will initially be `undefined` and then return the Quick Filter text after the Quick Filter is executed for the first time. This is printed to the developer console.
- **Normal Quick Filter:** The cache is not used. Value getters are executed on every node each time the filter is executed. Hitting 'Print Quick Filter Cache Texts' will always return `undefined` for every row because the cache is not used.

#### Quick Filter Configuration

```ts
import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ICellRendererParams,
  ModuleRegistry,
  NumberEditorModule,
  QuickFilterModule,
  RowApiModule,
  TextEditorModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import { getData } from "./data";

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

ModuleRegistry.registerModules([
  RowApiModule,
  QuickFilterModule,
  NumberEditorModule,
  TextEditorModule,
  ClientSideRowModelModule,
]);

const getMedalString = function ({
  gold,
  silver,
  bronze,
}: {
  gold: number;
  silver: number;
  bronze: number;
}) {
  const goldStr = gold > 0 ? `Gold: ${gold} ` : "";
  const silverStr = silver > 0 ? `Silver: ${silver} ` : "";
  const bronzeStr = bronze > 0 ? `Bronze: ${bronze}` : "";
  return goldStr + silverStr + bronzeStr;
};

const MedalRenderer = function (params: ICellRendererParams) {
  return getMedalString(params.value);
};

let gridApi: GridApi;

const gridOptions: GridOptions = {
  columnDefs: [
    // simple column, easy to understand
    { field: "name" },
    // the grid works with embedded fields
    { headerName: "Age", field: "person.age" },
    // or use value getter, all works with quick filter
    { headerName: "Country", valueGetter: "data.person.country" },
    // or use the object value, so value passed around is an object
    {
      headerName: "Results",
      field: "medals",
      cellRenderer: MedalRenderer,
      // this is needed to avoid toString=[object,object] result with objects
      getQuickFilterText: (params) => {
        return getMedalString(params.value);
      },
      cellDataType: false,
    },
    {
      headerName: "Hidden",
      field: "hidden",
      hide: true,
    },
  ],
  defaultColDef: {
    flex: 1,
    editable: true,
  },
  rowData: getData(),
  cacheQuickFilter: true,
  quickFilterParser: quickFilterParser,
  quickFilterMatcher: quickFilterMatcher,
};

let includeHiddenColumns = false;

function onIncludeHiddenColumnsToggled() {
  includeHiddenColumns = !includeHiddenColumns;
  gridApi!.setGridOption(
    "includeHiddenColumnsInQuickFilter",
    includeHiddenColumns,
  );
  document.querySelector("#includeHiddenColumns")!.textContent =
    `${includeHiddenColumns ? "Exclude" : "Include"} Hidden Columns`;
}

function onFilterTextBoxChanged() {
  gridApi!.setGridOption(
    "quickFilterText",
    (document.getElementById("filter-text-box") as HTMLInputElement).value,
  );
}

function onPrintQuickFilterTexts() {
  gridApi!.forEachNode(function (rowNode, index) {
    console.log(
      "Row " +
        index +
        " quick filter text is " +
        rowNode.quickFilterAggregateText,
    );
  });
}

function quickFilterParser(quickFilter: string) {
  // Note that this implementation is just provided as a simple example of the feature.
  // It does not handle all edge cases, e.g. preceding spaces inside quotes.
  const quickFilterParts = [];
  let lastSpaceIndex = -1;

  const isQuote = (index: number) => quickFilter[index] === '"';
  const getQuickFilterPart = (lastSpaceIndex: number, currentIndex: number) => {
    const startsWithQuote = isQuote(lastSpaceIndex + 1);
    const endsWithQuote = isQuote(currentIndex - 1);
    const startIndex =
      startsWithQuote && endsWithQuote
        ? lastSpaceIndex + 2
        : lastSpaceIndex + 1;
    const endIndex =
      startsWithQuote && endsWithQuote ? currentIndex - 1 : currentIndex;
    return quickFilter.slice(startIndex, endIndex);
  };

  for (let i = 0; i < quickFilter.length; i++) {
    const char = quickFilter[i];
    if (char === " ") {
      if (!isQuote(lastSpaceIndex + 1) || isQuote(i - 1)) {
        quickFilterParts.push(getQuickFilterPart(lastSpaceIndex, i));
        lastSpaceIndex = i;
      }
    }
  }
  if (lastSpaceIndex !== quickFilter.length - 1) {
    quickFilterParts.push(
      getQuickFilterPart(lastSpaceIndex, quickFilter.length),
    );
  }

  return quickFilterParts;
}

function quickFilterMatcher(
  quickFilterParts: string[],
  rowQuickFilterAggregateText: string,
) {
  let result: boolean;
  try {
    result = quickFilterParts.every((part) =>
      rowQuickFilterAggregateText.match(part),
    );
  } catch {
    result = false;
  }
  return result;
}

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).onIncludeHiddenColumnsToggled = onIncludeHiddenColumnsToggled;
  (<any>window).onFilterTextBoxChanged = onFilterTextBoxChanged;
  (<any>window).onPrintQuickFilterTexts = onPrintQuickFilterTexts;
}
```

[Live example: Quick Filter Configuration](https://www.ag-grid.com/examples/filter-quick/quick-filter-configuration/typescript)

## Pivoting / Filtering Aggregated Values

When [Pivoting](https://www.ag-grid.com/javascript-data-grid/pivoting/) or [Filtering Aggregated Values](https://www.ag-grid.com/javascript-data-grid/aggregation-filtering/#filtering-for-aggregated-values) are enabled, Quick Filter is applied by default to the data after pivoting/aggregating has been performed. This means that filtering will not change the aggregated values, and only columns that are being used for pivoting can be used for filtering.

It is possible to instead filter the data before pivoting/aggregating are applied. This can be done by setting the grid option `applyQuickFilterBeforePivotOrAgg = true`.

The following example demonstrates the difference in filtering behaviour with `applyQuickFilterBeforePivotOrAgg` enabled/disabled. The columns **Athlete** and **Sport** are present, but are not being used for pivoting:

- Use the Quick Filter toolbar to search for "Swimming" or 2000 and note that there are no matches in the grid, as the filter is applied after pivoting.
- Click the button to apply Quick Filter before pivoting and aggregation, then search again and note that there are now matches, as the filter is applied before pivoting.

#### Quick Filter Pivot / Aggregation

```ts
import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  QuickFilterModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import { PivotModule, ToolbarModule } from "ag-grid-enterprise";

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

ModuleRegistry.registerModules([
  QuickFilterModule,
  ToolbarModule,
  ClientSideRowModelModule,
  PivotModule,
]);

let gridApi: GridApi;

const gridOptions: GridOptions = {
  columnDefs: [
    { field: "athlete" },
    { field: "country", rowGroup: true },
    { field: "sport" },
    { field: "year", pivot: true },
    { field: "age" },
    { field: "gold", aggFunc: "sum" },
    { field: "silver", aggFunc: "sum" },
    { field: "bronze", aggFunc: "sum" },
  ],
  defaultColDef: {
    flex: 1,
    minWidth: 150,
  },
  autoGroupColumnDef: {
    minWidth: 250,
  },
  pivotMode: true,
  toolbar: {
    items: ["agQuickFilterToolbarItem"],
  },
};

let applyBeforePivotOrAgg = false;

function onApplyBeforePivotOrAgg() {
  applyBeforePivotOrAgg = !applyBeforePivotOrAgg;
  gridApi!.setGridOption(
    "applyQuickFilterBeforePivotOrAgg",
    applyBeforePivotOrAgg,
  );
  document.querySelector("#applyBeforePivotOrAgg")!.textContent =
    `Apply ${applyBeforePivotOrAgg ? "After" : "Before"} Pivot/Aggregation`;
}

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: IOlympicData[]) => gridApi!.setGridOption("rowData", data));

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

[Live example: Quick Filter Pivot / Aggregation](https://www.ag-grid.com/examples/filter-quick/quick-filter-pivot-agg/typescript)

## Server-Side Data

The Quick Filter is only supported with the [Client-Side Row Model](https://www.ag-grid.com/javascript-data-grid/row-models/#client-side). For the other row models you would need to implement your own server-side filtering to replicate Quick Filter functionality.

## API Reference

### Grid Options

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `quickFilterText` | `string` |  |  | Rows are filtered using this text as a Quick Filter. Only supported for Client-Side Row Model. Module: [`QuickFilterModule`](https://www.ag-grid.com/javascript-data-grid/modules/). |
| `cacheQuickFilter` | `boolean` |  | `false` | Set to `true` to turn on the Quick Filter cache, used to improve performance when using the Quick Filter. Module: [`QuickFilterModule`](https://www.ag-grid.com/javascript-data-grid/modules/). [Initial](https://www.ag-grid.com/javascript-data-grid/grid-interface/#initial-grid-options). |
| `includeHiddenColumnsInQuickFilter` | `boolean` |  | `false` | Hidden columns are excluded from the Quick Filter by default. To include hidden columns, set to `true`. Module: [`QuickFilterModule`](https://www.ag-grid.com/javascript-data-grid/modules/). |
| `quickFilterParser` | `QuickFilterParser` |  |  | Changes how the Quick Filter splits the Quick Filter text into search terms. Module: [`QuickFilterModule`](https://www.ag-grid.com/javascript-data-grid/modules/). |
| `quickFilterMatcher` | `QuickFilterMatcher` |  |  | Changes the matching logic for whether a row passes the Quick Filter. Module: [`QuickFilterModule`](https://www.ag-grid.com/javascript-data-grid/modules/). |

### Column Properties

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `getQuickFilterText` | `GetQuickFilterText` |  |  | A function to tell the grid what Quick Filter text to use for this column if you don't want to use the default (which is calling `toString` on the value). Module: [`QuickFilterModule`](https://www.ag-grid.com/javascript-data-grid/modules/). |

### Grid API Methods

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `getQuickFilter` | `Function` |  |  | Only supported for Client-Side Row Model. Get the current Quick Filter text from the grid, or `undefined` if none is set. Module: [`QuickFilterModule`](https://www.ag-grid.com/javascript-data-grid/modules/). |
| `isQuickFilterPresent` | `Function` |  |  | Only supported for Client-Side Row Model. Returns `true` if the Quick Filter is set, otherwise `false`. Module: [`QuickFilterModule`](https://www.ag-grid.com/javascript-data-grid/modules/). |