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
import { useRef, useCallback } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
const ExampleComponent = () => {
9
  const hotRef = useRef(null);
10
  const data = [
11
    ['Tesla', 2017, 'black', 'black'],
12
    ['Nissan', 2018, 'blue', 'blue'],
13
    ['Chrysler', 2019, 'yellow', 'black'],
14
    ['Volvo', 2020, 'yellow', 'gray'],
15
  ];
16

17
  const searchFieldKeyupCallback = useCallback(
18
    (event) => {
19
      const hot = hotRef.current?.hotInstance;
20
      // get the `Search` plugin's instance
21
      const search = hot?.getPlugin('search');
22
      // use the `Search` plugin's `query()` method
23
      const queryResult = search?.query(event.currentTarget.value);
24

25
      console.log(queryResult);
26
      hot?.render();
27
    },
28
    [hotRef.current]
29
  );
30

31
  return (
32
    <>
33
      <div className="example-controls-container">
34
        <div className="controls">
35
          <input
36
            id="search_field"
37
            type="search"
38
            placeholder="Search"
39
            onKeyUp={(event) => searchFieldKeyupCallback(event)}
40
          />
41
        </div>
42
      </div>
43
      <HotTable
44
        ref={hotRef}
45
        data={data}
46
        colHeaders={true}
47
        search={true}
48
        height="auto"
49
        autoWrapRow={true}
50
        autoWrapCol={true}
51
        licenseKey="non-commercial-and-evaluation"
52
      />
53
    </>
54
  );
55
};
56

57
export default ExampleComponent;

1
import { useRef, useCallback } from 'react';
2
import { HotTable, HotTableRef } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
const ExampleComponent = () => {
9
  const hotRef = useRef<HotTableRef>(null);
10

11
  const data = [
12
    ['Tesla', 2017, 'black', 'black'],
13
    ['Nissan', 2018, 'blue', 'blue'],
14
    ['Chrysler', 2019, 'yellow', 'black'],
15
    ['Volvo', 2020, 'yellow', 'gray'],
16
  ];
17

18
  const searchFieldKeyupCallback = useCallback(
19
    (event: React.KeyboardEvent<HTMLInputElement>) => {
20
      const hot = hotRef.current?.hotInstance;
21
      // get the `Search` plugin's instance
22
      const search = hot?.getPlugin('search');
23
      // use the `Search` plugin's `query()` method
24
      const queryResult = search?.query(event.currentTarget.value);
25

26
      console.log(queryResult);
27

28
      hot?.render();
29
    },
30
    [hotRef.current]
31
  );
32

33
  return (
34
    <>
35
      <div className="example-controls-container">
36
        <div className="controls">
37
          <input
38
            id="search_field"
39
            type="search"
40
            placeholder="Search"
41
            onKeyUp={(event) => searchFieldKeyupCallback(event)}
42
          />
43
        </div>
44
      </div>
45
      <HotTable
46
        ref={hotRef}
47
        data={data}
48
        colHeaders={true}
49
        search={true}
50
        height="auto"
51
        autoWrapRow={true}
52
        autoWrapCol={true}
53
        licenseKey="non-commercial-and-evaluation"
54
      />
55
    </>
56
  );
57
};
58

59
export default ExampleComponent;

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
import { useRef, useCallback } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
const ExampleComponent = () => {
9
  const hotRef = useRef(null);
10
  const data = [
11
    ['Tesla', 2017, 'black', 'black'],
12
    ['Nissan', 2018, 'blue', 'blue'],
13
    ['Chrysler', 2019, 'yellow', 'black'],
14
    ['Volvo', 2020, 'yellow', 'gray'],
15
  ];
16

17
  const searchFieldKeyupCallback = useCallback(
18
    (event) => {
19
      const hot = hotRef.current?.hotInstance;
20
      const search = hot?.getPlugin('search');
21
      const queryResult = search?.query(event.currentTarget.value);
22

23
      console.log(queryResult);
24
      hot?.render();
25
    },
26
    [hotRef.current]
27
  );
28

29
  return (
30
    <>
31
      <div className="example-controls-container">
32
        <div className="controls">
33
          <input
34
            id="search_field2"
35
            type="search"
36
            placeholder="Search"
37
            onKeyUp={(...args) => searchFieldKeyupCallback(...args)}
38
          />
39
        </div>
40
      </div>
41
      <HotTable
42
        ref={hotRef}
43
        data={data}
44
        colHeaders={true}
45
        // enable the `Search` plugin
46
        search={{
47
          // add your custom CSS class
48
          searchResultClass: 'my-class',
49
        }}
50
        height="auto"
51
        autoWrapRow={true}
52
        autoWrapCol={true}
53
        licenseKey="non-commercial-and-evaluation"
54
      />
55
    </>
56
  );
57
};
58

59
export default ExampleComponent;

1
import { useRef, useCallback } from 'react';
2
import { HotTable, HotTableRef } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
const ExampleComponent = () => {
9
  const hotRef = useRef<HotTableRef>(null);
10

11
  const data = [
12
    ['Tesla', 2017, 'black', 'black'],
13
    ['Nissan', 2018, 'blue', 'blue'],
14
    ['Chrysler', 2019, 'yellow', 'black'],
15
    ['Volvo', 2020, 'yellow', 'gray'],
16
  ];
17

18
  const searchFieldKeyupCallback = useCallback(
19
    (event: React.KeyboardEvent<HTMLInputElement>) => {
20
      const hot = hotRef.current?.hotInstance;
21
      const search = hot?.getPlugin('search');
22
      const queryResult = search?.query(event.currentTarget.value);
23

24
      console.log(queryResult);
25
      hot?.render();
26
    },
27
    [hotRef.current]
28
  );
29

30
  return (
31
    <>
32
      <div className="example-controls-container">
33
        <div className="controls">
34
          <input
35
            id="search_field2"
36
            type="search"
37
            placeholder="Search"
38
            onKeyUp={(...args) => searchFieldKeyupCallback(...args)}
39
          />
40
        </div>
41
      </div>
42
      <HotTable
43
        ref={hotRef}
44
        data={data}
45
        colHeaders={true}
46
        // enable the `Search` plugin
47
        search={{
48
          // add your custom CSS class
49
          searchResultClass: 'my-class',
50
        }}
51
        height="auto"
52
        autoWrapRow={true}
53
        autoWrapCol={true}
54
        licenseKey="non-commercial-and-evaluation"
55
      />
56
    </>
57
  );
58
};
59

60
export default ExampleComponent;

1
.ht-theme-main .handsontable .my-class {
2
  background: pink;
3
  color: red;
4
}

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
import { useRef, useCallback } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
const ExampleComponent = () => {
9
  const hotRef = useRef(null);
10
  const data = [
11
    ['Tesla', 2017, 'black', 'black'],
12
    ['Nissan', 2018, 'blue', 'blue'],
13
    ['Chrysler', 2019, 'yellow', 'black'],
14
    ['Volvo', 2020, 'white', 'gray'],
15
  ];
16

17
  const searchFieldKeyupCallback = useCallback(
18
    (event) => {
19
      const hot = hotRef.current?.hotInstance;
20
      const search = hot?.getPlugin('search');
21
      // use the `Search`'s `query()` method
22
      const queryResult = search?.query(event.currentTarget.value);
23

24
      console.log(queryResult);
25
      hot?.render();
26
    },
27
    [hotRef.current]
28
  );
29

30
  //  define your custom query method
31
  function onlyExactMatch(queryStr, value) {
32
    return queryStr.toString() === value.toString();
33
  }
34

35
  return (
36
    <>
37
      <div className="example-controls-container">
38
        <div className="controls">
39
          <input
40
            id="search_field3"
41
            type="search"
42
            placeholder="Search"
43
            onKeyUp={(...args) => searchFieldKeyupCallback(...args)}
44
          />
45
        </div>
46
      </div>
47
      <HotTable
48
        ref={hotRef}
49
        data={data}
50
        colHeaders={true}
51
        // enable the `Search` plugin
52
        search={{
53
          // add your custom query method
54
          queryMethod: onlyExactMatch,
55
        }}
56
        height="auto"
57
        autoWrapRow={true}
58
        autoWrapCol={true}
59
        licenseKey="non-commercial-and-evaluation"
60
      />
61
    </>
62
  );
63
};
64

65
export default ExampleComponent;

1
import { useRef, useCallback } from 'react';
2
import { HotTable, HotTableRef } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
const ExampleComponent = () => {
9
  const hotRef = useRef<HotTableRef>(null);
10

11
  const data = [
12
    ['Tesla', 2017, 'black', 'black'],
13
    ['Nissan', 2018, 'blue', 'blue'],
14
    ['Chrysler', 2019, 'yellow', 'black'],
15
    ['Volvo', 2020, 'white', 'gray'],
16
  ];
17

18
  const searchFieldKeyupCallback = useCallback(
19
    (event: React.KeyboardEvent<HTMLInputElement>) => {
20
      const hot = hotRef.current?.hotInstance;
21
      const search = hot?.getPlugin('search');
22
      // use the `Search`'s `query()` method
23
      const queryResult = search?.query(event.currentTarget.value);
24

25
      console.log(queryResult);
26

27
      hot?.render();
28
    },
29
    [hotRef.current]
30
  );
31

32
  //  define your custom query method
33
  function onlyExactMatch(queryStr: { toString: () => any }, value: { toString: () => any }) {
34
    return queryStr.toString() === value.toString();
35
  }
36

37
  return (
38
    <>
39
      <div className="example-controls-container">
40
        <div className="controls">
41
          <input
42
            id="search_field3"
43
            type="search"
44
            placeholder="Search"
45
            onKeyUp={(...args) => searchFieldKeyupCallback(...args)}
46
          />
47
        </div>
48
      </div>
49
      <HotTable
50
        ref={hotRef}
51
        data={data}
52
        colHeaders={true}
53
        // enable the `Search` plugin
54
        search={{
55
          // add your custom query method
56
          queryMethod: onlyExactMatch,
57
        }}
58
        height="auto"
59
        autoWrapRow={true}
60
        autoWrapCol={true}
61
        licenseKey="non-commercial-and-evaluation"
62
      />
63
    </>
64
  );
65
};
66

67
export default ExampleComponent;

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
import { useRef, useState } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
const ExampleComponent = () => {
9
  const hot4Ref = useRef(null);
10
  const [resultCount, setResultCounter] = useState(0);
11
  const data = [
12
    ['Tesla', 2017, 'black', 'black'],
13
    ['Nissan', 2018, 'blue', 'blue'],
14
    ['Chrysler', 2019, 'yellow', 'black'],
15
    ['Volvo', 2020, 'white', 'gray'],
16
  ];
17

18
  //  define your custom callback function
19
  function searchResultCounter(_instance, _row, _col, _value, result) {
20
    const DEFAULT_CALLBACK = function (instance, row, col, _data, testResult) {
21
      instance.getCellMeta(row, col).isSearchResult = testResult;
22
    };
23

24
    DEFAULT_CALLBACK.apply(this, arguments);
25

26
    if (result) {
27
      setResultCounter((count) => count + 1);
28
    }
29
  }
30

31
  const handleKeyUp = (event) => {
32
    setResultCounter(0);
33

34
    const search = hot4Ref.current?.hotInstance?.getPlugin('search');
35
    const queryResult = search?.query(event.currentTarget.value);
36

37
    console.log(queryResult);
38
    hot4Ref.current?.hotInstance?.render();
39
  };
40

41
  return (
42
    <>
43
      <div className="example-controls-container">
44
        <div className="controls">
45
          <input id="search_field4" type="search" placeholder="Search" onKeyUp={handleKeyUp} />
46
        </div>
47
        <output className="console" id="output">
48
          {resultCount} results
49
        </output>
50
      </div>
51
      <HotTable
52
        ref={hot4Ref}
53
        data={data}
54
        colHeaders={true}
55
        // enable the `Search` plugin
56
        search={{
57
          // add your custom callback function
58
          callback: searchResultCounter,
59
        }}
60
        height="auto"
61
        autoWrapRow={true}
62
        autoWrapCol={true}
63
        licenseKey="non-commercial-and-evaluation"
64
      />
65
    </>
66
  );
67
};
68

69
export default ExampleComponent;

1
import { useRef, useState } from 'react';
2
import { HotTable, HotTableRef } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4
import Handsontable from 'handsontable/base';
5

6
// register Handsontable's modules
7
registerAllModules();
8

9
const ExampleComponent = () => {
10
  const hot4Ref = useRef<HotTableRef>(null);
11
  const [resultCount, setResultCounter] = useState(0);
12

13
  const data = [
14
    ['Tesla', 2017, 'black', 'black'],
15
    ['Nissan', 2018, 'blue', 'blue'],
16
    ['Chrysler', 2019, 'yellow', 'black'],
17
    ['Volvo', 2020, 'white', 'gray'],
18
  ];
19

20
  //  define your custom callback function
21
  function searchResultCounter(
22
    this: Handsontable,
23
    _instance: Handsontable,
24
    _row: number,
25
    _col: number,
26
    _value: any,
27
    result: any
28
  ) {
29
    const DEFAULT_CALLBACK = function (instance: Handsontable, row: number, col: number, _data: any, testResult: any) {
30
      instance.getCellMeta(row, col).isSearchResult = testResult;
31
    };
32

33
    DEFAULT_CALLBACK.apply(this, arguments as any);
34

35
    if (result) {
36
      setResultCounter((count) => count + 1);
37
    }
38
  }
39

40
  const handleKeyUp = (event: React.KeyboardEvent<HTMLInputElement>) => {
41
    setResultCounter(0);
42

43
    const search = hot4Ref.current?.hotInstance?.getPlugin('search');
44
    const queryResult = search?.query(event.currentTarget.value);
45

46
    console.log(queryResult);
47

48
    hot4Ref.current?.hotInstance?.render();
49
  };
50

51
  return (
52
    <>
53
      <div className="example-controls-container">
54
        <div className="controls">
55
          <input id="search_field4" type="search" placeholder="Search" onKeyUp={handleKeyUp} />
56
        </div>
57
        <output className="console" id="output">
58
          {resultCount} results
59
        </output>
60
      </div>
61
      <HotTable
62
        ref={hot4Ref}
63
        data={data}
64
        colHeaders={true}
65
        // enable the `Search` plugin
66
        search={{
67
          // add your custom callback function
68
          callback: searchResultCounter,
69
        }}
70
        height="auto"
71
        autoWrapRow={true}
72
        autoWrapCol={true}
73
        licenseKey="non-commercial-and-evaluation"
74
      />
75
    </>
76
  );
77
};
78

79
export default ExampleComponent;

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`