Search

Description

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

In order to enable search mechanism, Options#search option must be set to true.

Example

// as boolean
search: true
// as a object with one or more options
search: {
  callback: myNewCallbackFunction,
  queryMethod: myNewQueryMethod,
  searchResultClass: 'customClass'
}

// Access to search plugin instance:
const searchPlugin = hot.getPlugin('search');

// Set callback programmatically:
searchPlugin.setCallback(myNewCallbackFunction);
// Set query method programmatically:
searchPlugin.setQueryMethod(myNewQueryMethod);
// Set search result cells class programmatically:
searchPlugin.setSearchResultClass(customClass);

Options

search

Ask AI

Source code

search.search : boolean | object

The search option enables and configures the Search plugin.

Setting	Description
false (default)	Disable the Search plugin
true	Enable the Search plugin with the default configuration
An object	Enable the Search plugin and apply a custom configuration

When set to an object, the following properties are supported:

Property	Type	Default	Description
searchResultClass	string	'htSearchResult'	CSS class name applied to every cell where isSearchResult === true.
queryMethod	Function	Case-insensitive substring match	Tests whether the query string matches a cell value. Signature: (queryStr: string, value: string|number|null, cellProperties: object) => boolean.
callback	Function	Sets isSearchResult on cell metadata	Called for every cell after each test. Signature: (instance: Handsontable, row: number, col: number, data: string|number|null, testResult: boolean) => void.

Default queryMethod behavior: case-insensitive, locale-aware substring match using toLocaleLowerCase() with cellProperties.locale.

Default callback behavior: sets instance.getCellMeta(row, col).isSearchResult = testResult on every cell.

Per-cell overrides: queryMethod and callback can also be set on individual cells, columns, or rows using the cascading configuration model. A cell-level search.queryMethod or search.callback takes precedence over the plugin-level setting for that cell. searchResultClass does not support per-cell overrides.

Read more:

• Searching values
• Custom query method
• Custom callback
• Per-cell overrides

Default: false
Example

// Enable with the default configuration
search: true,

// Enable with a custom configuration
search: {
  // Apply a custom CSS class to matching cells instead of 'htSearchResult'
  searchResultClass: 'customClass',
  // Replace the built-in substring match with exact matching
  queryMethod(queryStr, value, cellProperties) {
    if (!queryStr || queryStr.length === 0) return false;
    if (value === undefined || value === null) return false;

    return queryStr.toString() === value.toString();
  },
  // Count results while preserving default highlighting
  callback(instance, row, col, data, testResult) {
    // Preserve the default isSearchResult flag so highlighting still works
    instance.getCellMeta(row, col).isSearchResult = testResult;

    if (testResult) {
      // Custom logic: e.g., increment a result counter
    }
  }
},

// Override queryMethod for a specific column only (per-cell via cascading config)
columns: [
  {},
  {
    search: {
      queryMethod(queryStr, value) {
        return queryStr.toString() === value.toString(); // exact match for column 1
      }
    }
  }
],

Methods

destroy

Ask AI

Source code

search.destroy()

Destroys the plugin instance.

disablePlugin

Ask AI

Source code

search.disablePlugin()

Disables the plugin functionality for this Handsontable instance.

enablePlugin

Ask AI

Source code

search.enablePlugin()

Enables the plugin functionality for this Handsontable instance.

getCallback

Ask AI

Source code

search.getCallback() ⇒ function

Gets the callback function.

Returns: function - Return the callback function.

getQueryMethod

Ask AI

Source code

search.getQueryMethod() ⇒ function

Gets the query method function.

Returns: function - Return the query method.

getSearchResultClass

Ask AI

Source code

search.getSearchResultClass() ⇒ string

Gets search result cells class name.

Returns: string - Return the cell class name.

isEnabled

Ask AI

Source code

search.isEnabled() ⇒ boolean

Checks if the plugin is enabled in the handsontable settings. This method is executed in Hooks#beforeInit hook and if it returns true then the AutoRowSize#enablePlugin method is called.

query

Ask AI

Source code

search.query(queryStr, [callback], [queryMethod]) ⇒ Array<object>

Makes the query.

Param	Type	Description
queryStr	string	Value to be search.
[callback]	function	optional Callback function performed on cells with values which matches to the searched query.
[queryMethod]	function	optional Query function responsible for determining whether a query matches the value stored in a cell.

Returns: Array<object> - Return an array of objects with row, col, data properties or empty array.

setCallback

Ask AI

Source code

search.setCallback(newCallback)

Sets the callback function. This function will be called during querying for each cell.

Param	Type	Description
newCallback	function	A callback function.

setQueryMethod

Ask AI

Source code

search.setQueryMethod(newQueryMethod)

Sets the query method function. The function is responsible for determining whether a query matches the value stored in a cell.

Param	Type	Description
newQueryMethod	function	A function with specific match logic.

setSearchResultClass

Ask AI

Source code

search.setSearchResultClass(newElementClass)

Sets search result cells class name. This class name will be added to each cell that belongs to the searched query.

Param	Type	Description
newElementClass	string	CSS class name.

updatePlugin

Ask AI

Source code

search.updatePlugin()

Updates the plugin’s state.

This method is executed when updateSettings() is invoked with any of the following configuration options:

• search