---
title: "Text Filter"
framework: vue
version: "36.1.0"
---
# Text Filter
Text Filters allow you to filter string data.
## Enabling Text Filters
#### Text Filter
```ts
import {
createApp,
defineComponent,
onBeforeMount,
ref,
shallowRef,
} from "vue";
import { AgGridVue } from "ag-grid-vue3";
import {
ClientSideRowModelModule,
ColDef,
ColGroupDef,
GridApi,
GridOptions,
GridReadyEvent,
ModuleRegistry,
TextFilterModule,
enableDevValidations,
} from "ag-grid-community";
import { IOlympicData } from "./interfaces";
if (process.env.NODE_ENV !== "production") {
enableDevValidations();
}
ModuleRegistry.registerModules([ClientSideRowModelModule, TextFilterModule]);
const VueExample = defineComponent({
template: `
`,
components: {
"ag-grid-vue": AgGridVue,
},
setup(props) {
const gridApi = shallowRef | null>(null);
const columnDefs = ref([
{
field: "athlete",
filter: true,
},
{
field: "country",
filter: "agTextColumnFilter",
},
{
field: "sport",
filter: true,
},
]);
const defaultColDef = ref({
flex: 1,
});
const rowData = ref(null);
const onGridReady = (params: GridReadyEvent) => {
gridApi.value = params.api;
const updateData = (data) => (rowData.value = data);
fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
.then((resp) => resp.json())
.then((data) => updateData(data));
};
return {
gridApi,
columnDefs,
defaultColDef,
rowData,
onGridReady,
};
},
});
const app = createApp(VueExample);
app.mount("#app");
```
[Live example: Text Filter](https://www.ag-grid.com/examples/filter-text/text-filter/vue3)
The Text Filter is the default filter used in AG Grid Community, but it can also be explicitly configured as shown below:
```ts
this.columnDefs = [
{
field: 'athlete',
// Text Filter is used by default in Community version
filter: true,
filterParams: {
// pass in additional parameters to the Text Filter
},
},
{
field: 'country',
// explicitly configure column to use the Text Filter
filter: 'agTextColumnFilter',
filterParams: {
// pass in additional parameters to the Text Filter
},
},
];
```
## Text Filter Parameters
Text Filters are configured though the `filterParams` attribute of the column definition (`ITextFilterParams` interface):
| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `buttons` | `FilterAction[]` | | | Specifies the buttons to be shown in the filter, in the order they should be displayed in. The options are: `'apply'`: If the Apply button is present, the filter is only applied after the user hits the Apply button. `'clear'`: The Clear button will clear the (form) details of the filter without removing any active filters on the column. `'reset'`: The Reset button will clear the details of the filter and any active filters on that column. `'cancel'`: The Cancel button will discard any changes that have been made to the filter in the UI, restoring the applied model. |
| `caseSensitive` | `boolean` | | `false` | By default, text filtering is case-insensitive. Set this to `true` to make text filtering case-sensitive. |
| `closeOnApply` | `boolean` | | `false` | If the Apply button is present, the filter popup will be closed immediately when the Apply or Reset button is clicked if this is set to `true`. |
| `debounceMs` | `number` | | | Overrides the default debounce time in milliseconds for the filter. Defaults are: `TextFilter` and `NumberFilter`: 500ms. (These filters have text field inputs, so a short delay before the input is formatted and the filtering applied is usually appropriate). `DateFilter` and `SetFilter`: 0ms |
| `defaultJoinOperator` | `JoinOperator` | | | By default, the two conditions are combined using `AND`. You can change this default by setting this property. Options: `AND`, `OR` |
| `defaultOption` | `string` | | | The default filter option to be selected. |
| `filterOptions` | `(IFilterOptionDef \| ISimpleFilterModelType)[]` | | | Array of filter options to present to the user. See [Filter Options](https://www.ag-grid.com/vue-data-grid/filter-text/#text-filter-options) for more information. |
| `filterPlaceholder` | `FilterPlaceholderFunction \| string` | | | Placeholder text for the filter textbox. |
| `maxNumConditions` | `number` | | `2` | Maximum number of conditions allowed in the filter. |
| `numAlwaysVisibleConditions` | `number` | | `1` | By default only one condition is shown, and additional conditions are made visible when the previous conditions are entered (up to `maxNumConditions`). To have more conditions shown by default, set this to the number required. Conditions will be disabled until the previous conditions have been entered. Note that this cannot be greater than `maxNumConditions` - anything larger will be ignored. |
| `readOnly` | `boolean` | | `false` | If set to `true`, disables controls in the filter to mutate its state. Normally this would be used in conjunction with the Filter API. See [Read-only Filter UI](https://www.ag-grid.com/vue-data-grid/filter-api/#read-only-filter-ui) for more information. |
| `textFormatter` | `Function` | | | Formats the text before applying the filter compare logic. Useful if you want to substitute accented characters, for example. |
| `textMatcher` | `TextMatcher` | | | Used to override how to filter based on the user input. Returns `true` if the value passes the filter, otherwise `false`. |
| `trimInput` | `boolean` | | `false` | If `true`, the input that the user enters will be trimmed when the filter is applied, so any leading or trailing whitespace will be removed. If only whitespace is entered, it will be left as-is. If you enable `trimInput`, it is best to also increase the `debounceMs` to give users more time to enter text. |
The following example demonstrates configuring different Text Filter parameters:
- For the **Athlete** column:
- The filter has a debounce of 200ms (`debounceMs = 200`).
- Only one Filter Condition is allowed (`maxNumConditions = 1`)
- For the **Country** column:
- The filter input will be trimmed when the filter is applied (`trimInput = true`)
- There is a debounce of 1000ms (`debounceMs = 1000`)
- For the **Sport** column:
- The filter is case-sensitive (`caseSensitive = true`)
#### Text Filter Parameters
```ts
import {
createApp,
defineComponent,
onBeforeMount,
ref,
shallowRef,
} from "vue";
import { AgGridVue } from "ag-grid-vue3";
import {
ClientSideRowModelModule,
ColDef,
ColGroupDef,
GridApi,
GridOptions,
GridReadyEvent,
ITextFilterParams,
ModuleRegistry,
TextFilterModule,
enableDevValidations,
} from "ag-grid-community";
import { IOlympicData } from "./interfaces";
if (process.env.NODE_ENV !== "production") {
enableDevValidations();
}
ModuleRegistry.registerModules([ClientSideRowModelModule, TextFilterModule]);
const VueExample = defineComponent({
template: `
`,
components: {
"ag-grid-vue": AgGridVue,
},
setup(props) {
const gridApi = shallowRef | null>(null);
const columnDefs = ref([
{
field: "athlete",
filterParams: {
debounceMs: 200,
maxNumConditions: 1,
} as ITextFilterParams,
},
{
field: "country",
filterParams: {
trimInput: true,
debounceMs: 1000,
} as ITextFilterParams,
},
{
field: "sport",
filterParams: {
caseSensitive: true,
} as ITextFilterParams,
},
]);
const defaultColDef = ref({
flex: 1,
filter: true,
});
const rowData = ref(null);
const onGridReady = (params: GridReadyEvent) => {
gridApi.value = params.api;
const updateData = (data) => (rowData.value = data);
fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
.then((resp) => resp.json())
.then((data) => updateData(data));
};
return {
gridApi,
columnDefs,
defaultColDef,
rowData,
onGridReady,
};
},
});
const app = createApp(VueExample);
app.mount("#app");
```
[Live example: Text Filter Parameters](https://www.ag-grid.com/examples/filter-text/text-filter-parameters/vue3)
## Text Formatter
By default, the grid compares the Text Filter with the values in a case-insensitive way, by converting both the filter text and the values to lower case and comparing them; for example, `'o'` will match `'Olivia'` and `'Salmon'`. If you instead want to have case-sensitive matches, you can set `caseSensitive = true` in the `filterParams`, so that no lowercasing is performed. In this case, `'o'` would no longer match `'Olivia'`.
You might have more advanced requirements, for example to ignore accented characters. In this case, you can provide your own `textFormatter`, which is a function with the following signature:
| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `textFormatter` | `Function` | | | Formats the text before applying the filter compare logic. Useful if you want to substitute accented characters, for example. |
`from` is the value coming from the grid. This can be from the `valueGetter` if there is any for the column, or the value as originally provided in the `rowData`. The function should return a string to be used for the purpose of filtering.
The Text Formatter is applied to both the filter text and the values before they are compared.
The following is an example function to remove accents and convert to lower case.
```js
const toLowerWithoutAccents = value => value == null
? null
: value.toLowerCase()
.replace(/[àáâãäå]/g, 'a')
.replace(/æ/g, 'ae')
.replace(/ç/g, 'c')
.replace(/[èéêë]/g, 'e')
.replace(/[ìíîï]/g, 'i')
.replace(/ñ/g, 'n')
.replace(/[òóôõö]/g, 'o')
.replace(/œ/g, 'oe')
.replace(/[ùúûü]/g, 'u')
.replace(/[ýÿ]/g, 'y');
```
Note that when providing a Text Formatter, the `caseSensitive` parameter is ignored. In this situation, if you want to do a case-insensitive comparison, you will need to perform case conversion inside the `textFormatter` function.
The example below demonstrates a `textFormatter` on the **Athlete** column:
- If you search for `'o'` it will find `'ö'`. You can try this by searching the string `'Bjo'`.
#### Text Formatter
```ts
import {
createApp,
defineComponent,
onBeforeMount,
ref,
shallowRef,
} from "vue";
import { AgGridVue } from "ag-grid-vue3";
import {
ClientSideRowModelModule,
ColDef,
ColGroupDef,
GridApi,
GridOptions,
GridReadyEvent,
ITextFilterParams,
ModuleRegistry,
TextFilterModule,
enableDevValidations,
} from "ag-grid-community";
import { IOlympicData } from "./interfaces";
if (process.env.NODE_ENV !== "production") {
enableDevValidations();
}
ModuleRegistry.registerModules([ClientSideRowModelModule, TextFilterModule]);
const athleteFilterParams: ITextFilterParams = {
textFormatter: (r) => {
if (r == null) return null;
return r
.toLowerCase()
.replace(/[àáâãäå]/g, "a")
.replace(/æ/g, "ae")
.replace(/ç/g, "c")
.replace(/[èéêë]/g, "e")
.replace(/[ìíîï]/g, "i")
.replace(/ñ/g, "n")
.replace(/[òóôõö]/g, "o")
.replace(/œ/g, "oe")
.replace(/[ùúûü]/g, "u")
.replace(/[ýÿ]/g, "y");
},
};
const VueExample = defineComponent({
template: `
`,
components: {
"ag-grid-vue": AgGridVue,
},
setup(props) {
const gridApi = shallowRef | null>(null);
const columnDefs = ref([
{
field: "athlete",
filterParams: athleteFilterParams,
},
{
field: "country",
},
{
field: "sport",
},
]);
const defaultColDef = ref({
flex: 1,
filter: true,
});
const rowData = ref(null);
const onGridReady = (params: GridReadyEvent) => {
gridApi.value = params.api;
const updateData = (data) => (rowData.value = data);
fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
.then((resp) => resp.json())
.then((data) => updateData(data));
};
return {
gridApi,
columnDefs,
defaultColDef,
rowData,
onGridReady,
};
},
});
const app = createApp(VueExample);
app.mount("#app");
```
[Live example: Text Formatter](https://www.ag-grid.com/examples/filter-text/text-formatter/vue3)
## Text Custom Matcher
In most cases, you can customise the Text Filter matching logic by providing your own [Text Formatter](#text-formatter), e.g. to remove or replace characters in the filter text and values. The Text Formatter is applied to both the filter text and values before the filter comparison is performed.
For more advanced use cases, you can provide your own `textMatcher` to decide when to include a row in the filtered results. For example, you might want to apply different logic for the filter option `equals` than for `contains`.
| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `textMatcher` | `TextMatcher` | | | Used to override how to filter based on the user input. Returns `true` if the value passes the filter, otherwise `false`. |
The following is an example of a `textMatcher` that mimics the current implementation of AG Grid. This can be used as a template to create your own.
```ts
this.columnDefs = [
{
field: 'athlete',
filter: 'agTextColumnFilter',
filterParams: {
textMatcher: ({ filterOption, value, filterText }) => {
if (filterText == null) {
return false;
}
switch (filterOption) {
case 'contains':
return value.indexOf(filterText) >= 0;
case 'notContains':
return value.indexOf(filterText) < 0;
case 'equals':
return value === filterText;
case 'notEqual':
return value != filterText;
case 'startsWith':
return value.indexOf(filterText) === 0;
case 'endsWith':
const index = value.lastIndexOf(filterText);
return index >= 0 && index === (value.length - filterText.length);
default:
// should never happen
console.warn('invalid filter type ' + filterOption);
return false;
}
}
}
}
];
```
Note that the `textMatcher` is not called for the `blank` and `notBlank` options.
The example below demonstrates a `textMatcher` on the **Country** column:
- Most options are implemented as per the default grid implementation above.
- The `contains` option has additional logic so that aliases can be entered in the filter. E.g. if you filter using the text `'usa'` it will match `United States`, or `'holland'` will match `'Netherlands'`.
#### Text Custom Matcher
```ts
import {
createApp,
defineComponent,
onBeforeMount,
ref,
shallowRef,
} from "vue";
import { AgGridVue } from "ag-grid-vue3";
import {
ClientSideRowModelModule,
ColDef,
ColGroupDef,
GridApi,
GridOptions,
GridReadyEvent,
ITextFilterParams,
ModuleRegistry,
TextFilterModule,
enableDevValidations,
} from "ag-grid-community";
import { IOlympicData } from "./interfaces";
if (process.env.NODE_ENV !== "production") {
enableDevValidations();
}
ModuleRegistry.registerModules([ClientSideRowModelModule, TextFilterModule]);
function contains(target: string, lookingFor: string) {
return target && target.indexOf(lookingFor) >= 0;
}
const countryFilterParams: ITextFilterParams = {
textMatcher: ({ filterOption, value, filterText }) => {
if (filterText == null) {
return false;
}
switch (filterOption) {
case "contains":
const aliases: Record = {
usa: "united states",
holland: "netherlands",
};
const literalMatch = contains(value, filterText || "");
return !!literalMatch || !!contains(value, aliases[filterText || ""]);
case "notContains":
return value.indexOf(filterText) < 0;
case "equals":
return value === filterText;
case "notEqual":
return value != filterText;
case "startsWith":
return value.indexOf(filterText) === 0;
case "endsWith":
const index = value.lastIndexOf(filterText);
return index >= 0 && index === value.length - filterText.length;
default:
// should never happen
console.warn("invalid filter type " + filterOption);
return false;
}
},
};
const VueExample = defineComponent({
template: `
`,
components: {
"ag-grid-vue": AgGridVue,
},
setup(props) {
const gridApi = shallowRef | null>(null);
const columnDefs = ref([
{
field: "country",
filterParams: countryFilterParams,
},
{
field: "athlete",
},
{
field: "sport",
},
]);
const defaultColDef = ref({
flex: 1,
filter: true,
});
const rowData = ref(null);
const onGridReady = (params: GridReadyEvent) => {
gridApi.value = params.api;
const updateData = (data) => (rowData.value = data);
fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
.then((resp) => resp.json())
.then((data) => updateData(data));
};
return {
gridApi,
columnDefs,
defaultColDef,
rowData,
onGridReady,
};
},
});
const app = createApp(VueExample);
app.mount("#app");
```
[Live example: Text Custom Matcher](https://www.ag-grid.com/examples/filter-text/text-custom-matcher/vue3)
## Text Filter Model
The Filter Model describes the current state of the applied Text Filter. If only one [Filter Condition](https://www.ag-grid.com/vue-data-grid/filter-conditions/) is set, this will be a `TextFilterModel`:
| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `filterType` | `'text'` | | | Filter type is always `'text'` |
| `filter` | `string \| null` | | | The text value associated with the filter. It's optional as custom filters may not have a text value. |
| `filterTo` | `string \| null` | | | The 2nd text value associated with the filter, if supported. |
| `type` | `ISimpleFilterModelType \| null` | | | One of the filter options, e.g. `'equals'` |
If more than one Filter Condition is set, then multiple instances of the model are created and wrapped inside a Combined Model (`ICombinedSimpleModel`). A Combined Model looks as follows:
```ts
// A filter combining multiple conditions
interface ICombinedSimpleModel {
filterType: string;
operator: JoinOperator;
// multiple instances of the Filter Model
conditions: TextFilterModel[];
}
type JoinOperator = 'AND' | 'OR';
```
An example of a Filter Model with two conditions is as follows:
```js
// Text Filter with two conditions, both are equals type
const textEqualsSwimmingOrEqualsGymnastics = {
filterType: 'text',
operator: 'OR',
conditions: [
{
filterType: 'text',
type: 'equals',
filter: 'Swimming'
},
{
filterType: 'text',
type: 'equals',
filter: 'Gymnastics'
}
]
};
```
## Text Filter Options
The Text Filter presents a list of [Filter Options](https://www.ag-grid.com/vue-data-grid/filter-conditions/#filter-options) to the user.
The list of options is as follows:
| Option Name | Option Key | Included by Default |
| --- | --- | --- |
| Contains | `contains` | Yes |
| Does not contain | `notContains` | Yes |
| Equals | `equals` | Yes |
| Does not equal | `notEqual` | Yes |
| Begins with | `startsWith` | Yes |
| Ends with | `endsWith` | Yes |
| Blank | `blank` | Yes |
| Not blank | `notBlank` | Yes |
| Choose one | `empty` | No |
Note that the `empty` filter option is primarily used when creating [Custom Filter Options](https://www.ag-grid.com/vue-data-grid/filter-conditions/#custom-filter-options). When 'Choose one' is displayed, the filter is not active.
The default option for the Text Filter is `contains`.
When providing filter options, the default filter option (or the first option if no default set) must be an option that displays an input or the `empty` filter option (as a filter option with no inputs would mean the filter is active by default).
The example below demonstrates configuring different filter options:
- For the **Athlete** column, there are only two filter options: `filterOptions = ['contains', 'notContains']`.
- For the **Country** column, there is only one filter option: `filterOptions = ['contains']`.
- For the **Sport** column, there is a different default filter option: `defaultOption = 'startsWith'`.
#### Text Filter Options
```ts
import {
createApp,
defineComponent,
onBeforeMount,
ref,
shallowRef,
} from "vue";
import { AgGridVue } from "ag-grid-vue3";
import {
ClientSideRowModelModule,
ColDef,
ColGroupDef,
GridApi,
GridOptions,
GridReadyEvent,
ITextFilterParams,
ModuleRegistry,
TextFilterModule,
enableDevValidations,
} from "ag-grid-community";
import { IOlympicData } from "./interfaces";
if (process.env.NODE_ENV !== "production") {
enableDevValidations();
}
ModuleRegistry.registerModules([ClientSideRowModelModule, TextFilterModule]);
const VueExample = defineComponent({
template: `
`,
components: {
"ag-grid-vue": AgGridVue,
},
setup(props) {
const gridApi = shallowRef | null>(null);
const columnDefs = ref([
{
field: "athlete",
filterParams: {
filterOptions: ["contains", "notContains"],
maxNumConditions: 1,
} as ITextFilterParams,
},
{
field: "country",
filterParams: {
filterOptions: ["contains"],
} as ITextFilterParams,
},
{
field: "sport",
filterParams: {
defaultOption: "startsWith",
} as ITextFilterParams,
},
]);
const defaultColDef = ref({
flex: 1,
filter: true,
});
const rowData = ref(null);
const onGridReady = (params: GridReadyEvent) => {
gridApi.value = params.api;
const updateData = (data) => (rowData.value = data);
fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
.then((resp) => resp.json())
.then((data) => updateData(data));
};
return {
gridApi,
columnDefs,
defaultColDef,
rowData,
onGridReady,
};
},
});
const app = createApp(VueExample);
app.mount("#app");
```
[Live example: Text Filter Options](https://www.ag-grid.com/examples/filter-text/text-filter-options/vue3)
## Text Filter Values
By default, the values supplied to the Text Filter are retrieved from the data based on the `field` attribute. This can be overridden by providing a `filterValueGetter` in the Column Definition. This is similar to using a [Value Getter](https://www.ag-grid.com/vue-data-grid/value-getters/), but is specific to the filter.
| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `filterValueGetter` | `string \| ValueGetterFunc` | | | Function or [expression](https://www.ag-grid.com/vue-data-grid/cell-expressions/#column-definition-expressions). Gets the value for filtering purposes. |
## Applying the Text Filter
Applying the Text Filter is described in more detail in the following sections:
- [Apply, Clear, Reset and Cancel Buttons](https://www.ag-grid.com/vue-data-grid/filter-applying/#apply-clear-reset-and-cancel-buttons)
- [Applying the UI Model](https://www.ag-grid.com/vue-data-grid/filter-applying/#applying-the-ui-model)
## Data Updates
The Text Filter is not affected by data changes. When the grid data is updated, the filter value will remain unchanged and the filter will be re-applied based on the updated data (e.g. the displayed rows will update if necessary).