Searching values

Search data across Handsontable using the built-in API methods of the Search plugin, and implement your own search UI.

Overview

The Search plugin lets you scan all cells in the grid and get back a list of matches. Enable it by setting the search option to true or to a configuration object.

Once enabled, the plugin exposes the query(queryStr) method. Call it with a search string whenever the user types. By default, the search is case-insensitive and matches partial cell values.

How `query()` works

Calling query(queryStr, [callback], [queryMethod]) does two things:

Iterates over every cell in the grid and tests each one using the queryMethod.
After each test, calls the callback to update cell metadata (isSearchResult).

It returns an array of result objects - one for each matching cell:

Property	Type	Description
`row`	`number`	Visual row index of the matching cell
`col`	`number`	Visual column index of the matching cell
`data`	`string\|number\|null`	Value of the matching cell

After calling query(), call hot.render() to refresh visual highlighting.

Search result class

After query() runs, every cell where isSearchResult === true automatically receives the CSS class htSearchResult. You can replace this class in two ways:

At initialization: set search: { searchResultClass: 'my-class' }
Programmatically: call hot.getPlugin('search').setSearchResultClass('my-class')

Custom `queryMethod`

The queryMethod function determines whether the query string matches a cell value. It is called once per cell during every query() call.

Signature:

1
function queryMethod(query, value, cellProperties) {
2
  // return true for a match, false otherwise
3
}

Parameter	Type	Description
`query`	`string`	The search string passed to `query()`
`value`	`string\|number\|null`	The cell value (from `getDataAtCell()`)
`cellProperties`	`object`	The cell’s metadata object (includes `locale`, `type`, and other cell options)

The built-in default performs a case-insensitive, locale-aware substring match:

1
function defaultQueryMethod(query, value, cellProperties) {
2
  if (query === undefined || query === null || query.length === 0) {
3
    return false;
4
  }
5
  if (value === undefined || value === null) {
6
    return false;
7
  }
8

9
  return value.toString().toLocaleLowerCase(cellProperties.locale)
10
    .indexOf(query.toLocaleLowerCase(cellProperties.locale)) !== -1;
11
}

You can set a custom query method in three ways:

At initialization: search: { queryMethod: myQueryMethod }
Programmatically: hot.getPlugin('search').setQueryMethod(myQueryMethod)
Per query() call: searchPlugin.query(queryStr, callback, myQueryMethod) (applies to that call only)

Custom result callback

The callback function is called for every cell during a query() run, whether or not the cell matches. It is responsible for updating cell metadata so the renderer knows which cells to highlight.

Signature:

1
function callback(instance, row, col, data, testResult) {
2
  // update cell metadata based on testResult
3
}

Parameter	Type	Description
`instance`	`Handsontable`	The Handsontable instance
`row`	`number`	Visual row index
`col`	`number`	Visual column index
`data`	`string\|number\|null`	The cell value
`testResult`	`boolean`	`true` if the cell matches the query, `false` otherwise

The built-in default sets the isSearchResult flag on each cell’s metadata:

1
function defaultCallback(instance, row, col, data, testResult) {
2
  instance.getCellMeta(row, col).isSearchResult = testResult;
3
}

If you override the callback to add custom logic (for example, to count results), call the default behavior manually so that cell highlighting still works.

You can set a custom callback in three ways:

At initialization: search: { callback: myCallback }
Programmatically: hot.getPlugin('search').setCallback(myCallback)
Per query() call: searchPlugin.query(queryStr, myCallback) (applies to that call only)

Per-cell `queryMethod` and `callback`

Both queryMethod and callback can be overridden for individual cells, columns, or rows using Handsontable’s cascading configuration model. Set a search object directly in a cell, columns, or rows entry:

1
handsontable({
2
  data: myData,
3
  search: true,
4
  columns: [
5
    {},
6
    // Column 1: exact match only, everything else uses the global queryMethod
7
    {
8
      search: {
9
        queryMethod(queryStr, value) {
10
          return queryStr.toString() === value.toString();
11
        }
12
      }
13
    }
14
  ]
15
});

You can also set it programmatically on a specific cell using setCellMeta():

1
hot.setCellMeta(row, col, 'search', {
2
  queryMethod(queryStr, value) {
3
    return queryStr.toString() === value.toString();
4
  }
5
});

Per-cell settings take precedence over the plugin-level queryMethod and callback. Only queryMethod and callback support per-cell overrides - searchResultClass does not.

Simplest use case

The example below:

Enables the Search plugin by setting search to true
Listens for keyup events on a search input
Calls query() on each keystroke and re-renders the grid to apply highlighting

1
/* file: app.component.ts */
2
import { Component, ViewChild } from '@angular/core';
3
import { GridSettings, HotTableComponent } from '@handsontable/angular-wrapper';
4

5
@Component({
6
  selector: 'example1-searching-values',
7
  standalone: false,
8
  template: ` <div class="example-controls-container">
9
      <div class="controls">
10
        <input
11
          id="search_field"
12
          type="search"
13
          placeholder="Search"
14
          (keyup)="searchFieldKeyup($event)"
15
        />
16
      </div>
17
    </div>
18
    <div>
19
      <hot-table [data]="data" [settings]="gridSettings"></hot-table>
20
    </div>`,
21
})
22
export class Example1SearchingValuesComponent {
23
  @ViewChild(HotTableComponent, { static: false }) readonly hotTable!: HotTableComponent;
24

25
  readonly data: Array<Array<string | number>> = [
26
    ['Tesla', 2017, 'black', 'black'],
27
    ['Nissan', 2018, 'blue', 'blue'],
28
    ['Chrysler', 2019, 'yellow', 'black'],
29
    ['Volvo', 2020, 'yellow', 'gray'],
30
  ];
31

32
  readonly gridSettings: GridSettings = {
33
    colHeaders: true,
34
    search: true,
35
    height: 'auto',
36
    autoWrapRow: true,
37
    autoWrapCol: true
38
  };
39

40
  searchFieldKeyup(event: KeyboardEvent): void {
41
    const hot = this.hotTable?.hotInstance;
42
    // get the `Search` plugin's instance
43
    const search = hot?.getPlugin('search');
44
    // use the `Search` plugin's `query()` method
45
    const queryResult = search?.query((event.target as any).value);
46

47
    console.log(queryResult);
48

49
    hot?.render();
50
  }
51
}
52
/* end-file */
53

54

55
/* file: app.module.ts */
56
import { NgModule, ApplicationConfig } from '@angular/core';
57
import { BrowserModule } from '@angular/platform-browser';
58
import { registerAllModules } from 'handsontable/registry';
59
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, HotTableModule } from '@handsontable/angular-wrapper';
60
import { CommonModule } from '@angular/common';
61
import { NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
62
/* start:skip-in-compilation */
63
import { Example1SearchingValuesComponent } from './app.component';
64
/* end:skip-in-compilation */
65

66
// register Handsontable's modules
67
registerAllModules();
68

69
export const appConfig: ApplicationConfig = {
70
  providers: [
71
    {
72
      provide: HOT_GLOBAL_CONFIG,
73
      useValue: {
74
        license: NON_COMMERCIAL_LICENSE,
75
      } as HotGlobalConfig
76
    }
77
  ],
78
};
79

80
@NgModule({
81
  imports: [ BrowserModule, HotTableModule, CommonModule ],
82
  declarations: [ Example1SearchingValuesComponent ],
83
  providers: [...appConfig.providers],
84
  bootstrap: [ Example1SearchingValuesComponent ]
85
})
86

87
export class AppModule { }
88
/* end-file */

1
<div>
2
  <example1-searching-values></example1-searching-values>
3
</div>

Custom search result class

You can style search results with a custom CSS class, using the Search plugin’s searchResultClass option.

The example below highlights search results with a pink background and red text. To do this, it:

Defines a custom CSS class called my-class, scoped to .ht-theme-main .handsontable
Enables the Search plugin with a configuration object
Sets searchResultClass to 'my-class'

1
/* file: app.component.ts */
2
import { Component, ViewChild, ViewEncapsulation } from '@angular/core';
3
import { GridSettings, HotTableComponent } from '@handsontable/angular-wrapper';
4

5
@Component({
6
  selector: 'example2-searching-values',
7
  standalone: false,
8
  template: ` <div class="example-controls-container">
9
      <div class="controls">
10
        <input
11
          id="search_field2"
12
          type="search"
13
          placeholder="Search"
14
          (keyup)="searchFieldKeyup($event)"
15
        />
16
      </div>
17
    </div>
18
    <div>
19
      <hot-table [data]="data" [settings]="gridSettings"></hot-table>
20
    </div>`,
21
  styles: `.ht-theme-main .handsontable .my-class {
22
      background: pink;
23
      color: red;
24
    }`,
25
  encapsulation: ViewEncapsulation.None,
26
})
27
export class Example2SearchingValuesComponent {
28
  @ViewChild(HotTableComponent, { static: false }) readonly hotTable!: HotTableComponent;
29

30
  readonly data: Array<Array<string | number>> = [
31
    ['Tesla', 2017, 'black', 'black'],
32
    ['Nissan', 2018, 'blue', 'blue'],
33
    ['Chrysler', 2019, 'yellow', 'black'],
34
    ['Volvo', 2020, 'yellow', 'gray'],
35
  ];
36

37
  readonly gridSettings: GridSettings = {
38
    colHeaders: true,
39
    search: {
40
      searchResultClass: 'my-class',
41
    },
42
    height: 'auto',
43
    autoWrapRow: true,
44
    autoWrapCol: true
45
  };
46

47
  searchFieldKeyup(event: KeyboardEvent): void {
48
    const hot = this.hotTable?.hotInstance;
49
    // get the `Search` plugin's instance
50
    const search = hot?.getPlugin('search');
51
    // use the `Search` plugin's `query()` method
52
    const queryResult = search?.query((event.target as any).value);
53

54
    console.log(queryResult);
55

56
    hot?.render();
57
  }
58
}
59
/* end-file */
60

61

62
/* file: app.module.ts */
63
import { NgModule, ApplicationConfig } from '@angular/core';
64
import { BrowserModule } from '@angular/platform-browser';
65
import { registerAllModules } from 'handsontable/registry';
66
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, HotTableModule } from '@handsontable/angular-wrapper';
67
import { CommonModule } from '@angular/common';
68
import { NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
69
/* start:skip-in-compilation */
70
import { Example2SearchingValuesComponent } from './app.component';
71
/* end:skip-in-compilation */
72

73
// register Handsontable's modules
74
registerAllModules();
75

76
export const appConfig: ApplicationConfig = {
77
  providers: [
78
    {
79
      provide: HOT_GLOBAL_CONFIG,
80
      useValue: {
81
        license: NON_COMMERCIAL_LICENSE,
82
      } as HotGlobalConfig
83
    }
84
  ],
85
};
86

87
@NgModule({
88
  imports: [ BrowserModule, HotTableModule, CommonModule ],
89
  declarations: [ Example2SearchingValuesComponent ],
90
  providers: [...appConfig.providers],
91
  bootstrap: [ Example2SearchingValuesComponent ]
92
})
93

94
export class AppModule { }
95
/* end-file */

1
<div>
2
  <example2-searching-values></example2-searching-values>
3
</div>

Custom query method

You can replace the built-in substring search with a custom query method, using the queryMethod option.

The example below searches only for exact matches. To do this, it:

Defines a custom query method called onlyExactMatch that uses strict equality (===)
Enables the Search plugin with a configuration object
Sets queryMethod to onlyExactMatch

1
/* file: app.component.ts */
2
import { Component, ViewChild } from '@angular/core';
3
import { GridSettings, HotTableComponent } from '@handsontable/angular-wrapper';
4

5
@Component({
6
  selector: 'example3-searching-values',
7
  standalone: false,
8
  template: ` <div class="example-controls-container">
9
      <div class="controls">
10
        <input
11
          id="search_field3"
12
          type="search"
13
          placeholder="Search"
14
          (keyup)="searchFieldKeyup($event)"
15
        />
16
      </div>
17
    </div>
18
    <div>
19
      <hot-table [data]="data" [settings]="gridSettings"></hot-table>
20
    </div>`,
21
})
22
export class Example3SearchingValuesComponent {
23
  @ViewChild(HotTableComponent, { static: false }) readonly hotTable!: HotTableComponent;
24

25
  readonly data: Array<Array<string | number>> = [
26
    ['Tesla', 2017, 'black', 'black'],
27
    ['Nissan', 2018, 'blue', 'blue'],
28
    ['Chrysler', 2019, 'yellow', 'black'],
29
    ['Volvo', 2020, 'yellow', 'gray'],
30
  ];
31

32
  readonly gridSettings: GridSettings = {
33
    colHeaders: true,
34
    search: {
35
      // add your custom query method
36
      queryMethod: this.onlyExactMatch,
37
    },
38
    height: 'auto',
39
    autoWrapRow: true,
40
    autoWrapCol: true
41
  };
42

43
  searchFieldKeyup(event: KeyboardEvent): void {
44
    const hot = this.hotTable?.hotInstance;
45
    // get the `Search` plugin's instance
46
    const search = hot?.getPlugin('search');
47
    // use the `Search` plugin's `query()` method
48
    const queryResult = search?.query((event.target as any).value);
49

50
    console.log(queryResult);
51

52
    hot?.render();
53
  }
54

55
  //  define your custom query method
56
  onlyExactMatch(
57
    queryStr: { toString: () => any },
58
    value: { toString: () => any }
59
  ): boolean {
60
    return queryStr.toString() === value.toString();
61
  }
62
}
63
/* end-file */
64

65

66
/* file: app.module.ts */
67
import { NgModule, ApplicationConfig } from '@angular/core';
68
import { BrowserModule } from '@angular/platform-browser';
69
import { registerAllModules } from 'handsontable/registry';
70
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, HotTableModule } from '@handsontable/angular-wrapper';
71
import { CommonModule } from '@angular/common';
72
import { NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
73
/* start:skip-in-compilation */
74
import { Example3SearchingValuesComponent } from './app.component';
75
/* end:skip-in-compilation */
76

77
// register Handsontable's modules
78
registerAllModules();
79

80
export const appConfig: ApplicationConfig = {
81
  providers: [
82
    {
83
      provide: HOT_GLOBAL_CONFIG,
84
      useValue: {
85
        license: NON_COMMERCIAL_LICENSE,
86
      } as HotGlobalConfig
87
    }
88
  ],
89
};
90

91
@NgModule({
92
  imports: [ BrowserModule, HotTableModule, CommonModule ],
93
  declarations: [ Example3SearchingValuesComponent ],
94
  providers: [...appConfig.providers],
95
  bootstrap: [ Example3SearchingValuesComponent ]
96
})
97

98
export class AppModule { }
99
/* end-file */

1
<div>
2
  <example3-searching-values></example3-searching-values>
3
</div>

Custom callback

You can add a custom callback function, using the Search plugin’s callback option.

The example below displays the number of matching search results. To do this, it:

Defines a custom callback function called searchResultCounter that counts matches and calls the default callback to preserve highlighting
Enables the Search plugin with a configuration object
Sets callback to searchResultCounter

1
/* file: app.component.ts */
2
import { Component, ViewChild } from '@angular/core';
3
import { GridSettings, HotTableComponent } from '@handsontable/angular-wrapper';
4
import Handsontable from 'handsontable/base';
5

6
@Component({
7
  selector: 'example4-searching-values',
8
  standalone: false,
9
  template: ` <div class="example-controls-container">
10
      <div class="controls">
11
        <input
12
          id="search_field3"
13
          type="search"
14
          placeholder="Search"
15
          (keyup)="searchFieldKeyup($event)"
16
        />
17
      </div>
18
      <output class="console" id="output"> {{ resultCount }} results </output>
19
    </div>
20

21
    <div>
22
      <hot-table [data]="data" [settings]="gridSettings"></hot-table>
23
    </div>`,
24
})
25
export class Example4SearchingValuesComponent {
26
  @ViewChild(HotTableComponent, { static: false }) readonly hotTable!: HotTableComponent;
27

28
  readonly data: Array<Array<string | number>> = [
29
    ['Tesla', 2017, 'black', 'black'],
30
    ['Nissan', 2018, 'blue', 'blue'],
31
    ['Chrysler', 2019, 'yellow', 'black'],
32
    ['Volvo', 2020, 'yellow', 'gray'],
33
  ];
34

35
  readonly gridSettings: GridSettings = {
36
    colHeaders: true,
37
    search: {
38
      // add your custom callback function
39
      callback: (
40
        _instance: Handsontable,
41
        _row: number,
42
        _col: number,
43
        _value: any,
44
        result: any
45
      ) => this.searchResultCounter(_instance, _row, _col, _value, result),
46
    },
47
    height: 'auto',
48
    autoWrapRow: true,
49
    autoWrapCol: true
50
  };
51

52
  resultCount = 0;
53

54
  searchFieldKeyup(event: KeyboardEvent): void {
55
    this.setResultCounter(0);
56

57
    const search = this.hotTable?.hotInstance?.getPlugin('search');
58
    const queryResult = search?.query((event.target as any).value);
59

60
    console.log(queryResult);
61

62
    this.hotTable?.hotInstance?.render();
63
  }
64

65
  //  define your custom callback function
66
  searchResultCounter(
67
    _instance: Handsontable,
68
    _row: number,
69
    _col: number,
70
    _value: any,
71
    result: any
72
  ): void {
73
    _instance.getCellMeta(_row, _col).isSearchResult = result;
74
    if (result) {
75
      this.setResultCounter(this.resultCount + 1);
76
    }
77
  }
78

79
  private setResultCounter(count: number): void {
80
    this.resultCount = count;
81
  }
82
}
83
/* end-file */
84

85

86
/* file: app.module.ts */
87
import { NgModule, ApplicationConfig } from '@angular/core';
88
import { BrowserModule } from '@angular/platform-browser';
89
import { registerAllModules } from 'handsontable/registry';
90
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, HotTableModule } from '@handsontable/angular-wrapper';
91
import { CommonModule } from '@angular/common';
92
import { NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
93
/* start:skip-in-compilation */
94
import { Example4SearchingValuesComponent } from './app.component';
95
/* end:skip-in-compilation */
96

97
// register Handsontable's modules
98
registerAllModules();
99

100
export const appConfig: ApplicationConfig = {
101
  providers: [
102
    {
103
      provide: HOT_GLOBAL_CONFIG,
104
      useValue: {
105
        license: NON_COMMERCIAL_LICENSE,
106
      } as HotGlobalConfig
107
    }
108
  ],
109
};
110

111
@NgModule({
112
  imports: [ BrowserModule, HotTableModule, CommonModule ],
113
  declarations: [ Example4SearchingValuesComponent ],
114
  providers: [...appConfig.providers],
115
  bootstrap: [ Example4SearchingValuesComponent ]
116
})
117

118
export class AppModule { }
119
/* end-file */

1
<div>
2
  <example4-searching-values></example4-searching-values>
3
</div>

Configuration options

Plugins

Searching values

Searching values

Overview

How query() works

Search result class

Custom queryMethod

Custom result callback

Per-cell queryMethod and callback

Simplest use case

Custom search result class

Custom query method

Custom callback

Related API reference

How `query()` works

Custom `queryMethod`

Per-cell `queryMethod` and `callback`