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

6
registerAllModules();
7

8
const SOURCE_SYNC_FROM_MASTER = 'sync-from-master';
9

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

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

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

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

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

42
const detailColumnMap = {
43
  customer: 0,
44
  plan: 1,
45
  seats: 2,
46
  monthlyRevenue: 3,
47
  lastActive: 4,
48
};
49

50
const ExampleComponent = () => {
51
  const masterHotRef = useRef(null);
52
  const detailHotRef = useRef(null);
53

54
  const syncDetailRow = (rowIndex, rowData) => {
55
    const detailHot = detailHotRef.current?.hotInstance;
56

57
    if (!detailHot) {
58
      return;
59
    }
60

61
    const detailRow = toDetailRow(rowData);
62
    const detailChanges = Object.entries(detailColumnMap).map(([prop, columnIndex]) => [
63
      rowIndex,
64
      columnIndex,
65
      detailRow[prop],
66
    ]);
67

68
    detailHot.setDataAtCell(detailChanges, SOURCE_SYNC_FROM_MASTER);
69
  };
70

71
  const handleMasterAfterChange = (changes, source) => {
72
    // Ignore init/sync writes to prevent re-entrant updates.
73
    if (!changes || source === SOURCE_SYNC_FROM_MASTER || source === 'loadData') {
74
      return;
75
    }
76

77
    const masterHot = masterHotRef.current?.hotInstance;
78

79
    if (!masterHot) {
80
      return;
81
    }
82

83
    const changedRows = new Set();
84

85
    changes.forEach(([row]) => {
86
      if (typeof row === 'number') {
87
        changedRows.add(row);
88
      }
89
    });
90

91
    changedRows.forEach((rowIndex) => {
92
      const rowData = masterHot.getSourceDataAtRow(rowIndex);
93

94
      syncDetailRow(rowIndex, rowData);
95
    });
96
  };
97

98
  return (
99
    <div className="sync-grids-layout">
100
      <section className="sync-grids-card">
101
        <h4>Master grid (editable)</h4>
102
        <HotTable
103
          ref={masterHotRef}
104
          data={masterData}
105
          colHeaders={['First name', 'Last name', 'Plan', 'Seats', 'Price / seat', 'Last active']}
106
          columns={[
107
            { data: 'firstName', type: 'text', width: 120 },
108
            { data: 'lastName', type: 'text', width: 120 },
109
            { data: 'plan', type: 'dropdown', source: ['Starter', 'Team', 'Business', 'Enterprise'], width: 130 },
110
            { data: 'seats', type: 'numeric', width: 70 },
111
            { data: 'pricePerSeat', type: 'numeric', numericFormat: { pattern: '$0,0.00' }, width: 105 },
112
            { data: 'lastActive', type: 'date', dateFormat: 'YYYY-MM-DD', correctFormat: true, width: 130 },
113
          ]}
114
          rowHeaders={true}
115
          height={260}
116
          width="100%"
117
          autoWrapRow={true}
118
          stretchH="all"
119
          afterChange={handleMasterAfterChange}
120
          licenseKey="non-commercial-and-evaluation"
121
        />
122
      </section>
123
      <section className="sync-grids-card">
124
        <h4>Detail grid (synced)</h4>
125
        <HotTable
126
          ref={detailHotRef}
127
          data={masterData.map(toDetailRow)}
128
          colHeaders={['Customer', 'Plan', 'Seats', 'Monthly revenue', 'Last active']}
129
          columns={[
130
            { data: 'customer', readOnly: true, width: 170 },
131
            { data: 'plan', readOnly: true, width: 130 },
132
            { data: 'seats', readOnly: true, type: 'numeric', width: 70 },
133
            { data: 'monthlyRevenue', readOnly: true, width: 130 },
134
            { data: 'lastActive', readOnly: true, width: 110 },
135
          ]}
136
          rowHeaders={true}
137
          height={260}
138
          width="100%"
139
          autoWrapRow={true}
140
          stretchH="all"
141
          licenseKey="non-commercial-and-evaluation"
142
        />
143
      </section>
144
    </div>
145
  );
146
};
147

148
export default ExampleComponent;

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

6
registerAllModules();
7

8
const SOURCE_SYNC_FROM_MASTER = 'sync-from-master';
9

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

27
type MasterRow = {
28
  firstName: string;
29
  lastName: string;
30
  plan: string;
31
  seats: number;
32
  pricePerSeat: number;
33
  lastActive: string;
34
};
35

36
type DetailRow = {
37
  customer: string;
38
  plan: string;
39
  seats: number;
40
  monthlyRevenue: string;
41
  lastActive: string;
42
};
43

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

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

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

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

61
const detailColumnMap: Record<keyof DetailRow, number> = {
62
  customer: 0,
63
  plan: 1,
64
  seats: 2,
65
  monthlyRevenue: 3,
66
  lastActive: 4,
67
};
68

69
const ExampleComponent = () => {
70
  const masterHotRef = useRef<HotTableRef>(null);
71
  const detailHotRef = useRef<HotTableRef>(null);
72

73
  const syncDetailRow = (rowIndex: number, rowData: MasterRow): void => {
74
    const detailHot = detailHotRef.current?.hotInstance;
75

76
    if (!detailHot) {
77
      return;
78
    }
79

80
    const detailRow = toDetailRow(rowData);
81
    const detailChanges = (Object.entries(detailColumnMap) as [keyof DetailRow, number][]).map(
82
      ([prop, columnIndex]) => [rowIndex, columnIndex, detailRow[prop]] as [number, number, unknown]
83
    );
84

85
    detailHot.setDataAtCell(detailChanges, SOURCE_SYNC_FROM_MASTER);
86
  };
87

88
  const handleMasterAfterChange = (changes: [number, string | number, unknown, unknown][] | null, source: string): void => {
89
    // Ignore init/sync writes to prevent re-entrant updates.
90
    if (!changes || source === SOURCE_SYNC_FROM_MASTER || source === 'loadData') {
91
      return;
92
    }
93

94
    const masterHot = masterHotRef.current?.hotInstance;
95

96
    if (!masterHot) {
97
      return;
98
    }
99

100
    const changedRows = new Set<number>();
101

102
    changes.forEach(([row]) => {
103
      if (typeof row === 'number') {
104
        changedRows.add(row);
105
      }
106
    });
107

108
    changedRows.forEach((rowIndex) => {
109
      const rowData = masterHot.getSourceDataAtRow(rowIndex) as MasterRow;
110

111
      syncDetailRow(rowIndex, rowData);
112
    });
113
  };
114

115
  return (
116
    <div className="sync-grids-layout">
117
      <section className="sync-grids-card">
118
        <h4>Master grid (editable)</h4>
119
        <HotTable
120
          ref={masterHotRef}
121
          data={masterData}
122
          colHeaders={['First name', 'Last name', 'Plan', 'Seats', 'Price / seat', 'Last active']}
123
          columns={[
124
            { data: 'firstName', type: 'text', width: 120 },
125
            { data: 'lastName', type: 'text', width: 120 },
126
            { data: 'plan', type: 'dropdown', source: ['Starter', 'Team', 'Business', 'Enterprise'], width: 130 },
127
            { data: 'seats', type: 'numeric', width: 70 },
128
            { data: 'pricePerSeat', type: 'numeric', numericFormat: { pattern: '$0,0.00' }, width: 105 },
129
            { data: 'lastActive', type: 'date', dateFormat: 'YYYY-MM-DD', correctFormat: true, width: 130 },
130
          ]}
131
          rowHeaders={true}
132
          height={260}
133
          width="100%"
134
          autoWrapRow={true}
135
          stretchH="all"
136
          afterChange={handleMasterAfterChange}
137
          licenseKey="non-commercial-and-evaluation"
138
        />
139
      </section>
140
      <section className="sync-grids-card">
141
        <h4>Detail grid (synced)</h4>
142
        <HotTable
143
          ref={detailHotRef}
144
          data={masterData.map(toDetailRow)}
145
          colHeaders={['Customer', 'Plan', 'Seats', 'Monthly revenue', 'Last active']}
146
          columns={[
147
            { data: 'customer', readOnly: true, width: 170 },
148
            { data: 'plan', readOnly: true, width: 130 },
149
            { data: 'seats', readOnly: true, type: 'numeric', width: 70 },
150
            { data: 'monthlyRevenue', readOnly: true, width: 130 },
151
            { data: 'lastActive', readOnly: true, width: 110 },
152
          ]}
153
          rowHeaders={true}
154
          height={260}
155
          width="100%"
156
          autoWrapRow={true}
157
          stretchH="all"
158
          licenseKey="non-commercial-and-evaluation"
159
        />
160
      </section>
161
    </div>
162
  );
163
};
164

165
export default ExampleComponent;

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.