Expand All

  Getting Started

  Reference

  Features

  Row Models

  Themes

  Components

  Examples

  Third Party

Misc

Github stars make projects look great. Please help, donate a star, it's free.
Read about ag-Grid's Partnership with webpack.
Get informed on releases and other ag-Grid news only - never spam.
Follow on Twitter

Text Filter

Text filters allow users to filter data based on the text contained in the column where this filter is defined. To create a new text filter in a column, all you need to do is:

  1. Enable filtering on that column
  2. Set the filter type to text

In order to set the filter type to text you need to add the following to your column definition

colDef:{ filter:'text' }

Enterprise users have Set Filter as the default type

Non enterprise users have text filter as the default filter type. If you are not enterprise user, you don't need to specify filter:'text' since it is your default filter type

Text Filter Parameters

A text filter can take the following parameters:

  • newRowsAction: What to do when new rows are loaded. The default is to reset the filter. If you want to keep the filter status between row loads, then set this value to 'keep'.
  • applyButton: Set to true to include an 'Apply' button with the filter and not filter automatically as the selection changes.
  • clearButton: Set to true to include a 'Clear' button with the filter which when cliked will remove the filter conditions to this filter.
  • textCustomComparator: Used to override what to filter based on the user input. See textCustomComparator section below
  • filterOptions: If specified, limits the amount of options presented in the filter UI, it must be a string array containing some of the following values {equals, notEqual, contains, notContains, startsWith, endsWith}
  • defaultOption: If specified, changes the default filter option to one of {equals, notEqual, contains, notContains, startsWith, endsWith}. If not specified the default type is {contains}, if {contains} is not available because is removed using filterOptions, then the default is the first item in the filterOptions
  • textFormatter: If specified, formats the text before applying the filter compare logic, useful for instance if substituting accentuated characters or if you want to do case sensitive filtering.
  • debounceMs: If specified, the filter will wait this amount of ms after the user stops entering any characters in the input box before is triggered. If not specified this value is 500ms, if the value specified is 0 the filter will be immediately triggered
  • caseSensitive If true, the text filtering will be case sensitive, if not specified or false, the filtering will be case insensitive
The parameters for the filter must be specified in the property filterParams inside the column definition object

colDef:{ filter:'text', filterParams:{ ... } }

Text Custom Comparator

By default the text filter does strict case insensitive text filtering: ie If you provide as data for a text column the following values ['1,234.5USD', '345GBP']:

  • 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. Using your own textCustomComparator you can provide your own logic to decide when to include a row in the filtered results.

The textCustomComparator is a function with the following signature:

(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 off the value getter, otherwise it is the raw value injected into the grid
  • filterText:string The value to filter by.
  • returns:boolean 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 filterTextLoweCase = filterText.toLowerCase(); var valueLowerCase = value.toString().toLowerCase(); switch (filter) { case 'contains': return valueLowerCase.indexOf(filterTextLoweCase) >= 0; case 'notContains': return valueLowerCase.indexOf(filterTextLoweCase) === -1; case 'equals': return valueLowerCase === filterTextLoweCase; case 'notEqual': return valueLowerCase != filterTextLoweCase; case 'startsWith': return valueLowerCase.indexOf(filterTextLoweCase) === 0; case 'endsWith': var index = valueLowerCase.lastIndexOf(filterTextLoweCase); return index >= 0 && index === (valueLowerCase.length - filterTextLoweCase.length); default: // should never happen console.warn('invalid filter type ' + filter); return false; } }

Text Formatter

The grid compares the text filter with the values in a case insensite way, thus 'o' will match 'Olivia' and 'Salmon', however it will not match against 'Bjørk'. If you want to match in any other way (eg you want to makes against accents), or you want to have case sensitive matches, then you should provide your own textFormatter.

The textFormatter is a function with the following signature (gridValue:string):string;

  • gridValue:string The value coming from the grid. This can be the valueGetter if there is any for the column, or the value as originally provided in the rowData
  • returns:string The string to be used for the purpose of filtering.

If no textFormatter is provided the grid will convert the text to lower case. Is important to note that when comparing to the text entered in the filter box, the text in the filter box is converted always to lower case.

The following is an example to remove accents and convert to lower case.

function(s){ var r=s.toLowerCase(); r = r.replace(new RegExp("\\s", 'g'),""); r = r.replace(new RegExp("[àáâãäå]", 'g'),"a"); r = r.replace(new RegExp("æ", 'g'),"ae"); r = r.replace(new RegExp("ç", 'g'),"c"); r = r.replace(new RegExp("[èéêë]", 'g'),"e"); r = r.replace(new RegExp("[ìíîï]", 'g'),"i"); r = r.replace(new RegExp("ñ", 'g'),"n"); r = r.replace(new RegExp("[òóôõö]", 'g'),"o"); r = r.replace(new RegExp("œ", 'g'),"oe"); r = r.replace(new RegExp("[ùúûü]", 'g'),"u"); r = r.replace(new RegExp("[ýÿ]", 'g'),"y"); r = r.replace(new RegExp("\\W", 'g'),""); return r; };

Text Filter Model

Get and set the state of the text filter by getting and setting the model on the filter instance.

// get filter instance var athleteFilterComponent = gridOptions.api.getFilterInstance('athlete'); // get filter model var model = athleteFilterComponent.getModel(); // OR set filter model and update athleteFilterComponent.setModel({ type:'endsWith', filter:'thing' }); athleteFilterComponent.onFilterChanged()

The text filter model has the following attributes:

  • type: The type of text filter to apply. One of: {equals, notEqual, contains, notContains, startsWith, endsWith}
  • filter: The actual filter text to apply.

Floating Text Filter

If your grid has floatingFilter enabled, your columns with text filter will automatically show below the header a new column that will show two elements:

  • Filter input box: This input box serves two purposes:
    1. Lets the user change directly the filtering text that will be used for filtering.
    2. It reflects any change made to the filtering text from anywhere within the application. This includes changes on the rich filter for this column made by the user directly or changes made to the filter through a call to setModel to this filter component
  • Filter button: This button is a shortcut to show the rich filter editor

Example

  • 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 0ms debounceMs:0 in the column filter menu. The floating filter has the default 500ms
  • The athlete column filter is case sensitive, note that it has the following flag: caseSensitive:true
  • The country column has only one filter option: filterOptions=['contains']
  • The country column has a textCustomComparator so that there are aliases that can be entered in the filter ie: if you filter using the text 'usa' it will match United States or 'holland' will match 'Netherlands'
  • The country column has a debounce of 2000ms debounceMs:2000 in the column filter menu. The floating filter has the default 500ms
  • The year column has one filter option filterOptions=['inRange'].
  • The sports column has a different default option defaultOption='startsWith'

Common Column Filtering Functionality And Examples

The following can be found in the column filtering documentation page

  • Common filtering params
  • Enabling/Disabling filtering in a column
  • Enabling/Disabling floating filter
  • Adding apply and clear button to a column filter
  • Filtering animation
  • Examples