Auto-save changes to a backend

In this tutorial, you will build an auto-save flow that sends grid edits to a backend after a debounce delay. You will learn how to use afterChange, dirty row tracking, and save status feedback to give users real-time confirmation of their changes.

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

5
registerAllModules();
6

7
const data = [
8
  { id: 1, product: 'Keyboard', stock: 14, price: 89, status: 'active' },
9
  { id: 2, product: 'Monitor', stock: 5, price: 249, status: 'active' },
10
  { id: 3, product: 'Dock', stock: 22, price: 139, status: 'draft' },
11
  { id: 4, product: 'Webcam', stock: 9, price: 119, status: 'active' },
12
  { id: 5, product: 'Headset', stock: 16, price: 99, status: 'paused' },
13
];
14

15
const statusLabels = {
16
  idle: 'No pending changes',
17
  saving: 'Saving...',
18
  saved: 'Saved ✓',
19
  error: 'Error',
20
};
21

22
const statusColors = {
23
  idle: '#616161',
24
  saving: '#1a42e8',
25
  saved: '#117a1f',
26
  error: '#c62828',
27
};
28

29
const saveRowsToBackend = (rows) => {
30
  return new Promise((resolve) => setTimeout(resolve, 450)).then(() => {
31
    // Replace this with fetch('/api/products', { method: 'PATCH', body: ... }) in production.
32
    // eslint-disable-next-line no-console
33
    console.log('PATCH /api/products', rows);
34
  });
35
};
36

37
const ExampleComponent = () => {
38
  const hotRef = useRef(null);
39
  const [saveStatus, setSaveStatus] = useState('idle');
40
  const dirtyRowsRef = useRef(new Set());
41
  const saveTimeoutRef = useRef(null);
42
  const saveRequestCounterRef = useRef(0);
43

44
  const handleAfterChange = (changes, source) => {
45
    if (!changes || source === 'loadData') {
46
      return;
47
    }
48

49
    const hot = hotRef.current?.hotInstance;
50

51
    if (!hot) {
52
      return;
53
    }
54

55
    changes.forEach(([visualRow, _prop, oldValue, newValue]) => {
56
      if (oldValue !== newValue) {
57
        const physicalRow = hot.toPhysicalRow(visualRow);
58

59
        if (physicalRow !== null && physicalRow >= 0) {
60
          dirtyRowsRef.current.add(physicalRow);
61
        }
62
      }
63
    });
64

65
    if (saveTimeoutRef.current) {
66
      clearTimeout(saveTimeoutRef.current);
67
    }
68

69
    saveTimeoutRef.current = setTimeout(() => {
70
      const physicalRows = Array.from(dirtyRowsRef.current);
71

72
      if (physicalRows.length === 0) {
73
        return;
74
      }
75

76
      const requestId = ++saveRequestCounterRef.current;
77
      const visualRows = physicalRows
78
        .map((physicalRow) => hot.toVisualRow(physicalRow))
79
        .filter((row) => row !== null);
80

81
      hot.validateRows(visualRows, (valid) => {
82
        if (!valid) {
83
          if (requestId === saveRequestCounterRef.current) {
84
            setSaveStatus('error');
85
          }
86

87
          return;
88
        }
89

90
        const rowsToSave = physicalRows
91
          .map((physicalRow) => hot.getSourceDataAtRow(physicalRow))
92
          .filter((row) => row !== undefined && row !== null);
93

94
        dirtyRowsRef.current.clear();
95
        setSaveStatus('saving');
96

97
        void saveRowsToBackend(rowsToSave)
98
          .then(() => {
99
            if (requestId === saveRequestCounterRef.current) {
100
              setSaveStatus('saved');
101
            }
102
          })
103
          .catch(() => {
104
            physicalRows.forEach((physicalRow) => dirtyRowsRef.current.add(physicalRow));
105

106
            if (requestId === saveRequestCounterRef.current) {
107
              setSaveStatus('error');
108
            }
109
          });
110
      });
111
    }, 800);
112
  };
113

114
  return (
115
    <>
116
      <div
117
        style={{
118
          marginBottom: '8px',
119
          fontFamily: 'Arial, sans-serif',
120
          fontSize: '13px',
121
          fontWeight: '600',
122
          color: statusColors[saveStatus],
123
        }}
124
      >
125
        {statusLabels[saveStatus]}
126
      </div>
127
      <HotTable
128
        ref={hotRef}
129
        data={data}
130
        colHeaders={['ID', 'Product', 'Stock', 'Price', 'Status']}
131
        columns={[
132
          { data: 'id', type: 'numeric', readOnly: true, width: 70 },
133
          { data: 'product', type: 'text', width: 180 },
134
          { data: 'stock', type: 'numeric', width: 90 },
135
          { data: 'price', type: 'numeric', numericFormat: { pattern: '$0,0.00' }, width: 110 },
136
          { data: 'status', type: 'text', width: 120 },
137
        ]}
138
        stretchH="all"
139
        height="auto"
140
        afterChange={handleAfterChange}
141
        licenseKey="non-commercial-and-evaluation"
142
      />
143
    </>
144
  );
145
};
146

147
export default ExampleComponent;

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

5
registerAllModules();
6

7
const data = [
8
  { id: 1, product: 'Keyboard', stock: 14, price: 89, status: 'active' },
9
  { id: 2, product: 'Monitor', stock: 5, price: 249, status: 'active' },
10
  { id: 3, product: 'Dock', stock: 22, price: 139, status: 'draft' },
11
  { id: 4, product: 'Webcam', stock: 9, price: 119, status: 'active' },
12
  { id: 5, product: 'Headset', stock: 16, price: 99, status: 'paused' },
13
];
14

15
type SaveStatus = 'idle' | 'saving' | 'saved' | 'error';
16

17
const statusLabels: Record<SaveStatus, string> = {
18
  idle: 'No pending changes',
19
  saving: 'Saving...',
20
  saved: 'Saved ✓',
21
  error: 'Error',
22
};
23

24
const statusColors: Record<SaveStatus, string> = {
25
  idle: '#616161',
26
  saving: '#1a42e8',
27
  saved: '#117a1f',
28
  error: '#c62828',
29
};
30

31
const saveRowsToBackend = (rows: unknown[]): Promise<void> => {
32
  return new Promise<void>((resolve) => setTimeout(resolve, 450)).then(() => {
33
    // Replace this with fetch('/api/products', { method: 'PATCH', body: ... }) in production.
34
    // eslint-disable-next-line no-console
35
    console.log('PATCH /api/products', rows);
36
  });
37
};
38

39
const ExampleComponent = () => {
40
  const hotRef = useRef<HotTableRef>(null);
41
  const [saveStatus, setSaveStatus] = useState<SaveStatus>('idle');
42
  const dirtyRowsRef = useRef(new Set<number>());
43
  const saveTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
44
  const saveRequestCounterRef = useRef(0);
45

46
  const handleAfterChange = (
47
    changes: [number, string | number, unknown, unknown][] | null,
48
    source: string
49
  ): void => {
50
    if (!changes || source === 'loadData') {
51
      return;
52
    }
53

54
    const hot = hotRef.current?.hotInstance;
55

56
    if (!hot) {
57
      return;
58
    }
59

60
    changes.forEach(([visualRow, _prop, oldValue, newValue]) => {
61
      if (oldValue !== newValue) {
62
        const physicalRow = hot.toPhysicalRow(visualRow);
63

64
        if (physicalRow !== null && physicalRow >= 0) {
65
          dirtyRowsRef.current.add(physicalRow);
66
        }
67
      }
68
    });
69

70
    if (saveTimeoutRef.current) {
71
      clearTimeout(saveTimeoutRef.current);
72
    }
73

74
    saveTimeoutRef.current = setTimeout(() => {
75
      const physicalRows = Array.from(dirtyRowsRef.current);
76

77
      if (physicalRows.length === 0) {
78
        return;
79
      }
80

81
      const requestId = ++saveRequestCounterRef.current;
82
      const visualRows = physicalRows
83
        .map((physicalRow) => hot.toVisualRow(physicalRow))
84
        .filter((row): row is number => row !== null);
85

86
      hot.validateRows(visualRows, (valid) => {
87
        if (!valid) {
88
          if (requestId === saveRequestCounterRef.current) {
89
            setSaveStatus('error');
90
          }
91

92
          return;
93
        }
94

95
        const rowsToSave = physicalRows
96
          .map((physicalRow) => hot.getSourceDataAtRow(physicalRow))
97
          .filter((row) => row !== undefined && row !== null);
98

99
        dirtyRowsRef.current.clear();
100
        setSaveStatus('saving');
101

102
        void saveRowsToBackend(rowsToSave)
103
          .then(() => {
104
            if (requestId === saveRequestCounterRef.current) {
105
              setSaveStatus('saved');
106
            }
107
          })
108
          .catch(() => {
109
            physicalRows.forEach((physicalRow) => dirtyRowsRef.current.add(physicalRow));
110

111
            if (requestId === saveRequestCounterRef.current) {
112
              setSaveStatus('error');
113
            }
114
          });
115
      });
116
    }, 800);
117
  };
118

119
  return (
120
    <>
121
      <div
122
        style={{
123
          marginBottom: '8px',
124
          fontFamily: 'Arial, sans-serif',
125
          fontSize: '13px',
126
          fontWeight: '600',
127
          color: statusColors[saveStatus],
128
        }}
129
      >
130
        {statusLabels[saveStatus]}
131
      </div>
132
      <HotTable
133
        ref={hotRef}
134
        data={data}
135
        colHeaders={['ID', 'Product', 'Stock', 'Price', 'Status']}
136
        columns={[
137
          { data: 'id', type: 'numeric', readOnly: true, width: 70 },
138
          { data: 'product', type: 'text', width: 180 },
139
          { data: 'stock', type: 'numeric', width: 90 },
140
          { data: 'price', type: 'numeric', numericFormat: { pattern: '$0,0.00' }, width: 110 },
141
          { data: 'status', type: 'text', width: 120 },
142
        ]}
143
        stretchH="all"
144
        height="auto"
145
        afterChange={handleAfterChange}
146
        licenseKey="non-commercial-and-evaluation"
147
      />
148
    </>
149
  );
150
};
151

152
export default ExampleComponent;

Overview

This recipe shows how to auto-save edited rows to a backend with afterChange, an 800 ms debounce, and row-level dirty tracking. It sends only modified rows, ignores loadData changes, and reports save status in the UI.

Difficulty: Intermediate
Time: ~20 minutes
Libraries: None (mock backend included)

What You’ll Build

A grid that:

Tracks edited rows in a dirty set.
Batches rapid edits into one debounced save request.
Sends only changed rows to a backend save function.
Shows save state as Saving…, Saved ✓, or Error.
Ignores loadData updates so initial data loading does not trigger saves.

Register modules and create sample data

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

4
registerAllModules();
5

6
const data = [
7
  { id: 1, product: 'Keyboard', stock: 14, price: 89, status: 'active' },
8
  { id: 2, product: 'Monitor', stock: 5, price: 249, status: 'active' },
9
  { id: 3, product: 'Dock', stock: 22, price: 139, status: 'draft' },
10
  { id: 4, product: 'Webcam', stock: 9, price: 119, status: 'active' },
11
  { id: 5, product: 'Headset', stock: 16, price: 99, status: 'paused' },
12
];

Use object rows with a stable primary key (id) so each payload can identify records.

Add a save status element

1
const statusEl = document.querySelector('#save-status');
2

3
function setSaveStatus(state: 'idle' | 'saving' | 'saved' | 'error') {
4
  if (!statusEl) {
5
    return;
6
  }
7

8
  const labels = {
9
    idle: 'No pending changes',
10
    saving: 'Saving...',
11
    saved: 'Saved ✓',
12
    error: 'Error',
13
  };
14

15
  statusEl.textContent = labels[state];
16
  statusEl.dataset.state = state;
17
}

This keeps save feedback separate from table logic.

Add a backend save function

1
async function saveRowsToBackend(rows) {
2
  await new Promise((resolve) => setTimeout(resolve, 450));
3

4
  // Replace this with fetch('/api/products', { method: 'PATCH', body: ... }) in production.
5
  // eslint-disable-next-line no-console
6
  console.log('PATCH /api/products', rows);
7
}

Use a mock promise so the recipe works without extra setup.

Track dirty rows and debounce saves

1
const dirtyRows = new Set<number>();
2
let saveTimeout: ReturnType<typeof setTimeout> | null = null;
3
let saveRequestCounter = 0;
4

5
function queueSave() {
6
  if (saveTimeout) {
7
    clearTimeout(saveTimeout);
8
  }
9

10
  saveTimeout = setTimeout(async () => {
11
    const physicalRows = Array.from(dirtyRows);
12

13
    if (physicalRows.length === 0) {
14
      return;
15
    }
16

17
    const requestId = ++saveRequestCounter;
18
    const rowsToSave = physicalRows
19
      .map((physicalRow) => hot.getSourceDataAtRow(physicalRow))
20
      .filter((row): row is RowData => row !== undefined && row !== null);
21

22
    dirtyRows.clear();
23
    setSaveStatus('saving');
24

25
    try {
26
      await saveRowsToBackend(rowsToSave);
27

28
      if (requestId === saveRequestCounter) {
29
        setSaveStatus('saved');
30
      }
31
    } catch (_error) {
32
      physicalRows.forEach((physicalRow) => dirtyRows.add(physicalRow));
33

34
      if (requestId === saveRequestCounter) {
35
        setSaveStatus('error');
36
      }
37
    }
38
  }, 800);
39
}

The debounce batches fast edits into one request, and the dirty set prevents duplicate row saves.

Use `afterChange` and ignore `loadData`

1
afterChange(changes, source) {
2
  if (!changes || source === 'loadData') {
3
    return;
4
  }
5

6
  changes.forEach(([visualRow, _prop, oldValue, newValue]) => {
7
    if (oldValue !== newValue) {
8
      const physicalRow = hot.toPhysicalRow(visualRow as number);
9

10
      if (typeof physicalRow === 'number') {
11
        dirtyRows.add(physicalRow);
12
      }
13
    }
14
  });
15

16
  queueSave();
17
}

This limits auto-save behavior to user edits and other non-load update sources.

Complete working example

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

4
registerAllModules();
5

6
type RowData = {
7
  id: number;
8
  product: string;
9
  stock: number;
10
  price: number;
11
  status: 'active' | 'draft' | 'paused';
12
};
13

14
const data: RowData[] = [
15
  { id: 1, product: 'Keyboard', stock: 14, price: 89, status: 'active' },
16
  { id: 2, product: 'Monitor', stock: 5, price: 249, status: 'active' },
17
  { id: 3, product: 'Dock', stock: 22, price: 139, status: 'draft' },
18
  { id: 4, product: 'Webcam', stock: 9, price: 119, status: 'active' },
19
  { id: 5, product: 'Headset', stock: 16, price: 99, status: 'paused' },
20
];
21

22
const container = document.querySelector('#example1');
23

24
if (container instanceof HTMLElement) {
25
  const statusEl = document.createElement('div');
26
  statusEl.id = 'save-status';
27
  container.before(statusEl);
28

29
  const dirtyRows = new Set<number>();
30
  let saveTimeout: ReturnType<typeof setTimeout> | null = null;
31
  let saveRequestCounter = 0;
32

33
  const setSaveStatus = (state: 'idle' | 'saving' | 'saved' | 'error') => {
34
    const labels = {
35
      idle: 'No pending changes',
36
      saving: 'Saving...',
37
      saved: 'Saved ✓',
38
      error: 'Error',
39
    };
40

41
    statusEl.textContent = labels[state];
42
    statusEl.dataset.state = state;
43
  };
44

45
  const saveRowsToBackend = async (rows: RowData[]) => {
46
    await new Promise((resolve) => setTimeout(resolve, 450));
47
    // eslint-disable-next-line no-console
48
    console.log('PATCH /api/products', rows);
49
  };
50

51
  const hot = new Handsontable(container, {
52
    data,
53
    rowHeaders: true,
54
    colHeaders: ['ID', 'Product', 'Stock', 'Price', 'Status'],
55
    columns: [
56
      { data: 'id', type: 'numeric', readOnly: true, width: 70 },
57
      { data: 'product', type: 'text', width: 180 },
58
      { data: 'stock', type: 'numeric', width: 90 },
59
      { data: 'price', type: 'numeric', numericFormat: { pattern: '$0,0.00' }, width: 110 },
60
      { data: 'status', type: 'text', width: 120 },
61
    ],
62
    stretchH: 'all',
63
    height: 'auto',
64
    licenseKey: 'non-commercial-and-evaluation',
65
    afterChange(changes, source) {
66
      if (!changes || source === 'loadData') {
67
        return;
68
      }
69

70
      changes.forEach(([visualRow, _prop, oldValue, newValue]) => {
71
        if (oldValue !== newValue) {
72
          const physicalRow = hot.toPhysicalRow(visualRow as number);
73

74
          if (typeof physicalRow === 'number') {
75
            dirtyRows.add(physicalRow);
76
          }
77
        }
78
      });
79

80
      if (saveTimeout) {
81
        clearTimeout(saveTimeout);
82
      }
83

84
      saveTimeout = setTimeout(async () => {
85
        const physicalRows = Array.from(dirtyRows);
86

87
        if (physicalRows.length === 0) {
88
          return;
89
        }
90

91
        const requestId = ++saveRequestCounter;
92
        const rowsToSave = physicalRows
93
          .map((physicalRow) => hot.getSourceDataAtRow(physicalRow))
94
          .filter((row): row is RowData => row !== undefined && row !== null);
95

96
        dirtyRows.clear();
97
        setSaveStatus('saving');
98

99
        try {
100
          await saveRowsToBackend(rowsToSave);
101

102
          if (requestId === saveRequestCounter) {
103
            setSaveStatus('saved');
104
          }
105
        } catch (_error) {
106
          physicalRows.forEach((physicalRow) => dirtyRows.add(physicalRow));
107

108
          if (requestId === saveRequestCounter) {
109
            setSaveStatus('error');
110
          }
111
        }
112
      }, 800);
113
    },
114
  });
115

116
  // Demonstrate that loadData updates do not trigger save requests.
117
  hot.loadData(data.map((row) => ({ ...row })));
118
  setSaveStatus('idle');
119
}

How It Works - Save lifecycle

User edits one or more cells.
afterChange captures changed visual rows, but skips source === 'loadData'.
The debounce timer resets on each new edit.
After 800 ms without edits, only dirty rows are collected and sent.
The UI status changes from Saving… to Saved ✓ (or Error on failure).

Production tips

Send stable IDs and changed fields only if your API accepts partial row updates.
Replace the mock save with authenticated fetch calls and server-side validation.
Add retry or backoff logic for transient network failures.
Show the last successful save timestamp for better user confidence.

What you learned

How to use afterChange to react to grid edits and skip system-generated changes by checking the source argument.
How debouncing limits the number of save requests when the user edits many cells in quick succession.
How dirty row tracking lets you send only changed rows instead of the full dataset.
How to provide visual feedback with a save status element that reflects idle, saving, saved, and error states.

Next steps

Replace the mock save with a real fetch call to your API endpoint.
Add undo/redo with a custom UI to let users revert changes before they are auto-saved.
Explore server-side data with NestJS for a full server-driven CRUD approach with the dataProvider plugin.