Sync two grids

In this tutorial, you will sync edits from a master grid to a detail grid in real time. You will learn how to use afterChange, setDataAtCell(), and source guards to keep two Handsontable instances consistent without triggering infinite update loops.

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3

4
registerAllModules();
5

6
const SOURCE_SYNC_FROM_MASTER = 'sync-from-master';
7

8
/* start:skip-in-preview */
9
const masterData = [
10
  { firstName: 'Mia', lastName: 'Johnson', plan: 'Starter', seats: 5, pricePerSeat: 29, lastActive: '2026-03-09' },
11
  { firstName: 'Noah', lastName: 'Chen', plan: 'Team', seats: 12, pricePerSeat: 24, lastActive: '2026-03-10' },
12
  { firstName: 'Ava', lastName: 'Miller', plan: 'Business', seats: 18, pricePerSeat: 21, lastActive: '2026-03-08' },
13
  { firstName: 'Liam', lastName: 'Davis', plan: 'Enterprise', seats: 35, pricePerSeat: 19, lastActive: '2026-03-11' },
14
  { firstName: 'Emma', lastName: 'Wilson', plan: 'Team', seats: 9, pricePerSeat: 24, lastActive: '2026-03-06' },
15
  { firstName: 'Oliver', lastName: 'Khan', plan: 'Starter', seats: 4, pricePerSeat: 29, lastActive: '2026-03-07' },
16
  { firstName: 'Sophia', lastName: 'Lee', plan: 'Business', seats: 22, pricePerSeat: 21, lastActive: '2026-03-05' },
17
  { firstName: 'James', lastName: 'Patel', plan: 'Team', seats: 14, pricePerSeat: 24, lastActive: '2026-03-12' },
18
  { firstName: 'Isabella', lastName: 'Rossi', plan: 'Starter', seats: 6, pricePerSeat: 29, lastActive: '2026-03-04' },
19
  { firstName: 'Benjamin', lastName: 'Garcia', plan: 'Enterprise', seats: 41, pricePerSeat: 19, lastActive: '2026-03-03' },
20
  { firstName: 'Charlotte', lastName: 'Nguyen', plan: 'Business', seats: 19, pricePerSeat: 21, lastActive: '2026-03-02' },
21
  { firstName: 'Elijah', lastName: 'Brown', plan: 'Team', seats: 11, pricePerSeat: 24, lastActive: '2026-03-01' },
22
];
23
/* end:skip-in-preview */
24

25
const normalizePlanLabel = (plan) => typeof plan === 'string' ? plan.toUpperCase() : 'N/A';
26

27
const normalizeCustomer = (firstName, lastName) => [firstName, lastName].filter(Boolean).join(' ');
28

29
const normalizeMonthlyRevenue = (seats, pricePerSeat) =>
30
  `$${((seats ?? 0) * (pricePerSeat ?? 0)).toFixed(2)}`;
31

32
const toDetailRow = (row) => ({
33
  customer: normalizeCustomer(row.firstName, row.lastName),
34
  plan: normalizePlanLabel(row.plan),
35
  seats: row.seats,
36
  monthlyRevenue: normalizeMonthlyRevenue(row.seats, row.pricePerSeat),
37
  lastActive: row.lastActive ?? '',
38
});
39

40
const appContainer = document.querySelector('#example1');
41

42
if (!appContainer) {
43
  throw new Error('Missing #example1 container.');
44
}
45

46
appContainer.innerHTML = `
47
  <div class="sync-grids-layout">
48
    <section class="sync-grids-card">
49
      <h4>Master grid (editable)</h4>
50
      <div id="master-grid"></div>
51
    </section>
52
    <section class="sync-grids-card">
53
      <h4>Detail grid (synced)</h4>
54
      <div id="detail-grid"></div>
55
    </section>
56
  </div>
57
`;
58

59
const masterContainer = appContainer.querySelector('#master-grid');
60
const detailContainer = appContainer.querySelector('#detail-grid');
61

62
const detailHot = new Handsontable(detailContainer, {
63
  data: masterData.map(toDetailRow),
64
  colHeaders: ['Customer', 'Plan', 'Seats', 'Monthly revenue', 'Last active'],
65
  columns: [
66
    { data: 'customer', readOnly: true, width: 170 },
67
    { data: 'plan', readOnly: true, width: 130 },
68
    { data: 'seats', readOnly: true, type: 'numeric', width: 70 },
69
    { data: 'monthlyRevenue', readOnly: true, width: 130 },
70
    { data: 'lastActive', readOnly: true, width: 110 },
71
  ],
72
  rowHeaders: true,
73
  height: 260,
74
  width: '100%',
75
  autoWrapRow: true,
76
  stretchH: 'all',
77
  licenseKey: 'non-commercial-and-evaluation',
78
});
79

80
const detailColumnMap = {
81
  customer: 0,
82
  plan: 1,
83
  seats: 2,
84
  monthlyRevenue: 3,
85
  lastActive: 4,
86
};
87

88
const syncDetailRow = (rowIndex, rowData) => {
89
  const detailRow = toDetailRow(rowData);
90

91
  // Batch updates to avoid multiple render cycles for one row sync.
92
  const detailChanges = Object.entries(detailColumnMap)
93
    .map(([prop, columnIndex]) => [rowIndex, columnIndex, detailRow[prop]]);
94

95
  detailHot.setDataAtCell(detailChanges, SOURCE_SYNC_FROM_MASTER);
96
};
97

98
const masterHot = new Handsontable(masterContainer, {
99
  data: masterData,
100
  colHeaders: ['First name', 'Last name', 'Plan', 'Seats', 'Price / seat', 'Last active'],
101
  columns: [
102
    { data: 'firstName', type: 'text', width: 120 },
103
    { data: 'lastName', type: 'text', width: 120 },
104
    { data: 'plan', type: 'dropdown', source: ['Starter', 'Team', 'Business', 'Enterprise'], width: 130 },
105
    { data: 'seats', type: 'numeric', width: 70 },
106
    { data: 'pricePerSeat', type: 'numeric', numericFormat: { pattern: '$0,0.00' }, width: 105 },
107
    { data: 'lastActive', type: 'date', dateFormat: 'YYYY-MM-DD', correctFormat: true, width: 130 },
108
  ],
109
  rowHeaders: true,
110
  height: 260,
111
  width: '100%',
112
  autoWrapRow: true,
113
  stretchH: 'all',
114
  afterChange: (changes, source) => {
115
    // Ignore init/sync writes to prevent re-entrant updates.
116
    if (!changes || source === SOURCE_SYNC_FROM_MASTER || source === 'loadData') {
117
      return;
118
    }
119

120
    const changedRows = new Set();
121

122
    changes.forEach(([row]) => {
123
      if (typeof row === 'number') {
124
        changedRows.add(row);
125
      }
126
    });
127

128
    changedRows.forEach((rowIndex) => {
129
      const rowData = masterHot.getSourceDataAtRow(rowIndex);
130

131
      syncDetailRow(rowIndex, rowData);
132
    });
133
  },
134
  licenseKey: 'non-commercial-and-evaluation',
135
});
136

137
// eslint-disable-next-line no-unused-vars
138
const hotInstances = { masterHot, detailHot };

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3

4
registerAllModules();
5

6
interface MasterRow {
7
  firstName: string;
8
  lastName: string;
9
  plan: string | null;
10
  seats: number;
11
  pricePerSeat: number;
12
  lastActive: string;
13
}
14

15
interface DetailRow {
16
  customer: string;
17
  plan: string;
18
  seats: number;
19
  monthlyRevenue: string;
20
  lastActive: string;
21
}
22

23
const SOURCE_SYNC_FROM_MASTER = 'sync-from-master';
24

25
/* start:skip-in-preview */
26
const masterData: MasterRow[] = [
27
  { firstName: 'Mia', lastName: 'Johnson', plan: 'Starter', seats: 5, pricePerSeat: 29, lastActive: '2026-03-09' },
28
  { firstName: 'Noah', lastName: 'Chen', plan: 'Team', seats: 12, pricePerSeat: 24, lastActive: '2026-03-10' },
29
  { firstName: 'Ava', lastName: 'Miller', plan: 'Business', seats: 18, pricePerSeat: 21, lastActive: '2026-03-08' },
30
  { firstName: 'Liam', lastName: 'Davis', plan: 'Enterprise', seats: 35, pricePerSeat: 19, lastActive: '2026-03-11' },
31
  { firstName: 'Emma', lastName: 'Wilson', plan: 'Team', seats: 9, pricePerSeat: 24, lastActive: '2026-03-06' },
32
  { firstName: 'Oliver', lastName: 'Khan', plan: 'Starter', seats: 4, pricePerSeat: 29, lastActive: '2026-03-07' },
33
  { firstName: 'Sophia', lastName: 'Lee', plan: 'Business', seats: 22, pricePerSeat: 21, lastActive: '2026-03-05' },
34
  { firstName: 'James', lastName: 'Patel', plan: 'Team', seats: 14, pricePerSeat: 24, lastActive: '2026-03-12' },
35
  { firstName: 'Isabella', lastName: 'Rossi', plan: 'Starter', seats: 6, pricePerSeat: 29, lastActive: '2026-03-04' },
36
  { firstName: 'Benjamin', lastName: 'Garcia', plan: 'Enterprise', seats: 41, pricePerSeat: 19, lastActive: '2026-03-03' },
37
  { firstName: 'Charlotte', lastName: 'Nguyen', plan: 'Business', seats: 19, pricePerSeat: 21, lastActive: '2026-03-02' },
38
  { firstName: 'Elijah', lastName: 'Brown', plan: 'Team', seats: 11, pricePerSeat: 24, lastActive: '2026-03-01' },
39
];
40
/* end:skip-in-preview */
41

42
const normalizePlanLabel = (plan: MasterRow['plan']): string =>
43
  typeof plan === 'string' ? plan.toUpperCase() : 'N/A';
44

45
const normalizeCustomer = (firstName: string | null, lastName: string | null): string =>
46
  [firstName, lastName].filter(Boolean).join(' ');
47

48
const normalizeMonthlyRevenue = (seats: number | null, pricePerSeat: number | null): string =>
49
  `$${((seats ?? 0) * (pricePerSeat ?? 0)).toFixed(2)}`;
50

51
const toDetailRow = (row: MasterRow): DetailRow => ({
52
  customer: normalizeCustomer(row.firstName, row.lastName),
53
  plan: normalizePlanLabel(row.plan),
54
  seats: row.seats,
55
  monthlyRevenue: normalizeMonthlyRevenue(row.seats, row.pricePerSeat),
56
  lastActive: row.lastActive ?? '',
57
});
58

59
const appContainer = document.querySelector('#example1') as HTMLDivElement;
60

61
if (!appContainer) {
62
  throw new Error('Missing #example1 container.');
63
}
64

65
appContainer.innerHTML = `
66
  <div class="sync-grids-layout">
67
    <section class="sync-grids-card">
68
      <h4>Master grid (editable)</h4>
69
      <div id="master-grid"></div>
70
    </section>
71
    <section class="sync-grids-card">
72
      <h4>Detail grid (synced)</h4>
73
      <div id="detail-grid"></div>
74
    </section>
75
  </div>
76
`;
77

78
const masterContainer = appContainer.querySelector('#master-grid') as HTMLDivElement;
79
const detailContainer = appContainer.querySelector('#detail-grid') as HTMLDivElement;
80

81
const detailHot = new Handsontable(detailContainer, {
82
  data: masterData.map(toDetailRow),
83
  colHeaders: ['Customer', 'Plan', 'Seats', 'Monthly revenue', 'Last active'],
84
  columns: [
85
    { data: 'customer', readOnly: true, width: 170 },
86
    { data: 'plan', readOnly: true, width: 130 },
87
    { data: 'seats', readOnly: true, type: 'numeric', width: 70 },
88
    { data: 'monthlyRevenue', readOnly: true, width: 130 },
89
    { data: 'lastActive', readOnly: true, width: 110 },
90
  ],
91
  rowHeaders: true,
92
  height: 260,
93
  width: '100%',
94
  autoWrapRow: true,
95
  stretchH: 'all',
96
  licenseKey: 'non-commercial-and-evaluation',
97
});
98

99
const detailColumnMap: Record<keyof DetailRow, number> = {
100
  customer: 0,
101
  plan: 1,
102
  seats: 2,
103
  monthlyRevenue: 3,
104
  lastActive: 4,
105
};
106

107
const syncDetailRow = (rowIndex: number, rowData: MasterRow) => {
108
  const detailRow = toDetailRow(rowData);
109

110
  // Batch updates into one call to avoid multiple render passes.
111
  const updates = (Object.entries(detailColumnMap) as [keyof DetailRow, number][])
112
    .map(([prop, columnIndex]) => [rowIndex, columnIndex, detailRow[prop]] as [number, number, DetailRow[keyof DetailRow]]);
113

114
  detailHot.setDataAtCell(updates, SOURCE_SYNC_FROM_MASTER);
115
};
116

117
const masterHot = new Handsontable(masterContainer, {
118
  data: masterData,
119
  colHeaders: ['First name', 'Last name', 'Plan', 'Seats', 'Price / seat', 'Last active'],
120
  columns: [
121
    { data: 'firstName', type: 'text', width: 120 },
122
    { data: 'lastName', type: 'text', width: 120 },
123
    { data: 'plan', type: 'dropdown', source: ['Starter', 'Team', 'Business', 'Enterprise'], width: 130 },
124
    { data: 'seats', type: 'numeric', width: 70 },
125
    { data: 'pricePerSeat', type: 'numeric', numericFormat: { pattern: '$0,0.00' }, width: 105 },
126
    { data: 'lastActive', type: 'date', dateFormat: 'YYYY-MM-DD', correctFormat: true, width: 130 },
127
  ],
128
  rowHeaders: true,
129
  height: 260,
130
  width: '100%',
131
  autoWrapRow: true,
132
  stretchH: 'all',
133
  afterChange: (changes, source) => {
134
    // Ignore init/sync writes to prevent re-entrant updates.
135
    if (!changes || source === SOURCE_SYNC_FROM_MASTER || source === 'loadData') {
136
      return;
137
    }
138

139
    const changedRows = new Set<number>();
140

141
    changes.forEach(([row]) => {
142
      if (typeof row === 'number') {
143
        changedRows.add(row);
144
      }
145
    });
146

147
    changedRows.forEach((rowIndex) => {
148
      const rowData = masterHot.getSourceDataAtRow(rowIndex) as MasterRow;
149

150
      syncDetailRow(rowIndex, rowData);
151
    });
152
  },
153
  licenseKey: 'non-commercial-and-evaluation',
154
});
155

156
// eslint-disable-next-line no-unused-vars
157
const hotInstances = { masterHot, detailHot };

1
.sync-grids-layout {
2
  display: grid;
3
  grid-template-columns: repeat(2, minmax(0, 1fr));
4
  gap: 12px;
5
}
6

7
.sync-grids-card {
8
  border: 1px solid var(--sl-color-gray-5);
9
  border-radius: 4px;
10
  padding: 8px;
11
  background: var(--sl-color-gray-7);
12
}
13

14
.sync-grids-card h4 {
15
  margin: 0 0 8px;
16
  font-size: 13px;
17
  font-weight: 600;
18
  color: var(--sl-color-text);
19
}
20

21
@media (max-width: 960px) {
22
  .sync-grids-layout {
23
    grid-template-columns: 1fr;
24
  }
25
}

Overview

This recipe shows how to keep two Handsontable instances in sync on the same page. You edit data in the master grid, and the detail grid updates immediately.

The implementation uses afterChange and batched setDataAtCell() updates, plus a source guard to avoid infinite update loops.

Difficulty: Beginner Time: ~10 minutes Libraries: None (pure Handsontable)

What you’ll build

Two grids displayed side by side:

Master grid - editable source data.
Detail grid - synced preview with transformed values.

When you edit a row in the master grid, the related row in the detail grid is updated instantly.

Initialize two grid containers

Render two containers inside one recipe root element and place them side by side with CSS Grid.

1
const appContainer = document.querySelector('#example1') as HTMLDivElement;
2

3
appContainer.innerHTML = `
4
  <div class="sync-grids-layout">
5
    <section class="sync-grids-card">
6
      <h4>Master grid (editable)</h4>
7
      <div id="master-grid"></div>
8
    </section>
9
    <section class="sync-grids-card">
10
      <h4>Detail grid (synced)</h4>
11
      <div id="detail-grid"></div>
12
    </section>
13
  </div>
14
`;

Create a detail model

Use a helper function to map master rows into preview rows. This lets you sync only selected columns and transform values before display.

1
const toDetailRow = (row: MasterRow): DetailRow => ({
2
  customer: `${row.firstName} ${row.lastName}`,
3
  plan: row.plan.toUpperCase(),
4
  seats: row.seats,
5
  monthlyRevenue: `$${(row.seats * row.pricePerSeat).toFixed(2)}`,
6
});

Initialize detail grid

Create the detail table with readOnly: true so it acts as a live preview.

1
const detailHot = new Handsontable(detailContainer, {
2
  data: masterData.map(toDetailRow),
3
  readOnly: true,
4
  // ...
5
});

Sync updates with afterChange

Use afterChange on the master instance. For each changed row, map the detail values and apply them in a single batched setDataAtCell() call.
```
1
afterChange: (changes, source) => {
2
  if (!changes || source === 'sync-from-master' || source === 'loadData') {
3
    return;
4
  }
5

6
  changes.forEach(([row, prop, _oldValue, newValue]) => {
7
    // Update only mapped columns.
8
  });
9
}
```
The source check prevents re-entrant updates if synced writes trigger hooks, and batching keeps each row sync to one render pass.

How it works - complete flow

You edit a value in the master grid.
afterChange receives row, column, and new value.
The handler updates only mapped fields in the detail row.
The detail grid receives updates via setDataAtCell(..., 'sync-from-master').
The source guard ignores sync-originated updates, so no infinite loop occurs.

Why this pattern is useful

Keep one grid editable and another focused on read-only presentation.
Sync only selected fields, not the whole dataset.
Add value formatting or derived columns in one place.
Avoid expensive full-table refreshes by patching changed cells only.

What you learned

How to use afterChange on one Handsontable instance to detect edits and propagate them to a second instance.
How to use setDataAtCell() with a custom source string to apply updates without triggering an infinite re-entry loop.
How a source guard (if (source === 'sync-from-master') return) prevents the synced writes from firing the afterChange hook again.
How to batch multiple cell updates into a single setDataAtCell() call to keep each sync to one render pass.

Next steps

Extend the sync to work in both directions so either grid can serve as the master.
Add a field mapping function to transform values (for example, format currency in the detail grid) before applying the sync.
Explore the undo/redo recipe to let users revert synchronized changes.