Wrap Handsontable in a web component

In this tutorial, you will wrap Handsontable in a custom element that owns its own shadow root. It covers only the glue between the grid and the element: getting the stylesheets to both sides of the shadow boundary, passing data and settings in through methods, emitting cell edits out as DOM events, and destroying the instance when the element leaves the page. It assumes you already write custom elements.

Overview

Difficulty: Intermediate
Time: ~20 minutes

A custom element gives the grid one tag, a few methods, and one event, and the same tag then works in a plain page or inside a framework component.

Handsontable works across a shadow boundary on its own, so clicking, the cell editors, copy and paste, and the context menu need no forwarding code from you - see the Shadow DOM guide for what it handles there.

What you’ll build

A <hot-grid> element with a small, framework-agnostic contract:

setData() and setSettings() methods that update a live grid instead of recreating it, with getData(), getSettings(), and getInstance() reading straight from it.
A cell-change event that carries each edit to the host page.
Stylesheets on both sides of the shadow boundary: a constructed sheet inside the root, a plain import for the menus outside it.

Before you begin

Scaffold a vanilla project and add the grid:

1
npm create vite@latest hot-grid-element -- --template vanilla-ts
2
cd hot-grid-element
3
npm install handsontable

Define the element and its styles

The grid needs a container inside the shadow root, and a :host display so the element has a box to render into. index.html puts the tag on the page, so every later step has something live to change:

1
import baseStyles from 'handsontable/styles/handsontable.min.css?inline';
2
import themeStyles from 'handsontable/styles/ht-theme-main.min.css?inline';
3

4
// The menus mount in a portal on document.body, outside the shadow root.
5
import 'handsontable/styles/handsontable.min.css';
6
import 'handsontable/styles/ht-theme-main.min.css';
7

8
const gridStyles = new CSSStyleSheet();
9

10
gridStyles.replaceSync(`
11
  ${baseStyles}
12
  ${themeStyles}
13
  :host { display: block; }
14
`);
15

16
class HotGridElement extends HTMLElement {
17
  #container: HTMLDivElement;
18

19
  constructor() {
20
    super();
21

22
    const shadowRoot = this.attachShadow({ mode: 'open' });
23

24
    shadowRoot.adoptedStyleSheets = [gridStyles];
25

26
    this.#container = document.createElement('div');
27

28
    shadowRoot.append(this.#container);
29
  }
30
}
31

32
customElements.define('hot-grid', HotGridElement);
33

34
declare global {
35
  interface HTMLElementTagNameMap {
36
    'hot-grid': HotGridElement;
37
  }
38
}

1
<hot-grid></hot-grid>
2
<script type="module" src="/src/main.ts"></script>

The ?inline imports give the constructed sheet its text: handsontable.min.css for structure, the theme stylesheet for the visible design. Without the plain pair in the document, every menu opens unstyled.

The page stays blank for now: the element upgrades and its shadow root is styled, but no grid exists until Step 2 creates one.

Create the grid and emit its edits

Create the instance in connectedCallback(), and translate the one hook the host page cares about into a DOM event:

1
import Handsontable from 'handsontable';
15 collapsed lines
2
import baseStyles from 'handsontable/styles/handsontable.min.css?inline';
3
import themeStyles from 'handsontable/styles/ht-theme-main.min.css?inline';
4

5
// The menus mount in a portal on document.body, outside the shadow root.
6
import 'handsontable/styles/handsontable.min.css';
7
import 'handsontable/styles/ht-theme-main.min.css';
8

9
const gridStyles = new CSSStyleSheet();
10

11
gridStyles.replaceSync(`
12
  ${baseStyles}
13
  ${themeStyles}
14
  :host { display: block; }
15
`);
16

17
interface HotGridCellChange {
18
  row: number;
19
  physicalRow: number;
20
  prop: Handsontable.CellChange[1];
21
  oldValue: Handsontable.CellValue;
22
  newValue: Handsontable.CellValue;
23
  source?: Handsontable.ChangeSource;
24
}
25

26
class HotGridElement extends HTMLElement {
27
  #instance: Handsontable | null = null;
13 collapsed lines
28
  #container: HTMLDivElement;
29

30
  constructor() {
31
    super();
32

33
    const shadowRoot = this.attachShadow({ mode: 'open' });
34

35
    shadowRoot.adoptedStyleSheets = [gridStyles];
36

37
    this.#container = document.createElement('div');
38

39
    shadowRoot.append(this.#container);
40
  }
41

42
  #createGrid(): void {
43
    const instance = new Handsontable(this.#container, {
44
      themeName: 'ht-theme-main',
45
      rowHeaders: true,
46
      licenseKey: 'non-commercial-and-evaluation',
47
      afterChange: (changes, source) => {
48
        if (!changes || source === 'loadData') {
49
          return;
50
        }
51

52
        changes.forEach(([row, prop, oldValue, newValue]) => {
53
          this.dispatchEvent(new CustomEvent<HotGridCellChange>('cell-change', {
54
            detail: {
55
              row,
56
              physicalRow: instance.toPhysicalRow(row),
57
              prop,
58
              oldValue,
59
              newValue,
60
              source,
61
            },
62
            bubbles: true,
63
            composed: true,
64
          }));
65
        });
66
      },
67
    });
68

69
    this.#instance = instance;
70
  }
71

72
  connectedCallback(): void {
73
    if (!this.#instance) {
74
      this.#createGrid();
75
    }
76
  }
8 collapsed lines
77
}
78

79
customElements.define('hot-grid', HotGridElement);
80

81
declare global {
82
  interface HTMLElementTagNameMap {
83
    'hot-grid': HotGridElement;
84
  }
85

86
  interface HTMLElementEventMap {
87
    'cell-change': CustomEvent<HotGridCellChange>;
88
  }
89
}

composed: true is what lets the event leave the shadow root - without it a listener on the host page never fires. Skipping the loadData source keeps the first data load from reporting every cell as an edit.

cell-change carries both indexes, because row is visual and moves when the user sorts - index your store with physicalRow. See Understanding data and indexes.

Replace licenseKey with your commercial key before production use. See License key.

Expose the grid through methods

The host reads and writes through methods that go straight to the instance, so the element stores no copy of the data:


16 collapsed lines
1
import Handsontable from 'handsontable';
2
import baseStyles from 'handsontable/styles/handsontable.min.css?inline';
3
import themeStyles from 'handsontable/styles/ht-theme-main.min.css?inline';
4

5
// The menus mount in a portal on document.body, outside the shadow root.
6
import 'handsontable/styles/handsontable.min.css';
7
import 'handsontable/styles/ht-theme-main.min.css';
8

9
const gridStyles = new CSSStyleSheet();
10

11
gridStyles.replaceSync(`
12
  ${baseStyles}
13
  ${themeStyles}
14
  :host { display: block; }
15
`);
16

17
type HotGridRow = Handsontable.RowObject | Handsontable.CellValue[];
18

7 collapsed lines
19
interface HotGridCellChange {
20
  row: number;
21
  physicalRow: number;
22
  prop: Handsontable.CellChange[1];
23
  oldValue: Handsontable.CellValue;
24
  newValue: Handsontable.CellValue;
25
  source?: Handsontable.ChangeSource;
26
}
27

28
function cloneRows(rows: HotGridRow[]): HotGridRow[] {
29
  try {
30
    return structuredClone(rows);
31
  } catch (error) {
32
    throw new Error(
33
      'hot-grid: data must be structured-cloneable. Reactive proxies, cyclic ' +
34
      'references, functions, and BigInt are not.',
35
      { cause: error },
36
    );
37
  }
53 collapsed lines
38
}
39

40
class HotGridElement extends HTMLElement {
41
  #instance: Handsontable | null = null;
42
  #container: HTMLDivElement;
43

44
  constructor() {
45
    super();
46

47
    const shadowRoot = this.attachShadow({ mode: 'open' });
48

49
    shadowRoot.adoptedStyleSheets = [gridStyles];
50

51
    this.#container = document.createElement('div');
52

53
    shadowRoot.append(this.#container);
54
  }
55

56
  #createGrid(): void {
57
    const instance = new Handsontable(this.#container, {
58
      themeName: 'ht-theme-main',
59
      rowHeaders: true,
60
      licenseKey: 'non-commercial-and-evaluation',
61
      afterChange: (changes, source) => {
62
        if (!changes || source === 'loadData') {
63
          return;
64
        }
65

66
        changes.forEach(([row, prop, oldValue, newValue]) => {
67
          this.dispatchEvent(new CustomEvent<HotGridCellChange>('cell-change', {
68
            detail: {
69
              row,
70
              physicalRow: instance.toPhysicalRow(row),
71
              prop,
72
              oldValue,
73
              newValue,
74
              source,
75
            },
76
            bubbles: true,
77
            composed: true,
78
          }));
79
        });
80
      },
81
    });
82

83
    this.#instance = instance;
84
  }
85

86
  connectedCallback(): void {
87
    if (!this.#instance) {
88
      this.#createGrid();
89
    }
90
  }
91

92
  getData(): ReturnType<Handsontable['getSourceData']> {
93
    return this.#instance?.getSourceData() ?? [];
94
  }
95

96
  setData(rows: HotGridRow[]): void {
97
    this.#instance?.updateSettings({ data: cloneRows(rows) });
98
  }
99

100
  getSettings(): Handsontable.GridSettings {
101
    return this.#instance?.getSettings() ?? {};
102
  }
103

104
  setSettings(settings: Handsontable.GridSettings): void {
105
    this.#instance?.updateSettings(settings);
106
  }
107

108
  getInstance(): Handsontable | null {
109
    return this.#instance;
110
  }
13 collapsed lines
111
}
112

113
customElements.define('hot-grid', HotGridElement);
114

115
declare global {
116
  interface HTMLElementTagNameMap {
117
    'hot-grid': HotGridElement;
118
  }
119

120
  interface HTMLElementEventMap {
121
    'cell-change': CustomEvent<HotGridCellChange>;
122
  }
123
}

Handsontable writes edits into the array it is given, so setData() clones what the host passes in rather than letting the grid edit the host’s own state.

Clean up on disconnect

A grid that is never destroyed keeps its listeners and its resize observer alive, which leaks on any page that swaps views without a reload:
src/main.ts
```
1
  connectedCallback(): void {
2
    if (!this.#instance) {
3
      this.#createGrid();
4
    }
5
  }
6

7
  disconnectedCallback(): void {
8
    queueMicrotask(() => {
9
      if (this.isConnected) {
10
        return;
11
      }
12

13
      this.#instance?.destroy();
14
      this.#instance = null;
15
    });
16
  }
17

18
  getData(): ReturnType<Handsontable['getSourceData']> {
19
    return this.#instance?.getSourceData() ?? [];
20
  }
21

22
  setData(rows: HotGridRow[]): void {
23
    this.#instance?.updateSettings({ data: cloneRows(rows) });
24
  }
```
Handsontable reads the container’s root node once, when the instance is created, and that single check drives the ht-shadow-dom class and the shadow-root clipboard listeners. Moving a live grid into or out of a shadow root leaves those bound to the wrong tree, so destroy and recreate rather than reparenting.

The microtask is what makes an ordinary DOM move survivable. insertBefore and append on an already-connected element fire disconnectedCallback and then connectedCallback, so destroying synchronously throws away the instance - and with it the selection and any edit the grid has not written back - on a plain reorder. Deferring one microtask lets the reconnect cancel the teardown.

Use the element

The tag has been on the page since Step 1. Fill it at the end of src/main.ts, below the class:

1
customElements.define('hot-grid', HotGridElement);
2

3
declare global {
4
  interface HTMLElementTagNameMap {
5
    'hot-grid': HotGridElement;
6
  }
7

8
  interface HTMLElementEventMap {
9
    'cell-change': CustomEvent<HotGridCellChange>;
10
  }
11
}
12

13
const grid = document.querySelector('hot-grid');
14

15
grid?.setData([
16
  { sku: 'SKU-4821', product: 'Thermal camera', quantity: 142, supplier: 'Harbor Goods' },
17
  { sku: 'SKU-0093', product: 'Cable tester', quantity: 67, supplier: 'Alpine Supply Co.' },
18
  { sku: 'SKU-1147', product: 'Torque wrench', quantity: 0, supplier: 'Harbor Goods' },
19
  { sku: 'SKU-2250', product: 'Label printer', quantity: 38, supplier: 'Vertex Industries' },
20
  { sku: 'SKU-3390', product: 'Impact driver', quantity: 91, supplier: 'Alpine Supply Co.' },
21
]);
22

23
grid?.setSettings({
24
  colHeaders: ['SKU', 'Product', 'Quantity', 'Supplier'],
25
  columns: [
26
    { data: 'sku' },
27
    { data: 'product' },
28
    { data: 'quantity', type: 'numeric' },
29
    { data: 'supplier' },
30
  ],
31
});
32

33
grid?.addEventListener('cell-change', (event) => {
34
  const { physicalRow, prop, newValue } = event.detail;
35

36
  console.log(physicalRow, prop, newValue);
37
});

Shadow DOM

Themes

Installation

What you learned

The shadow root adopts the grid’s stylesheets as a constructed sheet, and the document still needs them for the menus.
Data and settings go in through methods, forwarded to updateSettings() so a live grid is not recreated.

Next steps

Explore Run Handsontable in a Salesforce Lightning Web Component for the same pattern on a platform that owns the component lifecycle.