Load data from a REST API

This tutorial shows how to fetch JSON from a REST API and populate Handsontable after initialization. It starts the grid with data: [], shows a loading message, then displays success or error feedback in the UI.

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

4
registerAllModules();
5

6
const STATUS_LOADING = 'Loading users...';
7
const STATUS_READY = 'Loaded users from REST API.';
8
const STATUS_ERROR = 'Failed to load users. Try again.';
9

10
const container = document.querySelector('#example1');
11

12
if (!container) {
13
  throw new Error('Missing #example1 element.');
14
}
15

16
const status = document.createElement('p');
17
const retryButton = document.createElement('button');
18

19
status.textContent = STATUS_LOADING;
20
status.style.margin = '0';
21
status.style.fontFamily = 'Arial, sans-serif';
22
status.style.fontSize = '14px';
23

24
retryButton.type = 'button';
25
retryButton.textContent = 'Retry';
26
retryButton.hidden = true;
27
retryButton.style.marginBottom = '0';
28

29
const statusBar = document.createElement('div');
30
const gridContainer = document.createElement('div');
31

32
statusBar.style.display = 'flex';
33
statusBar.style.gap = '12px';
34
statusBar.style.alignItems = 'center';
35
statusBar.style.marginBottom = '8px';
36

37
container.appendChild(statusBar);
38
statusBar.appendChild(status);
39
statusBar.appendChild(retryButton);
40
container.appendChild(gridContainer);
41

42
const hot = new Handsontable(gridContainer, {
43
  data: [],
44
  colHeaders: ['ID', 'Name', 'Username', 'Email', 'City', 'Company'],
45
  columns: [
46
    { data: 'id', type: 'numeric', width: 70 },
47
    { data: 'name', type: 'text', width: 190 },
48
    { data: 'username', type: 'text', width: 150 },
49
    { data: 'email', type: 'text', width: 220 },
50
    { data: 'city', type: 'text', width: 140 },
51
    { data: 'company', type: 'text', width: 180 },
52
  ],
53
  rowHeaders: true,
54
  height: 360,
55
  width: '100%',
56
  stretchH: 'all',
57
  autoWrapRow: true,
58
  licenseKey: 'non-commercial-and-evaluation',
59
});
60

61
function setUiState({ loading = false, hasError = false, message = '' } = {}) {
62
  status.textContent = message;
63
  status.style.color = hasError
64
    ? 'var(--ht-cell-error-foreground-color, #c62828)'
65
    : 'var(--ht-foreground-color, #202124)';
66
  retryButton.hidden = !hasError;
67
  retryButton.disabled = loading;
68
}
69

70
function mapUsersToGridRows(users) {
71
  return users.map((user) => ({
72
    id: user.id,
73
    name: user.name,
74
    username: user.username,
75
    email: user.email,
76
    city: user.address?.city ?? '',
77
    company: user.company?.name ?? '',
78
  }));
79
}
80

81
async function loadUsers() {
82
  setUiState({ loading: true, message: STATUS_LOADING });
83

84
  try {
85
    const response = await fetch('https://jsonplaceholder.typicode.com/users');
86

87
    if (!response.ok) {
88
      throw new Error(`Request failed with status: ${response.status}`);
89
    }
90

91
    const users = await response.json();
92

93
    hot.loadData(mapUsersToGridRows(users));
94
    setUiState({ message: STATUS_READY });
95
  } catch (_error) {
96
    hot.loadData([]);
97
    setUiState({ hasError: true, message: STATUS_ERROR });
98
  }
99
}
100

101
retryButton.addEventListener('click', () => {
102
  loadUsers();
103
});
104

105
loadUsers();

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

4
registerAllModules();
5

6
type ApiUser = {
7
  id: number;
8
  name: string;
9
  username: string;
10
  email: string;
11
  address?: { city?: string };
12
  company?: { name?: string };
13
};
14

15
const STATUS_LOADING = 'Loading users...';
16
const STATUS_READY = 'Loaded users from REST API.';
17
const STATUS_ERROR = 'Failed to load users. Try again.';
18

19
const rootContainer = document.querySelector('#example1') as HTMLDivElement;
20

21
const statusBar = document.createElement('div');
22
const statusLabel = document.createElement('p');
23
const retryButton = document.createElement('button');
24
const gridContainer = document.createElement('div');
25

26
statusBar.style.display = 'flex';
27
statusBar.style.gap = '12px';
28
statusBar.style.alignItems = 'center';
29
statusBar.style.marginBottom = '8px';
30

31
statusLabel.style.margin = '0';
32
statusLabel.style.fontFamily = 'Arial, sans-serif';
33
statusLabel.style.fontSize = '14px';
34

35
retryButton.type = 'button';
36
retryButton.textContent = 'Retry';
37
retryButton.hidden = true;
38

39
rootContainer.appendChild(statusBar);
40
statusBar.appendChild(statusLabel);
41
statusBar.appendChild(retryButton);
42
rootContainer.appendChild(gridContainer);
43

44
const hot = new Handsontable(gridContainer, {
45
  data: [],
46
  colHeaders: ['ID', 'Name', 'Username', 'Email', 'City', 'Company'],
47
  columns: [
48
    { data: 'id', type: 'numeric', width: 70 },
49
    { data: 'name', type: 'text', width: 190 },
50
    { data: 'username', type: 'text', width: 150 },
51
    { data: 'email', type: 'text', width: 220 },
52
    { data: 'city', type: 'text', width: 140 },
53
    { data: 'company', type: 'text', width: 180 },
54
  ],
55
  rowHeaders: true,
56
  height: 360,
57
  width: '100%',
58
  stretchH: 'all',
59
  autoWrapRow: true,
60
  licenseKey: 'non-commercial-and-evaluation',
61
});
62

63
function setUiState({
64
  loading = false,
65
  hasError = false,
66
  message = '',
67
}: {
68
  loading?: boolean;
69
  hasError?: boolean;
70
  message?: string;
71
}) {
72
  statusLabel.textContent = message;
73
  statusLabel.style.color = hasError
74
    ? 'var(--ht-cell-error-foreground-color, #c62828)'
75
    : 'var(--ht-foreground-color, #202124)';
76
  retryButton.hidden = !hasError;
77
  retryButton.disabled = loading;
78
}
79

80
function mapUsersToGridRows(users: ApiUser[]) {
81
  return users.map((user) => ({
82
    id: user.id,
83
    name: user.name,
84
    username: user.username,
85
    email: user.email,
86
    city: user.address?.city ?? '',
87
    company: user.company?.name ?? '',
88
  }));
89
}
90

91
async function loadUsers() {
92
  setUiState({ loading: true, message: STATUS_LOADING });
93

94
  try {
95
    const response = await fetch('https://jsonplaceholder.typicode.com/users');
96

97
    if (!response.ok) {
98
      throw new Error(`Request failed with status: ${response.status}`);
99
    }
100

101
    const users = (await response.json()) as ApiUser[];
102

103
    hot.loadData(mapUsersToGridRows(users));
104
    setUiState({ message: STATUS_READY });
105
  } catch (_error) {
106
    hot.loadData([]);
107
    setUiState({ hasError: true, message: STATUS_ERROR });
108
  }
109
}
110

111
retryButton.addEventListener('click', () => {
112
  loadUsers();
113
});
114

115
loadUsers();

What this recipe covers

Fetching data from https://jsonplaceholder.typicode.com/users.
Initializing Handsontable with an empty dataset.
Filling the table with hot.loadData() when the response arrives.
Showing loading, success, and error states in the interface.
Defining a column configuration that matches API fields.

How it works

Create Handsontable with data: [].
Create a status element and retry button above the grid.
Start loadUsers() and set status to loading.
Fetch users and map nested fields (company.name, address.city) to flat row objects.
Call hot.loadData(rows) and show a success message.
If the request fails, show an error message and keep the table empty.

Using `updateData()` to preserve sorting and other states

The first example resets all grid state on every data load — column sort order, selection, and column order all go back to defaults. This is fine when no user state exists yet, but it creates a jarring experience in a running app where the user has already sorted or filtered the data.

hot.updateData() replaces the dataset while keeping every registered grid state intact. The second example demonstrates this: sort any column by clicking its header, then click Refresh. The sort order survives the data update.

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

4
registerAllModules();
5

6
const STATUS_LOADING = 'Loading users...';
7
const STATUS_READY =
8
  'Users loaded. Sort a column, then click "Refresh" to see that the column sort order is preserved.';
9
const STATUS_REFRESHING = 'Refreshing...';
10
const STATUS_REFRESHED = 'Data refreshed -- column sort order was preserved.';
11
const STATUS_ERROR = 'Failed to load users. Try again.';
12

13
const container = document.querySelector('#example2');
14

15
if (!container) {
16
  throw new Error('Missing #example2 element.');
17
}
18

19
const statusBar = document.createElement('div');
20
const status = document.createElement('p');
21
const refreshButton = document.createElement('button');
22
const retryButton = document.createElement('button');
23
const gridContainer = document.createElement('div');
24

25
statusBar.style.display = 'flex';
26
statusBar.style.gap = '12px';
27
statusBar.style.alignItems = 'center';
28
statusBar.style.marginBottom = '8px';
29

30
status.style.margin = '0';
31
status.style.fontFamily = 'Arial, sans-serif';
32
status.style.fontSize = '14px';
33

34
refreshButton.type = 'button';
35
refreshButton.textContent = 'Refresh';
36
refreshButton.hidden = true;
37
refreshButton.style.marginBottom = '0';
38

39
retryButton.type = 'button';
40
retryButton.textContent = 'Retry';
41
retryButton.hidden = true;
42
retryButton.style.marginBottom = '0';
43

44
container.appendChild(statusBar);
45
statusBar.appendChild(status);
46
statusBar.appendChild(refreshButton);
47
statusBar.appendChild(retryButton);
48
container.appendChild(gridContainer);
49

50
// Step 1: Initialize the grid with columnSorting enabled and an empty dataset.
51
const hot = new Handsontable(gridContainer, {
52
  data: [],
53
  colHeaders: ['ID', 'Name', 'Username', 'Email', 'City', 'Company'],
54
  columns: [
55
    { data: 'id', type: 'numeric', width: 70 },
56
    { data: 'name', type: 'text', width: 190 },
57
    { data: 'username', type: 'text', width: 150 },
58
    { data: 'email', type: 'text', width: 220 },
59
    { data: 'city', type: 'text', width: 140 },
60
    { data: 'company', type: 'text', width: 180 },
61
  ],
62
  // Enables clickable sort indicators on column headers.
63
  columnSorting: true,
64
  rowHeaders: true,
65
  height: 360,
66
  width: '100%',
67
  stretchH: 'all',
68
  autoWrapRow: true,
69
  licenseKey: 'non-commercial-and-evaluation',
70
});
71

72
// Step 2: A helper that keeps the toolbar consistent with the current request state.
73
function setUiState({ loading = false, hasError = false, message = '' } = {}) {
74
  status.textContent = message;
75
  status.style.color = hasError
76
    ? 'var(--ht-cell-error-foreground-color, #c62828)'
77
    : 'var(--ht-foreground-color, #202124)';
78
  // Show "Retry" only when there is an error.
79
  retryButton.hidden = !hasError;
80
  // Show "Refresh" only when the grid has data and no error is active.
81
  refreshButton.hidden = hasError || loading;
82
  refreshButton.disabled = loading;
83
  retryButton.disabled = loading;
84
}
85

86
// Step 3: Map the API response to flat row objects that match the column definitions.
87
function mapUsersToGridRows(users) {
88
  return users.map((user) => ({
89
    id: user.id,
90
    name: user.name,
91
    username: user.username,
92
    email: user.email,
93
    city: user.address?.city ?? '',
94
    company: user.company?.name ?? '',
95
  }));
96
}
97

98
// Step 4: Shared fetch helper used by both initialLoad() and refreshUsers().
99
async function fetchUsers() {
100
  const response = await fetch('https://jsonplaceholder.typicode.com/users');
101

102
  if (!response.ok) {
103
    throw new Error(`Request failed with status: ${response.status}`);
104
  }
105

106
  return response.json();
107
}
108

109
// Step 5: Initial load uses loadData(), which resets all grid states.
110
// This is correct for a first load -- there is no existing state to preserve.
111
async function initialLoad() {
112
  setUiState({ loading: true, message: STATUS_LOADING });
113

114
  try {
115
    const users = await fetchUsers();
116

117
    hot.loadData(mapUsersToGridRows(users));
118
    setUiState({ message: STATUS_READY });
119
  } catch (_error) {
120
    hot.loadData([]);
121
    setUiState({ hasError: true, message: STATUS_ERROR });
122
  }
123
}
124

125
// Step 6: Subsequent refreshes use updateData(), which replaces the data
126
// without resetting column sort order, selection, or column order.
127
async function refreshUsers() {
128
  setUiState({ loading: true, message: STATUS_REFRESHING });
129

130
  try {
131
    const users = await fetchUsers();
132

133
    hot.updateData(mapUsersToGridRows(users));
134
    setUiState({ message: STATUS_REFRESHED });
135
  } catch (_error) {
136
    // On error, do not clear the grid -- the existing data is still valid.
137
    setUiState({ hasError: true, message: STATUS_ERROR });
138
  }
139
}
140

141
refreshButton.addEventListener('click', () => {
142
  refreshUsers();
143
});
144

145
retryButton.addEventListener('click', () => {
146
  initialLoad();
147
});
148

149
initialLoad();

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

4
registerAllModules();
5

6
type ApiUser = {
7
  id: number;
8
  name: string;
9
  username: string;
10
  email: string;
11
  address?: { city?: string };
12
  company?: { name?: string };
13
};
14

15
const STATUS_LOADING = 'Loading users...';
16
const STATUS_READY =
17
  'Users loaded. Sort a column, then click "Refresh" to see that the column sort order is preserved.';
18
const STATUS_REFRESHING = 'Refreshing...';
19
const STATUS_REFRESHED = 'Data refreshed -- column sort order was preserved.';
20
const STATUS_ERROR = 'Failed to load users. Try again.';
21

22
const rootContainer = document.querySelector('#example2') as HTMLDivElement;
23

24
const statusBar = document.createElement('div');
25
const statusLabel = document.createElement('p');
26
const refreshButton = document.createElement('button');
27
const retryButton = document.createElement('button');
28
const gridContainer = document.createElement('div');
29

30
statusBar.style.display = 'flex';
31
statusBar.style.gap = '12px';
32
statusBar.style.alignItems = 'center';
33
statusBar.style.marginBottom = '8px';
34

35
statusLabel.style.margin = '0';
36
statusLabel.style.fontFamily = 'Arial, sans-serif';
37
statusLabel.style.fontSize = '14px';
38

39
refreshButton.type = 'button';
40
refreshButton.textContent = 'Refresh';
41
refreshButton.hidden = true;
42
refreshButton.style.marginBottom = '0';
43

44
retryButton.type = 'button';
45
retryButton.textContent = 'Retry';
46
retryButton.hidden = true;
47
retryButton.style.marginBottom = '0';
48

49
rootContainer.appendChild(statusBar);
50
statusBar.appendChild(statusLabel);
51
statusBar.appendChild(refreshButton);
52
statusBar.appendChild(retryButton);
53
rootContainer.appendChild(gridContainer);
54

55
// Step 1: Initialize the grid with columnSorting enabled and an empty dataset.
56
const hot = new Handsontable(gridContainer, {
57
  data: [],
58
  colHeaders: ['ID', 'Name', 'Username', 'Email', 'City', 'Company'],
59
  columns: [
60
    { data: 'id', type: 'numeric', width: 70 },
61
    { data: 'name', type: 'text', width: 190 },
62
    { data: 'username', type: 'text', width: 150 },
63
    { data: 'email', type: 'text', width: 220 },
64
    { data: 'city', type: 'text', width: 140 },
65
    { data: 'company', type: 'text', width: 180 },
66
  ],
67
  // Enables clickable sort indicators on column headers.
68
  columnSorting: true,
69
  rowHeaders: true,
70
  height: 360,
71
  width: '100%',
72
  stretchH: 'all',
73
  autoWrapRow: true,
74
  licenseKey: 'non-commercial-and-evaluation',
75
});
76

77
// Step 2: A helper that keeps the toolbar consistent with the current request state.
78
function setUiState({
79
  loading = false,
80
  hasError = false,
81
  message = '',
82
}: {
83
  loading?: boolean;
84
  hasError?: boolean;
85
  message?: string;
86
}) {
87
  statusLabel.textContent = message;
88
  statusLabel.style.color = hasError
89
    ? 'var(--ht-cell-error-foreground-color, #c62828)'
90
    : 'var(--ht-foreground-color, #202124)';
91
  // Show "Retry" only when there is an error.
92
  retryButton.hidden = !hasError;
93
  // Show "Refresh" only when the grid has data and no error is active.
94
  refreshButton.hidden = hasError || loading;
95
  refreshButton.disabled = loading;
96
  retryButton.disabled = loading;
97
}
98

99
// Step 3: Map the API response to flat row objects that match the column definitions.
100
function mapUsersToGridRows(users: ApiUser[]) {
101
  return users.map((user) => ({
102
    id: user.id,
103
    name: user.name,
104
    username: user.username,
105
    email: user.email,
106
    city: user.address?.city ?? '',
107
    company: user.company?.name ?? '',
108
  }));
109
}
110

111
// Step 4: Shared fetch helper used by both initialLoad() and refreshUsers().
112
async function fetchUsers(): Promise<ApiUser[]> {
113
  const response = await fetch('https://jsonplaceholder.typicode.com/users');
114

115
  if (!response.ok) {
116
    throw new Error(`Request failed with status: ${response.status}`);
117
  }
118

119
  return response.json() as Promise<ApiUser[]>;
120
}
121

122
// Step 5: Initial load uses loadData(), which resets all grid states.
123
// This is correct for a first load -- there is no existing state to preserve.
124
async function initialLoad() {
125
  setUiState({ loading: true, message: STATUS_LOADING });
126

127
  try {
128
    const users = await fetchUsers();
129

130
    hot.loadData(mapUsersToGridRows(users));
131
    setUiState({ message: STATUS_READY });
132
  } catch (_error) {
133
    hot.loadData([]);
134
    setUiState({ hasError: true, message: STATUS_ERROR });
135
  }
136
}
137

138
// Step 6: Subsequent refreshes use updateData(), which replaces the data
139
// without resetting column sort order, selection, or column order.
140
async function refreshUsers() {
141
  setUiState({ loading: true, message: STATUS_REFRESHING });
142

143
  try {
144
    const users = await fetchUsers();
145

146
    hot.updateData(mapUsersToGridRows(users));
147
    setUiState({ message: STATUS_REFRESHED });
148
  } catch (_error) {
149
    // On error, do not clear the grid -- the existing data is still valid.
150
    setUiState({ hasError: true, message: STATUS_ERROR });
151
  }
152
}
153

154
refreshButton.addEventListener('click', () => {
155
  refreshUsers();
156
});
157

158
retryButton.addEventListener('click', () => {
159
  initialLoad();
160
});
161

162
initialLoad();

What the second example covers

Enabling columnSorting so the user can sort by any column header.
Using hot.loadData() for the first fetch — there is no existing state to preserve.
Using hot.updateData() for every subsequent refresh to keep column sort order, selection, and column order intact.
Extracting a shared fetchUsers() helper that both functions call.
Keeping the “Refresh” button hidden until the grid has data, and the “Retry” button visible only on error.

`loadData()` vs `updateData()`

Both methods replace the grid’s dataset. The difference is what they reset:

Method	Resets sort order	Resets selection	Resets column order	Use when
`loadData()`	Yes	Yes	Yes	Initial load, schema change, or hard reset
`updateData()`	No	No	No	Periodic refresh or live-data feed

Enable column sorting

Add columnSorting: true to the grid options. Handsontable renders a sort-indicator arrow in each column header, and the sort state is preserved by updateData().
```
1
const hot = new Handsontable(gridContainer, {
2
  data: [],
3
  // ...column definitions...
4
  columnSorting: true,
5
  licenseKey: 'non-commercial-and-evaluation',
6
});
```
What’s happening:
- Clicking a column header cycles through ascending, descending, and no sort.
- The sort state is one of the registered states that updateData() leaves untouched.
- loadData(), by contrast, resets the sort state to “no sort” on every call.
Add a “Refresh” button to the toolbar

Create a second button next to the status label and add it to the status bar.
```
1
const refreshButton = document.createElement('button');
2

3
refreshButton.type = 'button';
4
refreshButton.textContent = 'Refresh';
5
refreshButton.hidden = true; // hidden until the initial load succeeds
6
refreshButton.style.marginBottom = '0';
7

8
statusBar.appendChild(refreshButton);
```
What’s happening:
- The button starts hidden so it does not appear during the initial loading phase.
- setUiState() makes it visible only when the grid contains data and no error is active.
Track four UI states

The second example has one more status constant than the first — a “Refreshing…” state shown while a refresh is in progress.
```
1
const STATUS_LOADING   = 'Loading users...';
2
const STATUS_READY     = 'Users loaded. Sort a column, then click "Refresh" to see that the column sort order is preserved.';
3
const STATUS_REFRESHING = 'Refreshing...';
4
const STATUS_REFRESHED = 'Data refreshed -- column sort order was preserved.';
5
const STATUS_ERROR     = 'Failed to load users. Try again.';
```
What’s happening:
- STATUS_LOADING — shown during the first fetch.
- STATUS_READY — shown after the first load; prompts the user to sort a column.
- STATUS_REFRESHING — shown while a refresh request is in flight.
- STATUS_REFRESHED — shown after a successful refresh; confirms that sort order was kept.
- STATUS_ERROR — shown when any request fails.

Update `setUiState()` to manage both buttons

The helper controls the “Refresh” button alongside the existing “Retry” button.

1
function setUiState({ loading = false, hasError = false, message = '' } = {}) {
2
  status.textContent = message;
3
  status.style.color = hasError
4
    ? 'var(--ht-cell-error-foreground-color, #c62828)'
5
    : 'var(--ht-foreground-color, #202124)';
6
  retryButton.hidden = !hasError;            // visible only on error
7
  refreshButton.hidden = hasError || loading; // visible only when data is ready
8
  refreshButton.disabled = loading;
9
  retryButton.disabled = loading;
10
}

What’s happening:

refreshButton.hidden = hasError || loading — the Refresh button appears only in the “ready” or “refreshed” state.
retryButton.hidden = !hasError — the Retry button appears only on error.
Both buttons are disabled while any request is in progress to prevent double-clicks.

Extract fetchUsers() as a shared helper

Both initialLoad() and refreshUsers() need to call the same endpoint. Extract the fetch logic into its own function so neither handler duplicates it.
```
1
async function fetchUsers() {
2
  const response = await fetch('https://jsonplaceholder.typicode.com/users');
3

4
  if (!response.ok) {
5
    throw new Error(`Request failed with status: ${response.status}`);
6
  }
7

8
  return response.json();
9
}
```
What’s happening:
- The function throws when the HTTP status is not 2xx, so callers can catch it in a unified catch block.
- The mapUsersToGridRows() helper (unchanged from the first example) runs in each caller, keeping fetchUsers() focused on the network concern only.
Use loadData() for the initial fetch

On the first load there is no state to preserve, so loadData() is the right choice. It also performs a clean reset if the user retries after an error.
```
1
async function initialLoad() {
2
  setUiState({ loading: true, message: STATUS_LOADING });
3

4
  try {
5
    const users = await fetchUsers();
6

7
    hot.loadData(mapUsersToGridRows(users));
8
    setUiState({ message: STATUS_READY });
9
  } catch (_error) {
10
    hot.loadData([]);
11
    setUiState({ hasError: true, message: STATUS_ERROR });
12
  }
13
}
```
What’s happening:
1. Set the UI to the “Loading…” state and disable both buttons.
2. Fetch users from the API.
3. Call hot.loadData() — resets all states (sort order, selection) and renders the fresh data.
4. On success, show STATUS_READY, which prompts the user to sort a column before refreshing.
5. On error, clear the grid with hot.loadData([]) and show the Retry button.
Use updateData() for subsequent refreshes

When the user clicks Refresh, call hot.updateData() instead of hot.loadData(). The grid replaces its data while keeping the sort order exactly as the user left it.
```
1
async function refreshUsers() {
2
  setUiState({ loading: true, message: STATUS_REFRESHING });
3

4
  try {
5
    const users = await fetchUsers();
6

7
    hot.updateData(mapUsersToGridRows(users));
8
    setUiState({ message: STATUS_REFRESHED });
9
  } catch (_error) {
10
    // On error, do not clear the grid -- the existing data is still valid.
11
    setUiState({ hasError: true, message: STATUS_ERROR });
12
  }
13
}
```
What’s happening:
1. Set the UI to “Refreshing…” and hide the Refresh button.
2. Fetch users from the API.
3. Call hot.updateData() — replaces the data while keeping column sort order, selection, and column order intact.
4. On success, show STATUS_REFRESHED and make the Refresh button available again.
5. On error, show the Retry button. The grid keeps its current data because updateData() was never called — no data is lost.
Key difference from loadData():
- loadData() fires beforeLoadData / afterLoadData hooks and resets all registered state.
- updateData() fires beforeUpdateData / afterUpdateData hooks and preserves all registered state.

Using `dataProvider` for automatic pagination and sorting

The first two examples manage the fetch lifecycle yourself: you call loadData() or updateData() at the right time and maintain loading state manually. Handsontable’s dataProvider option flips this model — you provide a fetchRows function and three CRUD callbacks, and the plugin drives everything else: initial load, pagination, column sorting, request cancellation, and loading overlays.

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

4
registerAllModules();
5

6
// Step 1: Cache the full response after the first request.
7
// Every subsequent fetchRows call (page change, column sort) reuses this
8
// without hitting the network again.
9
let cachedRows = null;
10

11
async function loadAllRows(signal) {
12
  if (cachedRows !== null) {
13
    return cachedRows;
14
  }
15

16
  const response = await fetch('https://jsonplaceholder.typicode.com/users', { signal });
17

18
  if (!response.ok) {
19
    throw new Error(`HTTP ${response.status}`);
20
  }
21

22
  const users = await response.json();
23

24
  cachedRows = users.map((u) => ({
25
    id: u.id,
26
    name: u.name,
27
    username: u.username,
28
    email: u.email,
29
    city: u.address?.city ?? '',
30
    company: u.company?.name ?? '',
31
  }));
32

33
  return cachedRows;
34
}
35

36
const container = document.querySelector('#example3');
37

38
if (!container) {
39
  throw new Error('Missing #example3 element.');
40
}
41

42
const statusBar = document.createElement('div');
43
const status = document.createElement('p');
44
const gridContainer = document.createElement('div');
45

46
statusBar.style.display = 'flex';
47
statusBar.style.alignItems = 'center';
48
statusBar.style.marginBottom = '8px';
49

50
status.style.margin = '0';
51
status.style.fontFamily = 'Arial, sans-serif';
52
status.style.fontSize = '14px';
53
status.textContent = 'Loading...';
54

55
container.appendChild(statusBar);
56
statusBar.appendChild(status);
57
container.appendChild(gridContainer);
58

59
new Handsontable(gridContainer, {
60
  // Step 2: Use dataProvider instead of a static data array.
61
  // Handsontable calls fetchRows automatically on init, page change, and sort change.
62
  dataProvider: {
63
    // rowId tells the plugin which field holds the stable row identity.
64
    // It is required for CRUD callbacks and internal refetch tracking.
65
    rowId: 'id',
66

67
    // Step 3: fetchRows receives current query parameters and an AbortSignal.
68
    // Return { rows, totalRows } so the Pagination plugin knows the total row count.
69
    async fetchRows({ page, pageSize, sort }, { signal }) {
70
      let rows = await loadAllRows(signal);
71

72
      // Step 4: Apply server-side sort from query parameters.
73
      // In production, pass sort.prop and sort.order to your API instead.
74
      if (sort) {
75
        rows = [...rows].sort((a, b) => {
76
          const av = a[sort.prop];
77
          const bv = b[sort.prop];
78
          const cmp = av < bv ? -1 : av > bv ? 1 : 0;
79

80
          return sort.order === 'asc' ? cmp : -cmp;
81
        });
82
      }
83

84
      // Step 5: Apply server-side pagination from query parameters.
85
      // In production, pass page and pageSize to your API instead.
86
      const start = (page - 1) * pageSize;
87

88
      return {
89
        rows: rows.slice(start, start + pageSize),
90
        totalRows: rows.length,
91
      };
92
    },
93

94
    // Step 6: CRUD callbacks. jsonplaceholder is read-only, so these are no-ops.
95
    // Replace with POST / PATCH / DELETE calls to a real API.
96
    onRowsCreate: async () => {},
97
    onRowsUpdate: async () => {},
98
    onRowsRemove: async () => {},
99
  },
100

101
  colHeaders: ['ID', 'Name', 'Username', 'Email', 'City', 'Company'],
102
  columns: [
103
    { data: 'id', type: 'numeric', width: 70, readOnly: true },
104
    { data: 'name', type: 'text', width: 190, readOnly: true },
105
    { data: 'username', type: 'text', width: 150, readOnly: true },
106
    { data: 'email', type: 'text', width: 220, readOnly: true },
107
    { data: 'city', type: 'text', width: 140, readOnly: true },
108
    { data: 'company', type: 'text', width: 180, readOnly: true },
109
  ],
110

111
  // Step 7: Enable the Pagination plugin and pass pageSize so the plugin knows
112
  // how many rows to request. columnSorting enables server-driven sort.
113
  // emptyDataState shows a loading overlay while fetchRows is in flight.
114
  pagination: { pageSize: 5 },
115
  columnSorting: true,
116
  emptyDataState: true,
117

118
  rowHeaders: true,
119
  height: 360,
120
  width: '100%',
121
  stretchH: 'all',
122
  autoWrapRow: true,
123
  licenseKey: 'non-commercial-and-evaluation',
124

125
  // Step 8: Use fetch hooks to update the status label.
126
  // skipLoading is true for internal refetches (after sort) -- skip the "Loading..." message
127
  // in those cases so the grid does not flash a spinner on every column header click.
128
  beforeDataProviderFetch: ({ skipLoading }) => {
129
    if (!skipLoading) {
130
      status.textContent = 'Loading...';
131
      status.style.color = 'var(--ht-foreground-color, #202124)';
132
    }
133
  },
134
  afterDataProviderFetch: () => {
135
    status.textContent = 'Loaded from REST API via dataProvider.';
136
    status.style.color = 'var(--ht-foreground-color, #202124)';
137
  },
138
  afterDataProviderFetchError: (error) => {
139
    status.textContent = `Error: ${error.message}`;
140
    status.style.color = 'var(--ht-notification-error-accent, #c62828)';
141
  },
142
});

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3
import type {
4
  DataProviderQueryParameters,
5
  DataProviderFetchOptions,
6
  DataProviderBeforeFetchParameters,
7
} from 'handsontable/plugins/dataProvider';
8

9
registerAllModules();
10

11
type UserRow = {
12
  id: number;
13
  name: string;
14
  username: string;
15
  email: string;
16
  city: string;
17
  company: string;
18
};
19

20
// Step 1: Cache the full response after the first request.
21
// Every subsequent fetchRows call (page change, column sort) reuses this
22
// without hitting the network again.
23
let cachedRows: UserRow[] | null = null;
24

25
async function loadAllRows(signal: AbortSignal): Promise<UserRow[]> {
26
  if (cachedRows !== null) {
27
    return cachedRows;
28
  }
29

30
  const response = await fetch('https://jsonplaceholder.typicode.com/users', { signal });
31

32
  if (!response.ok) {
33
    throw new Error(`HTTP ${response.status}`);
34
  }
35

36
  const users = (await response.json()) as Array<{
37
    id: number;
38
    name: string;
39
    username: string;
40
    email: string;
41
    address?: { city?: string };
42
    company?: { name?: string };
43
  }>;
44

45
  cachedRows = users.map((u) => ({
46
    id: u.id,
47
    name: u.name,
48
    username: u.username,
49
    email: u.email,
50
    city: u.address?.city ?? '',
51
    company: u.company?.name ?? '',
52
  }));
53

54
  return cachedRows;
55
}
56

57
const rootContainer = document.querySelector('#example3') as HTMLDivElement;
58

59
const statusBar = document.createElement('div');
60
const statusLabel = document.createElement('p');
61
const gridContainer = document.createElement('div');
62

63
statusBar.style.display = 'flex';
64
statusBar.style.alignItems = 'center';
65
statusBar.style.marginBottom = '8px';
66

67
statusLabel.style.margin = '0';
68
statusLabel.style.fontFamily = 'Arial, sans-serif';
69
statusLabel.style.fontSize = '14px';
70
statusLabel.style.color = 'var(--ht-foreground-color, #202124)';
71
statusLabel.textContent = 'Loading...';
72

73
rootContainer.appendChild(statusBar);
74
statusBar.appendChild(statusLabel);
75
rootContainer.appendChild(gridContainer);
76

77
new Handsontable(gridContainer, {
78
  // Step 2: Use dataProvider instead of a static data array.
79
  // Handsontable calls fetchRows automatically on init, page change, and sort change.
80
  dataProvider: {
81
    // rowId tells the plugin which field holds the stable row identity.
82
    // It is required for CRUD callbacks and internal refetch tracking.
83
    rowId: 'id',
84

85
    // Step 3: fetchRows receives current query parameters and an AbortSignal.
86
    // Return { rows, totalRows } so the Pagination plugin knows the total row count.
87
    async fetchRows(
88
      { page, pageSize, sort }: DataProviderQueryParameters,
89
      { signal }: DataProviderFetchOptions
90
    ) {
91
      let rows = await loadAllRows(signal);
92

93
      // Step 4: Apply server-side sort from query parameters.
94
      // In production, pass sort.prop and sort.order to your API instead.
95
      if (sort) {
96
        rows = [...rows].sort((a, b) => {
97
          const av = a[sort.prop as keyof UserRow];
98
          const bv = b[sort.prop as keyof UserRow];
99
          const cmp = av < bv ? -1 : av > bv ? 1 : 0;
100

101
          return sort.order === 'asc' ? cmp : -cmp;
102
        });
103
      }
104

105
      // Step 5: Apply server-side pagination from query parameters.
106
      // In production, pass page and pageSize to your API instead.
107
      const start = (page - 1) * pageSize;
108

109
      return {
110
        rows: rows.slice(start, start + pageSize),
111
        totalRows: rows.length,
112
      };
113
    },
114

115
    // Step 6: CRUD callbacks. jsonplaceholder is read-only, so these are no-ops.
116
    // Replace with POST / PATCH / DELETE calls to a real API.
117
    onRowsCreate: async () => {},
118
    onRowsUpdate: async () => {},
119
    onRowsRemove: async () => {},
120
  },
121

122
  colHeaders: ['ID', 'Name', 'Username', 'Email', 'City', 'Company'],
123
  columns: [
124
    { data: 'id', type: 'numeric', width: 70, readOnly: true },
125
    { data: 'name', type: 'text', width: 190, readOnly: true },
126
    { data: 'username', type: 'text', width: 150, readOnly: true },
127
    { data: 'email', type: 'text', width: 220, readOnly: true },
128
    { data: 'city', type: 'text', width: 140, readOnly: true },
129
    { data: 'company', type: 'text', width: 180, readOnly: true },
130
  ],
131

132
  // Step 7: Enable the Pagination plugin and pass pageSize so the plugin knows
133
  // how many rows to request. columnSorting enables server-driven sort.
134
  // emptyDataState shows a loading overlay while fetchRows is in flight.
135
  pagination: { pageSize: 5 },
136
  columnSorting: true,
137
  emptyDataState: true,
138

139
  rowHeaders: true,
140
  height: 360,
141
  width: '100%',
142
  stretchH: 'all',
143
  autoWrapRow: true,
144
  licenseKey: 'non-commercial-and-evaluation',
145

146
  // Step 8: Use fetch hooks to update the status label.
147
  // skipLoading is true for internal refetches (after sort) -- skip the "Loading..." message
148
  // in those cases so the grid does not flash a spinner on every column header click.
149
  beforeDataProviderFetch: ({ skipLoading }: DataProviderBeforeFetchParameters) => {
150
    if (!skipLoading) {
151
      statusLabel.textContent = 'Loading...';
152
      statusLabel.style.color = 'var(--ht-foreground-color, #202124)';
153
    }
154
  },
155
  afterDataProviderFetch: () => {
156
    statusLabel.textContent = 'Loaded from REST API via dataProvider.';
157
    statusLabel.style.color = 'var(--ht-foreground-color, #202124)';
158
  },
159
  afterDataProviderFetchError: (error: Error) => {
160
    statusLabel.textContent = `Error: ${error.message}`;
161
    statusLabel.style.color = 'var(--ht-notification-error-accent, #c62828)';
162
  },
163
});

What the third example covers

Configuring dataProvider with rowId, fetchRows, and CRUD callbacks.
Sorting rows in fetchRows from the sort query parameter before returning a page.
Slicing rows in fetchRows using the page and pageSize query parameters.
Enabling pagination, columnSorting, and emptyDataState so the plugin drives navigation and loading overlays.
Using beforeDataProviderFetch, afterDataProviderFetch, and afterDataProviderFetchError hooks for status feedback.
Passing an AbortSignal to fetch so superseded requests are cancelled automatically.

When to use each approach

Approach	When to use
`loadData()`	One-shot load on page init; or when you want to reset all grid state (sort, selection) together with the data.
`updateData()`	Periodic refresh where the user’s sort order, selection, and column layout must survive the data update.
`dataProvider`	Backend-driven pagination, sorting, and filtering; CRUD that round-trips to a server; any dataset too large to keep in the browser.

Cache the remote response

The dataProvider plugin calls fetchRows every time the user changes page or clicks a sort header. If the API does not support server-side pagination or sorting (as with jsonplaceholder), fetch the full dataset once and reuse it.
```
1
let cachedRows = null;
2

3
async function loadAllRows(signal) {
4
  if (cachedRows !== null) {
5
    return cachedRows;
6
  }
7

8
  const response = await fetch('https://jsonplaceholder.typicode.com/users', { signal });
9

10
  if (!response.ok) {
11
    throw new Error(`HTTP ${response.status}`);
12
  }
13

14
  const users = await response.json();
15

16
  cachedRows = users.map((u) => ({
17
    id: u.id, name: u.name, username: u.username,
18
    email: u.email,
19
    city: u.address?.city ?? '',
20
    company: u.company?.name ?? '',
21
  }));
22

23
  return cachedRows;
24
}
```
What’s happening:
- cachedRows starts as null. The first call hits the network; every later call returns the same array.
- signal is the AbortSignal from fetchRows — passing it to fetch cancels the network request if the user sorts or changes pages before the current fetch finishes.
- The raw API response is mapped to flat row objects that match your columns data keys.
In production: Pass page, pageSize, sort, and filters directly to your API query string — no client-side caching needed. The client-side sort and slice shown in Steps 4 and 5 replace the server query.
Replace the data array with a dataProvider object

Instead of passing data: [] and calling hot.loadData(), pass a dataProvider object. Handsontable ignores any data array when the provider is complete.
```
1
new Handsontable(gridContainer, {
2
  dataProvider: {
3
    rowId: 'id',
4
    fetchRows: ...,
5
    onRowsCreate: async () => {},
6
    onRowsUpdate: async () => {},
7
    onRowsRemove: async () => {},
8
  },
9
  // ...
10
});
```
What’s happening:
- rowId: 'id' tells the plugin which property on each row object carries the stable row identity. It is required for the CRUD callbacks, refetch bookkeeping, and modifyRowHeader numbering across pages.
- All five keys (rowId, fetchRows, onRowsCreate, onRowsUpdate, onRowsRemove) must be valid for the configuration to be complete. If any are missing, the plugin stays enabled but the affected operations no-op.
Implement fetchRows

fetchRows is the only required async function. It receives queryParameters and an options object that carries an AbortSignal.
```
1
async fetchRows({ page, pageSize, sort }, { signal }) {
2
  const rows = await loadAllRows(signal);
3
  // ...
4
  return { rows: pagedSlice, totalRows: rows.length };
5
}
```
What’s happening:
- page — 1-based page index driven by the Pagination plugin.
- pageSize — rows per page; matches pagination: { pageSize: 5 } in grid options.
- sort — { prop, order } object when a column header is sorted, or null when unsorted.
- { signal } — AbortSignal from the plugin. Pass it to your fetch call so superseded requests are cancelled.
- Return { rows, totalRows }. totalRows is the unsliced count — the Pagination plugin uses it to calculate the page count and navigation controls.
Apply sort from query parameters

When sort is non-null, sort a copy of the rows array before slicing. Never mutate the cached array.
```
1
if (sort) {
2
  rows = [...rows].sort((a, b) => {
3
    const av = a[sort.prop];
4
    const bv = b[sort.prop];
5
    const cmp = av < bv ? -1 : av > bv ? 1 : 0;
6

7
    return sort.order === 'asc' ? cmp : -cmp;
8
  });
9
}
```
What’s happening:
- sort.prop is the data key of the sorted column (for example 'name' or 'email').
- sort.order is 'asc' or 'desc'.
- The spread [...rows] prevents mutating the cached array. Sorting is referentially transparent — the cache always holds the original order.
In production: You would not sort in the browser at all. Pass sort.prop and sort.order as query parameters to your API (?_sort=name&_order=asc for jsonplaceholder-style, or your own convention).
Apply pagination from query parameters

Slice the (sorted) array using page and pageSize.
```
1
const start = (page - 1) * pageSize;
2

3
return {
4
  rows: rows.slice(start, start + pageSize),
5
  totalRows: rows.length,
6
};
```
What’s happening:
- page is 1-based, so page 1 starts at index 0, page 2 starts at index pageSize, and so on.
- totalRows is the length of the full sorted array — not the slice. The Pagination plugin uses this to render the correct total page count.
In production: Pass page and pageSize to your API (?_page=1&_limit=5 for jsonplaceholder) and return the server’s own total or count field as totalRows.
Provide CRUD callbacks

All three callbacks must be valid functions for the dataProvider configuration to be complete. For a read-only API, return resolved promises without calling the server.
```
1
onRowsCreate: async () => {},
2
onRowsUpdate: async () => {},
3
onRowsRemove: async () => {},
```
What’s happening:
- The plugin serializes CRUD calls — a second mutation waits for the first to finish.
- After each callback resolves, the plugin automatically refetches the current page.
- These no-ops accept any user edit from the context menu but discard it on the next refetch. For a truly read-only grid, set readOnly: true on each column to prevent edits in the first place (as this example does).
In production: Implement POST, PATCH, and DELETE calls here. See the Server-side data guide for payload shapes and the full CRUD lifecycle.
Enable pagination, columnSorting, and emptyDataState
```
1
pagination: { pageSize: 5 },
2
columnSorting: true,
3
emptyDataState: true,
```
What’s happening:
- pagination: { pageSize: 5 } enables the Pagination plugin and sets 5 rows per page. The plugin renders navigation controls below the grid and passes page and pageSize into every fetchRows call.
- columnSorting: true enables server-driven single-column sorting. Clicking a header sets sort in the next fetchRows call. (multiColumnSorting is incompatible with dataProvider — use columnSorting only.)
- emptyDataState: true renders a loading overlay while fetchRows is in flight and an “empty” state when the response contains zero rows.
Use fetch hooks for status feedback
```
1
beforeDataProviderFetch: ({ skipLoading }) => {
2
  if (!skipLoading) {
3
    status.textContent = 'Loading...';
4
  }
5
},
6
afterDataProviderFetch: () => {
7
  status.textContent = 'Loaded from REST API via dataProvider.';
8
},
9
afterDataProviderFetchError: (error) => {
10
  status.textContent = `Error: ${error.message}`;
11
  status.style.color = 'var(--ht-cell-error-foreground-color, #c62828)';
12
},
```
What’s happening:
- beforeDataProviderFetch fires before every fetch. The skipLoading flag is true for internal refetches triggered after a sort or CRUD operation — skip updating the status label in those cases so the label does not flash “Loading…” on every column header click.
- afterDataProviderFetch fires after a successful fetch. Update the status label to confirm data was loaded.
- afterDataProviderFetchError fires when fetchRows rejects with a non-abort error. Update the status label with the error message. If you also set dialog: true in the grid options, the built-in Dialog plugin shows an error modal in addition to this hook.

Saving data

Server-side data

What you learned

How to initialize Handsontable with data: [] and populate it after an async fetch with hot.loadData().
How hot.loadData() resets all grid state and hot.updateData() preserves column sort order, selection, and column order on refreshes.
How to use beforeDataProviderFetch, afterDataProviderFetch, and afterDataProviderFetchError hooks for status feedback during dataProvider fetches.
How the dataProvider architecture handles pagination, server-side sorting, and CRUD automatically — removing the need for manual data management.

Next steps

Explore Load data from a GraphQL API for the same patterns with a GraphQL backend.
Explore Auto-save changes to a backend to persist grid edits automatically after a debounce delay.

Load data from a REST API

What this recipe covers

How it works

Using `updateData()` to preserve sorting and other states

What the second example covers

`loadData()` vs `updateData()`

Enable column sorting

Track four UI states

Update `setUiState()` to manage both buttons

Extract `fetchUsers()` as a shared helper

Use `loadData()` for the initial fetch

Use `updateData()` for subsequent refreshes

What the third example covers

When to use each approach

Cache the remote response

Replace the `data` array with a `dataProvider` object

Implement `fetchRows`

Apply sort from query parameters

Provide CRUD callbacks

Use fetch hooks for status feedback

What you learned

Next steps

Load data from a REST API

What this recipe covers

How it works

Using updateData() to preserve sorting and other states

What the second example covers

loadData() vs updateData()

Enable column sorting

Add a “Refresh” button to the toolbar

Track four UI states

Update setUiState() to manage both buttons

Extract fetchUsers() as a shared helper

Use loadData() for the initial fetch

Use updateData() for subsequent refreshes

Using dataProvider for automatic pagination and sorting

What the third example covers

When to use each approach

Cache the remote response

Replace the data array with a dataProvider object

Implement fetchRows

Apply sort from query parameters

Apply pagination from query parameters

Provide CRUD callbacks

Enable pagination, columnSorting, and emptyDataState

Use fetch hooks for status feedback

Related

What you learned

Next steps

Using `updateData()` to preserve sorting and other states

`loadData()` vs `updateData()`

Update `setUiState()` to manage both buttons

Extract `fetchUsers()` as a shared helper

Use `loadData()` for the initial fetch

Use `updateData()` for subsequent refreshes

Using `dataProvider` for automatic pagination and sorting

Replace the `data` array with a `dataProvider` object

Implement `fetchRows`

Enable `pagination`, `columnSorting`, and `emptyDataState`