Text Filter

Text filters allow you to filter string data.

The Provided Filters and Simple Filters pages explain the parts of the Text Filter that the same as the other Provided Filters. This page builds on that and explains some details that are specific to the Text Filter.

Text Filter Parameters

Text Filters are configured though the filterParams attribute of the column definition. All of the parameters from Provided Filters are available:

buttonsSpecifies 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.
closeOnApplyIf 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.
debounceMsBy default the Text and Number filters will debounce by 500ms. This is because these filters have text field inputs, so time is given to the user to type items in before the input is formatted and the filtering applied. The Set and Date will execute immediately (no debounce). To override these defaults, set debounceMs to the number of milliseconds to debounce by.
newRowsActionThis property is for when using the Client Side Row Model only. When set to 'clear', updating the data in the grid by calling api.setRowData() (or updating the rowData property if bound by a framework) will clear (reset) the filter. If you instead set this to 'keep', the grid will keep its currently set filter when the data is updated.
Default: 'clear'

In addition, the following parameters are also available:

alwaysShowBothConditionsBy default, only one condition is shown, and a second is made visible once a first condition has been entered. Set this to true to always show both conditions. In this case the second condition will be disabled until a first condition has been entered.
Default: false
filterOptionsArray of Filter Options to present to the user.
Options: 'equals', 'notEqual', 'contains', 'notContains', 'startsWith', 'endsWith', 'lessThan', 'lessThanOrEqual', 'greaterThan', 'greaterThanOrEqual', 'inRange', 'empty'
defaultOptionThe default Filter Option to be selected.
Options: 'equals', 'notEqual', 'contains', 'notContains', 'startsWith', 'endsWith', 'lessThan', 'lessThanOrEqual', 'greaterThan', 'greaterThanOrEqual', 'inRange', 'empty'
defaultJoinOperatorBy default, the two conditions are combined using AND. You can change this default by setting this property.
Options: 'AND', 'OR'
suppressAndOrConditionIf true, the filter will only allow one condition.
Default: false
textCustomComparatorUsed to override how to filter based on the user input. See Text Custom Comparator.
caseSensitiveBy default, text filtering is case-insensitive. Set this to true to make text filtering case-sensitive.
Default: false
textFormatterFormats the text before applying the filter compare logic. Useful if you want to substitute accented characters, for example.

Text Custom Comparator

By default the text filter performs strict case-insensitive text filtering, i.e. if you provide ['1,234.5USD', '345GBP'] as data for a text column:

  • contains '1,2' will show 1 value: ['1,234.5USD']
  • contains '12' will show 0 values
  • contains '$' will show 0 values
  • contains 'gbp' will show 1 value ['345GBP']

You can change the default behaviour by providing your own textCustomComparator, which allows you to provide your own logic to decide when to include a row in the filtered results.

The textCustomComparator is a function with the following signature:

function textCustomComparator(filter: string, gridValue: any, filterText: string): boolean;
  • filter: string The applicable filter type being tested. One of: equals, notEqual, contains, notContains, startsWith, endsWith
  • gridValue: any The value about to be filtered. If this column has a value getter, this value will be coming from the value getter, otherwise it is the raw value injected into the grid.
  • filterText: string The value to filter by.
  • returns: boolean Set to true if the value passes the filter, otherwise false.

The following is an example of a textCustomComparator that mimics the current implementation of ag-Grid. This can be used as a template to create your own.

function myComparator(filter, value, filterText) { var filterTextLowerCase = filterText.toLowerCase(); var valueLowerCase = value.toString().toLowerCase(); switch (filter) { case 'contains': return valueLowerCase.indexOf(filterTextLowerCase) >= 0; case 'notContains': return valueLowerCase.indexOf(filterTextLowerCase) === -1; case 'equals': return valueLowerCase === filterTextLowerCase; case 'notEqual': return valueLowerCase != filterTextLowerCase; case 'startsWith': return valueLowerCase.indexOf(filterTextLowerCase) === 0; case 'endsWith': var index = valueLowerCase.lastIndexOf(filterTextLowerCase); return index >= 0 && index === (valueLowerCase.length - filterTextLowerCase.length); default: // should never happen console.warn('invalid filter type ' + filter); return false; } } }

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 lower-casing 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:

function textFormatter(gridValue: string): string;

gridValue 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 following is an example function to remove accents and convert to lower case.

function(value) { return value.toLowerCase() .replace(/\s/g, '') .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') .replace(/\W/g, ''); };

Example: Text Filter

  • The Athlete column has only two filter options: filterOptions = ['contains', 'notContains']
  • The Athlete column has a text formatter, so if you search for 'o' it will find ø. You can try this by searching the string 'Bjo'.
  • The Athlete column has a debounce of 200ms (debounceMs = 200).
  • The Athlete column filter has the AND/OR additional filter suppressed (suppressAndOrCondition = true)
  • The Country column has only one filter option: filterOptions = ['contains']
  • The Country column has a textCustomComparator 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'
  • The Country column filter has a debounce of 2000ms (debounceMs = 2000)
  • The Year column has one filter option: filterOptions = ['inRange']
  • The Sport column has a different default option (defaultOption = 'startsWith')
  • The Sport column filter is case-sensitive (caseSensitive = true)