Highlight search matches

In this tutorial, you will highlight matched text fragments inside cells using a custom renderer. You will learn how to wrap matching substrings in  tags safely and keep the highlights in sync with an external search input.

1
import { useRef } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4
import { rendererFactory } from 'handsontable/renderers';
5

6
registerAllModules();
7

8
const data = [
9
  { id: 101, title: 'Search API docs', owner: 'Alex', status: 'In progress' },
10
  { id: 102, title: 'Renderer refactor', owner: 'Mia', status: 'Review' },
11
  { id: 103, title: 'Fix keyboard shortcut', owner: 'Noah', status: 'Done' },
12
  { id: 104, title: 'Search UX tests', owner: 'Ava', status: 'In progress' },
13
];
14

15
let currentSearchTerm = '';
16

17
function escapeRegExp(value) {
18
  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
19
}
20

21
function escapeHtml(value) {
22
  return value
23
    .replace(/&/g, '&amp;')
24
    .replace(/</g, '&lt;')
25
    .replace(/>/g, '&gt;')
26
    .replace(/"/g, '&quot;')
27
    .replace(/'/g, '&#39;');
28
}
29

30
const highlightRenderer = rendererFactory(({ td, value, cellProperties }) => {
31
  const cellText = value === null || value === undefined ? '' : String(value);
32
  const query = currentSearchTerm.trim();
33

34
  if (!query || !cellProperties.isSearchResult) {
35
    td.textContent = cellText;
36
    return;
37
  }
38

39
  const splitter = new RegExp(`(${escapeRegExp(query)})`, 'gi');
40
  const highlighted = cellText
41
    .split(splitter)
42
    .map((fragment) =>
43
      fragment.toLocaleLowerCase() === query.toLocaleLowerCase()
44
        ? `<mark>${escapeHtml(fragment)}</mark>`
45
        : escapeHtml(fragment)
46
    )
47
    .join('');
48

49
  td.innerHTML = highlighted;
50
});
51

52
const ExampleComponent = () => {
53
  const hotRef = useRef(null);
54

55
  function handleSearchInput(e) {
56
    const hot = hotRef.current?.hotInstance;
57

58
    if (!hot) {
59
      return;
60
    }
61

62
    currentSearchTerm = e.target.value;
63
    hot.getPlugin('search').query(currentSearchTerm);
64
    hot.render();
65
  }
66

67
  return (
68
    <div>
69
      <div className="example-controls-container">
70
        <div className="controls">
71
          <input
72
            type="search"
73
            placeholder="Search tasks"
74
            onInput={handleSearchInput}
75
          />
76
        </div>
77
      </div>
78
      <HotTable
79
        ref={hotRef}
80
        data={data}
81
        colHeaders={['ID', 'Title', 'Owner', 'Status']}
82
        rowHeaders={true}
83
        height="auto"
84
        search={true}
85
        columns={[
86
          { data: 'id', type: 'numeric' },
87
          { data: 'title', renderer: highlightRenderer },
88
          { data: 'owner', renderer: highlightRenderer },
89
          { data: 'status', renderer: highlightRenderer },
90
        ]}
91
        licenseKey="non-commercial-and-evaluation"
92
      />
93
    </div>
94
  );
95
};
96

97
export default ExampleComponent;

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

6
registerAllModules();
7

8
const data = [
9
  { id: 101, title: 'Search API docs', owner: 'Alex', status: 'In progress' },
10
  { id: 102, title: 'Renderer refactor', owner: 'Mia', status: 'Review' },
11
  { id: 103, title: 'Fix keyboard shortcut', owner: 'Noah', status: 'Done' },
12
  { id: 104, title: 'Search UX tests', owner: 'Ava', status: 'In progress' },
13
];
14

15
let currentSearchTerm = '';
16

17
function escapeRegExp(value: string): string {
18
  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
19
}
20

21
function escapeHtml(value: string): string {
22
  return value
23
    .replace(/&/g, '&amp;')
24
    .replace(/</g, '&lt;')
25
    .replace(/>/g, '&gt;')
26
    .replace(/"/g, '&quot;')
27
    .replace(/'/g, '&#39;');
28
}
29

30
const highlightRenderer = rendererFactory(({ td, value, cellProperties }) => {
31
  const cellText = value === null || value === undefined ? '' : String(value);
32
  const query = currentSearchTerm.trim();
33

34
  if (!query || !cellProperties.isSearchResult) {
35
    td.textContent = cellText;
36
    return;
37
  }
38

39
  const splitter = new RegExp(`(${escapeRegExp(query)})`, 'gi');
40
  const highlighted = cellText
41
    .split(splitter)
42
    .map((fragment) =>
43
      fragment.toLocaleLowerCase() === query.toLocaleLowerCase()
44
        ? `<mark>${escapeHtml(fragment)}</mark>`
45
        : escapeHtml(fragment)
46
    )
47
    .join('');
48

49
  td.innerHTML = highlighted;
50
});
51

52
const ExampleComponent = () => {
53
  const hotRef = useRef<HotTableRef>(null);
54

55
  function handleSearchInput(e: React.FormEvent<HTMLInputElement>) {
56
    const hot = hotRef.current?.hotInstance;
57

58
    if (!hot) {
59
      return;
60
    }
61

62
    currentSearchTerm = e.currentTarget.value;
63
    hot.getPlugin('search').query(currentSearchTerm);
64
    hot.render();
65
  }
66

67
  return (
68
    <div>
69
      <div className="example-controls-container">
70
        <div className="controls">
71
          <input
72
            type="search"
73
            placeholder="Search tasks"
74
            onInput={handleSearchInput}
75
          />
76
        </div>
77
      </div>
78
      <HotTable
79
        ref={hotRef}
80
        data={data}
81
        colHeaders={['ID', 'Title', 'Owner', 'Status']}
82
        rowHeaders={true}
83
        height="auto"
84
        search={true}
85
        columns={[
86
          { data: 'id', type: 'numeric' },
87
          { data: 'title', renderer: highlightRenderer },
88
          { data: 'owner', renderer: highlightRenderer },
89
          { data: 'status', renderer: highlightRenderer },
90
        ]}
91
        licenseKey="non-commercial-and-evaluation"
92
      />
93
    </div>
94
  );
95
};
96

97
export default ExampleComponent;

Overview

This recipe shows how to highlight matched text fragments with a custom renderer that wraps matches in a  element. You can use this approach when you want richer highlighting than the default Search plugin class.

Difficulty: Beginner Time: ~15 minutes Libraries: None (pure Handsontable + browser APIs)

What You’ll Build

A search experience that:

Highlights only matched fragments inside each cell with 
Keeps non-matching cells unchanged
Escapes both user input and cell values before inserting HTML
Updates in real time when the user types in an external search field
Uses search.query() to keep isSearchResult metadata in sync

Import dependencies

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
import { Search } from 'handsontable/plugins';
4
import { rendererFactory } from 'handsontable/renderers';
5

6
registerAllModules();

Use rendererFactory to build a custom renderer, and use the Search plugin for match detection.

Keep the search term in external state
```
1
let currentSearchTerm = '';
```
The renderer reads currentSearchTerm, so typing in the external input updates rendering after search.query() and hot.render().

Add safe HTML helpers

1
function escapeHtml(value: string): string {
2
  return value
3
    .replace(/&/g, '&amp;')
4
    .replace(/</g, '&lt;')
5
    .replace(/>/g, '&gt;')
6
    .replace(/"/g, '&quot;')
7
    .replace(/'/g, '&#39;');
8
}

Because the renderer sets innerHTML, escape both the source text and the query before composing HTML. This prevents injecting arbitrary markup from data or user input.

Build a `` renderer

1
const highlightRenderer = rendererFactory(({ td, value, cellProperties }) => {
2
  const cellText = value === null || value === undefined ? '' : String(value);
3
  const query = currentSearchTerm.trim();
4

5
  if (!query || !cellProperties.isSearchResult) {
6
    td.textContent = cellText;
7
    return;
8
  }
9

10
  const escapedCellText = escapeHtml(cellText);
11
  const escapedQuery = escapeHtml(query);
12
  const splitter = new RegExp(`(${escapeRegExp(escapedQuery)})`, 'gi');
13
  const highlighted = escapedCellText
14
    .split(splitter)
15
    .map(fragment => (
16
      fragment.toLocaleLowerCase() === escapedQuery.toLocaleLowerCase()
17
        ? `<mark>${fragment}</mark>`
18
        : fragment
19
    ))
20
    .join('');
21

22
  td.innerHTML = highlighted;
23
});

This renderer:

Renders plain text for non-matches
Highlights only cells flagged by the Search plugin
Wraps matching fragments with

Wire the external input to the Search plugin

1
searchField.addEventListener('input', (event) => {
2
  currentSearchTerm = (event.target as HTMLInputElement).value;
3
  searchPlugin.query(currentSearchTerm);
4
  hot.render();
5
});

This keeps metadata and rendering synchronized on every keystroke.

Register the renderer

You can register the custom renderer in two ways:
- Per-column, by setting renderer: highlightRenderer only on selected columns.
- Globally, by setting renderer: highlightRenderer in the root Handsontable options.
This recipe uses per-column registration so numeric IDs keep the default renderer.

Complete example

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
import { Search } from 'handsontable/plugins';
4
import { rendererFactory } from 'handsontable/renderers';
5

6
registerAllModules();
7

8
type RowData = {
9
  id: number;
10
  title: string;
11
  owner: string;
12
  status: string;
13
};
14

15
const data: RowData[] = [
16
  { id: 101, title: 'Search API docs', owner: 'Alex', status: 'In progress' },
17
  { id: 102, title: 'Renderer refactor', owner: 'Mia', status: 'Review' },
18
  { id: 103, title: 'Fix keyboard shortcut', owner: 'Noah', status: 'Done' },
19
  { id: 104, title: 'Search UX tests', owner: 'Ava', status: 'In progress' },
20
];
21

22
let currentSearchTerm = '';
23

24
function escapeRegExp(value: string): string {
25
  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
26
}
27

28
function escapeHtml(value: string): string {
29
  return value
30
    .replace(/&/g, '&amp;')
31
    .replace(/</g, '&lt;')
32
    .replace(/>/g, '&gt;')
33
    .replace(/"/g, '&quot;')
34
    .replace(/'/g, '&#39;');
35
}
36

37
const highlightRenderer = rendererFactory(({ td, value, cellProperties }) => {
38
  const cellText = value === null || value === undefined ? '' : String(value);
39
  const query = currentSearchTerm.trim();
40

41
  if (!query || !cellProperties.isSearchResult) {
42
    td.textContent = cellText;
43
    return;
44
  }
45

46
  const escapedCellText = escapeHtml(cellText);
47
  const escapedQuery = escapeHtml(query);
48
  const splitter = new RegExp(`(${escapeRegExp(escapedQuery)})`, 'gi');
49
  const highlighted = escapedCellText
50
    .split(splitter)
51
    .map(fragment => (
52
      fragment.toLocaleLowerCase() === escapedQuery.toLocaleLowerCase()
53
        ? `<mark>${fragment}</mark>`
54
        : fragment
55
    ))
56
    .join('');
57

58
  td.innerHTML = highlighted;
59
});
60

61
const container = document.querySelector('#example1')!;
62
const searchField = document.querySelector('#search_field')!;
63

64
const hot = new Handsontable(container, {
65
  data,
66
  colHeaders: ['ID', 'Title', 'Owner', 'Status'],
67
  rowHeaders: true,
68
  height: 'auto',
69
  search: true,
70
  columns: [
71
    { data: 'id', type: 'numeric' },
72
    { data: 'title', renderer: highlightRenderer },
73
    { data: 'owner', renderer: highlightRenderer },
74
    { data: 'status', renderer: highlightRenderer },
75
  ],
76
  licenseKey: 'non-commercial-and-evaluation',
77
});
78

79
const searchPlugin: Search = hot.getPlugin('search');
80

81
searchField.addEventListener('input', (event) => {
82
  currentSearchTerm = (event.target as HTMLInputElement).value;
83
  searchPlugin.query(currentSearchTerm);
84
  hot.render();
85
});

How it works

User types in the external search field.
search.query() marks matching cells with isSearchResult.
hot.render() runs the custom renderer.
Matching fragments are wrapped in .
Non-matching cells render as plain text.

Searching values

Cell renderer

Search plugin API

What you learned

How to write a custom cell renderer that reads the isSearchResult flag and the current search term from the plugin state.
How to safely insert  tags around matched text fragments to highlight partial matches inside cell content.
Why you must escape special regex characters in the search term before building a RegExp to avoid runtime errors.
How to combine search.query() and hot.render() to keep highlights in sync with every keystroke.

Next steps

Explore external search box for a simpler approach using the default htSearchResult highlight class without a custom renderer.
Extend the renderer to also highlight matches in the column header row by overriding afterGetColHeader.

Highlight search matches

Overview

What You’ll Build

Import dependencies

Keep the search term in external state

Add safe HTML helpers

Build a <mark> renderer

Wire the external input to the Search plugin

Register the renderer

Complete example

How it works

Related

What you learned

Next steps

Build a `<mark>` renderer