Tutorial: Searching


The search plugin provides an easy interface to search data across Handsontable.

You should first enable the plugin by setting the search option to search. When enabled, searchPlugin exposes a new method query(queryStr), where queryStr is a string to find within the table. By default, the search is case insensitive.

query(queryStr, [callback], [queryMethod]) method does 2 things. First of all, it returns an array of search results. Every element is an objects containing 3 properties:

  • row – index of the row where the value has been found
  • col – index of the column where the value has been found
  • data – the value that has been found

The second thing the query does is set the isSearchResult property for each cell. If a cell is in search results, then its isSearchResult is set to true, otherwise the property is set to false.

All you have to do now, is use the query() method inside search input listener and you're done.

Search result class

By default the searchPlugin adds htSearchResult class to every cell which isSearchResult property is true. You can change this class using searchResultClass option.

If you wish to change the result class globally (for all Handsontable instances on the page), you can use the Handsontable.Search.global.setDefaultSearchResultClass(className) method.

Custom queryMethod

The queryMethod is responsible for determining whether a queryStr matches the value stored in a cell. It takes 2 arguments: queryStr and cellData. The first is a string passed to query() method. The second is a value returned by getDataAtCell(). The queryMethod function should return true if there is a match.

The default queryMethod is dead simple:

      Handsontable.Search.DEFAULT_QUERY_METHOD = function (query, value) {
  if (typeof query == 'undefined' || query == null || !query.toLowerCase || query.length === 0) {
    return false;

  return value.toString().toLowerCase().indexOf(query.toLowerCase()) !== -1;

If you want to change the queryMethod, use queryMethod option. You can also pass the queryMethod as the third argument of query() method. To change the queryMethod globally, use Handsontable.Search.global.setDefaultQueryMethod(queryMethod).

Custom result callback

After calling queryMethod searchPlugin calls callback(instance, rowIndex, colIndex, cellData, testResult) for every cell.

Just as the queryMethod, you can override this callback globally, using Handsontable.Search.global.setDefaultCallback(), you can set different callbacks particular Handsontable instances using callback option, or pass the callback as the second argument of query() method.

The default callback is responsible for setting the isSearchResult property, so if you want to preserve this functionality, be sure to invoke Handsontable.Search.DEFAULT_CALLBACK inside your custom callback.

      Handsontable.Search.DEFAULT_CALLBACK = function(instance, row, col, data, testResult) {
  instance.getCellMeta(row, col).isSearchResult = testResult;

Find the following examples below:

Edit this page

Simplest use case

Custom search result class

Custom query method

Custom callback

0 results