Notes

  • In v2.29.1, a data.matchedOn value was added. See the How to add Custom filter types section below.
  • In v2.22.0, additional values were added to the data parameter as it is now provided as a parameter to all filter_functions. See the "How to add Custom filter types" section below to review the new additions.
  • Notice! In version v2.17.8, some drastic changes were made to the way variables are passed to the filters. Please check out the "How to add Custom Filter types" section below.
  • This demo was added in v2.17.5, but modification using these instructions works for v2.13.3+; when the filter widget was restructured to allow the adding of custom filter search types.
  • In this demo, two additional search types have been added as an example
    • Start a search from beginning of the content using the ^ designator.
    • Search for a specific ending in the content using the $ designator.
  • Please review the following sections for more details.

Built-in Filters

The built-in filter search types include:
PriorityTypeDesignatorFunction
1regex/./mig$.tablesorter.filter.types.regex
2operators< <= >= >$.tablesorter.filter.types.operators
3not! or !=$.tablesorter.filter.types.notMatch
4exact" or =$.tablesorter.filter.types.exact
5and &&  or  and $.tablesorter.filter.types.and
6range -  or  to $.tablesorter.filter.types.range
7wild* or ?$.tablesorter.filter.types.wild
7or| or  or $.tablesorter.filter.types.wild (built-into wild)
8fuzzy~$.tablesorter.filter.types.fuzzy

How to add Custom filter types

  • The first step is to decide what you want your filter to do.
  • Should it look for a symbol at the beginning, middle or end of the filter?
  • Does the designator need spaces around it (e.g. " and " or " or ") to prevent problems? You wouldn't be able to find the country of "Andorra" if the "and" or "or" designators didn't require spaces.
  • Make sure to name your filter so that it doesn't interfere with already existing ones, unless your filter is meant to replace an existing one. See the "Built-in Filters" section for a full list of filter function names.
  • Changed in v2.17.8, only two parameters are passed to the filter type function:
    $.tablesorter.filter.types.myNewFilter = function( config, data ) { /* ... */ }
    • config - tablesorter config containing all variables (table.config)
    • data - filter data containing all filter variables. All variables are listed below.

  • Within your filter, first test for your designator symbol.
    • If it exists within the filter, then do your comparison and return a boolean of true or false.
    • The following arguments are passed within the data parameter to both the filter_function & filter type function (changed in v2.22.0):
      • data.$row - The jQuery object of the current row being processed by the filter widget; added v2.22.0.
      • data.$cells - A jQuery object containing all the table cells in the current row being processed; added v2.22.0.
      • data.filters - Array of filters for all columns (some array values may be undefined); added v2.22.0.

      • data.filter - The exact text from the filter input (e.g. ^h).
      • data.iFilter - The text from the filter in all lower case for case insensitive searches, if table.config.widgetOptions.filter_ignoreCase is true.
      • data.exact - The exact (or parsed) text from the current table cell, or the entire row if data.anyMatch is true; the parsed text is passed when the column has a "filter-parsed" class name set.
      • data.iExact - The exact (or parsed) text in all lower case for case insensitive searches, if table.config.widgetOptions.filter_ignoreCase is true.

      • data.rowIndex (v2.27.0) - The current row index (zero-based) being filtered. This index includes hidden rows and only applies to the rows currently in the DOM in their current unsorted/sorted state.
      • data.index - The current column index (zero-based) being filtered. When performing an "any match", this index is equal to config.columns which is the last column of the table plus one.
      • data.cache - The parsed text from the current table cell, or the entire row if data.anyMatch is true. This value will be in all lower case if config.ignoreCase is true.

      • data.anyMatch - This is a boolean value indicating when the data.exact and data.iExact parameters contain data from the entire row instead of one cell. This value will always be false if the table does not include an associated any match filter.

      • data.rawArray - An array of raw content extracted from each table cell in the row being processed; added v2.22.0.
      • data.rowArray - An array of the modified exact text from each table cell in the current row being processed. The content will be in all lower case, if the table.config.ignoreCase option is true & accents replaced if the table.config.sortLocaleCompare option is true).
      • data.cacheArray - An array of parsed content from each table cell in the row being processed.
      • data.childRowText - contains all text from any associated child rows.
      • data.parsed - An array of boolean flags that indicate if the column data should be obtained from parsed values, or not; obtained from filter_useParsedData setting or filter-parsed classes on the header cells.

      • data.matchedOn - The name of the filter type function (see the Built-in Filters section above for a list) that returned a match, either true or false. If no type was matched, it will contain a null value; added v2.29.1.

    • If your designator doesn't exist, you *must* return null to allow comparisons with other filter types.

  • Here is a basic example with extensive comments:
    // search for a match from the beginning of a string
    // "^l" matches "lion" but not "koala"
    $.tablesorter.filter.types.start = function( config, data ) {
    	// test for filter type designator. In this example, "^" must be at the beginning of the filter
    	// for this test, the use of the case insensitive "iFilter" variable
    	// doesn't matter since we are only looking at the symbol
    	if ( /^\^/.test( data.iFilter ) ) {
    		// test the table content (exact or parsed) against the filter
    		// * Don't forget to remove the designator first ( the substring(1) part ), so "^h".substring(1) becomes "h"
    		// * In this case, we do care about using "iFilter" since we're comparing it with "iExact"
    		// * We use "indexOf" so that we know the match starts from the beginning of the string.
    		// * Your function should return a boolean indicating a match, or not.
    		return data.iExact.indexOf( data.iFilter.substring(1) ) === 0;
    	}
    	// ALWAYS return null if your custom filter type doesn't match
    	return null;
    };

How to remove filter types

  • If one of the built-in search types is interfering or bothersome to your users, then you can remove it using the following command (using fuzzy search as an example):
    $(function() {
    
    	// Remove fuzzy search
    	delete $.tablesorter.filter.types.fuzzy;
    
    	$('table').tablesorter({
    		theme: 'blue',
    		widgets: ['filter']
    	});
    
    });
  • The full list of built-in filter type functions can be found in the "Built-in Filters" section.

Localization

You can change the language of the searches used within the filter widget. This only applies to the "and", "or" and "to" (range) searches. For example, to change the localization to French, do the following:
// add French support
$.extend($.tablesorter.language, {
	to  : 'à',
	or  : 'ou',
	and : 'et'
});
This results in searches that can be performed as follows:
  • "and" search: Pierre et Franc or Pierre && Franc.
  • "or" search: Marie ou Claudette or Marie|Claudette
  • "to" search: 10 à 20 or 10 - 20
Note the symbolic searches never changed ( && , | and  - )
Important Even though the language settings don't include spaces, the user is still required to enter spaces in the filter to perform these searches, e.g. 1 à 10 (shows rows with numbers between 1 and 10).
If you want to support multiple languages, separate the language variables with a vertical bar (|, Shift + \):
// add French & Spanish support
$.extend($.tablesorter.language, {
	to  : 'à|a',
	or  : 'ou|o',
	and : 'et|y'
});

Demo

(beginning of word)
(end of word)

First NameLast NameCityAgeTotalDiscountDate
AaronJohnson SrAtlanta35$5.9522%Jun 26, 2004 7:22 AM
AaronJohnsonYuma12$2.995%Aug 21, 2009 12:21 PM
ClarkHenry JrTampa51$42.2918%Oct 13, 2000 1:15 PM
DenniHenryNew York28$9.9920%Jul 6, 2006 8:14 AM
JohnHoodBoston33$19.9925%Dec 10, 2002 5:14 AM
ClarkKent SrLos Angeles18$15.8944%Jan 12, 2003 11:14 AM
PeterKent EsqSeattle45$153.1944%Jan 18, 2021 9:12 AM
PeterJohnsMilwaukee13$5.294%Jan 8, 2012 5:11 PM
AaronEvanChicago24$14.1914%Jan 14, 2004 11:23 AM
BruceEvansUpland22$13.1911%Jan 18, 2007 9:12 AM
ClarkMcMastersPheonix18$55.2015%Feb 12, 2010 7:23 PM
DennisMastersIndianapolis65$123.0032%Jan 20, 2001 1:12 PM
JohnHoodFort Worth25$22.0917%Jun 11, 2011 10:55 AM

Javascript


	

HTML


	

Next up: Custom Filter Widget Search Types (example 2) ››