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 { useState, useEffect } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
registerAllModules();
6

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

11
async function fetchUsers() {
12
  const response = await fetch('https://jsonplaceholder.typicode.com/users');
13

14
  if (!response.ok) {
15
    throw new Error(`Request failed with status: ${response.status}`);
16
  }
17

18
  return response.json();
19
}
20

21
function mapUsersToGridRows(users) {
22
  return users.map((user) => ({
23
    id: user.id,
24
    name: user.name,
25
    username: user.username,
26
    email: user.email,
27
    city: user.address?.city ?? '',
28
    company: user.company?.name ?? '',
29
  }));
30
}
31

32
const ExampleComponent = () => {
33
  const [rows, setRows] = useState([]);
34
  const [status, setStatus] = useState(STATUS_LOADING);
35
  const [hasError, setHasError] = useState(false);
36

37
  const loadUsers = async () => {
38
    setStatus(STATUS_LOADING);
39
    setHasError(false);
40

41
    try {
42
      const users = await fetchUsers();
43

44
      setRows(mapUsersToGridRows(users));
45
      setStatus(STATUS_READY);
46
    } catch (_error) {
47
      setRows([]);
48
      setHasError(true);
49
      setStatus(STATUS_ERROR);
50
    }
51
  };
52

53
  // eslint-disable-next-line react-hooks/exhaustive-deps
54
  useEffect(() => { loadUsers(); }, []);
55

56
  return (
57
    <div>
58
      <div style={{ display: 'flex', gap: '12px', alignItems: 'center', marginBottom: '8px' }}>
59
        <p style={{ margin: 0, fontFamily: 'Arial, sans-serif', fontSize: '14px', color: hasError ? '#c62828' : '#202124' }}>
60
          {status}
61
        </p>
62
        {hasError && (
63
          <button type="button" onClick={loadUsers}>
64
            Retry
65
          </button>
66
        )}
67
      </div>
68
      <HotTable
69
        data={rows}
70
        colHeaders={['ID', 'Name', 'Username', 'Email', 'City', 'Company']}
71
        columns={[
72
          { data: 'id', type: 'numeric', width: 70, readOnly: true },
73
          { data: 'name', type: 'text', width: 190, readOnly: true },
74
          { data: 'username', type: 'text', width: 150, readOnly: true },
75
          { data: 'email', type: 'text', width: 220, readOnly: true },
76
          { data: 'city', type: 'text', width: 140, readOnly: true },
77
          { data: 'company', type: 'text', width: 180, readOnly: true },
78
        ]}
79
        rowHeaders={true}
80
        height={360}
81
        width="100%"
82
        stretchH="all"
83
        autoWrapRow={true}
84
        licenseKey="non-commercial-and-evaluation"
85
      />
86
    </div>
87
  );
88
};
89

90
export default ExampleComponent;

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

5
registerAllModules();
6

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

16
type UserRow = {
17
  id: number;
18
  name: string;
19
  username: string;
20
  email: string;
21
  city: string;
22
  company: string;
23
};
24

25
const STATUS_LOADING = 'Loading users...';
26
const STATUS_READY = 'Loaded users from REST API.';
27
const STATUS_ERROR = 'Failed to load users. Try again.';
28

29
async function fetchUsers(): Promise<ApiUser[]> {
30
  const response = await fetch('https://jsonplaceholder.typicode.com/users');
31

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

36
  return response.json() as Promise<ApiUser[]>;
37
}
38

39
function mapUsersToGridRows(users: ApiUser[]): UserRow[] {
40
  return users.map((user) => ({
41
    id: user.id,
42
    name: user.name,
43
    username: user.username,
44
    email: user.email,
45
    city: user.address?.city ?? '',
46
    company: user.company?.name ?? '',
47
  }));
48
}
49

50
const ExampleComponent = () => {
51
  const [rows, setRows] = useState<UserRow[]>([]);
52
  const [status, setStatus] = useState(STATUS_LOADING);
53
  const [hasError, setHasError] = useState(false);
54

55
  const loadUsers = async () => {
56
    setStatus(STATUS_LOADING);
57
    setHasError(false);
58

59
    try {
60
      const users = await fetchUsers();
61

62
      setRows(mapUsersToGridRows(users));
63
      setStatus(STATUS_READY);
64
    } catch (_error) {
65
      setRows([]);
66
      setHasError(true);
67
      setStatus(STATUS_ERROR);
68
    }
69
  };
70

71
  // eslint-disable-next-line react-hooks/exhaustive-deps
72
  useEffect(() => { loadUsers(); }, []);
73

74
  return (
75
    <div>
76
      <div style={{ display: 'flex', gap: '12px', alignItems: 'center', marginBottom: '8px' }}>
77
        <p style={{ margin: 0, fontFamily: 'Arial, sans-serif', fontSize: '14px', color: hasError ? '#c62828' : '#202124' }}>
78
          {status}
79
        </p>
80
        {hasError && (
81
          <button type="button" onClick={loadUsers}>
82
            Retry
83
          </button>
84
        )}
85
      </div>
86
      <HotTable
87
        data={rows}
88
        colHeaders={['ID', 'Name', 'Username', 'Email', 'City', 'Company']}
89
        columns={[
90
          { data: 'id', type: 'numeric', width: 70, readOnly: true },
91
          { data: 'name', type: 'text', width: 190, readOnly: true },
92
          { data: 'username', type: 'text', width: 150, readOnly: true },
93
          { data: 'email', type: 'text', width: 220, readOnly: true },
94
          { data: 'city', type: 'text', width: 140, readOnly: true },
95
          { data: 'company', type: 'text', width: 180, readOnly: true },
96
        ]}
97
        rowHeaders={true}
98
        height={360}
99
        width="100%"
100
        stretchH="all"
101
        autoWrapRow={true}
102
        licenseKey="non-commercial-and-evaluation"
103
      />
104
    </div>
105
  );
106
};
107

108
export default ExampleComponent;

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 { useState, useEffect, useRef } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
registerAllModules();
6

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

14
async function fetchUsers() {
15
  const response = await fetch('https://jsonplaceholder.typicode.com/users');
16

17
  if (!response.ok) {
18
    throw new Error(`Request failed with status: ${response.status}`);
19
  }
20

21
  return response.json();
22
}
23

24
function mapUsersToGridRows(users) {
25
  return users.map((user) => ({
26
    id: user.id,
27
    name: user.name,
28
    username: user.username,
29
    email: user.email,
30
    city: user.address?.city ?? '',
31
    company: user.company?.name ?? '',
32
  }));
33
}
34

35
const ExampleComponent = () => {
36
  const hotRef = useRef(null);
37
  const [status, setStatus] = useState(STATUS_LOADING);
38
  const [hasError, setHasError] = useState(false);
39
  const [showRefresh, setShowRefresh] = useState(false);
40

41
  const initialLoad = async () => {
42
    setStatus(STATUS_LOADING);
43
    setHasError(false);
44
    setShowRefresh(false);
45

46
    try {
47
      const users = await fetchUsers();
48

49
      hotRef.current?.hotInstance?.loadData(mapUsersToGridRows(users));
50
      setStatus(STATUS_READY);
51
      setShowRefresh(true);
52
    } catch (_error) {
53
      hotRef.current?.hotInstance?.loadData([]);
54
      setHasError(true);
55
      setStatus(STATUS_ERROR);
56
    }
57
  };
58

59
  const refreshUsers = async () => {
60
    setStatus(STATUS_REFRESHING);
61
    setHasError(false);
62
    setShowRefresh(false);
63

64
    try {
65
      const users = await fetchUsers();
66

67
      hotRef.current?.hotInstance?.updateData(mapUsersToGridRows(users));
68
      setStatus(STATUS_REFRESHED);
69
      setShowRefresh(true);
70
    } catch (_error) {
71
      setHasError(true);
72
      setStatus(STATUS_ERROR);
73
    }
74
  };
75

76
  // eslint-disable-next-line react-hooks/exhaustive-deps
77
  useEffect(() => { initialLoad(); }, []);
78

79
  return (
80
    <div>
81
      <div style={{ display: 'flex', gap: '12px', alignItems: 'center', marginBottom: '8px' }}>
82
        <p style={{ margin: 0, fontFamily: 'Arial, sans-serif', fontSize: '14px', color: hasError ? '#c62828' : '#202124' }}>
83
          {status}
84
        </p>
85
        {showRefresh && !hasError && (
86
          <button type="button" onClick={refreshUsers} style={{ marginBottom: 0 }}>
87
            Refresh
88
          </button>
89
        )}
90
        {hasError && (
91
          <button type="button" onClick={initialLoad} style={{ marginBottom: 0 }}>
92
            Retry
93
          </button>
94
        )}
95
      </div>
96
      <HotTable
97
        ref={hotRef}
98
        colHeaders={['ID', 'Name', 'Username', 'Email', 'City', 'Company']}
99
        columns={[
100
          { data: 'id', type: 'numeric', width: 70, readOnly: true },
101
          { data: 'name', type: 'text', width: 190, readOnly: true },
102
          { data: 'username', type: 'text', width: 150, readOnly: true },
103
          { data: 'email', type: 'text', width: 220, readOnly: true },
104
          { data: 'city', type: 'text', width: 140, readOnly: true },
105
          { data: 'company', type: 'text', width: 180, readOnly: true },
106
        ]}
107
        columnSorting={true}
108
        rowHeaders={true}
109
        height={360}
110
        width="100%"
111
        stretchH="all"
112
        autoWrapRow={true}
113
        licenseKey="non-commercial-and-evaluation"
114
      />
115
    </div>
116
  );
117
};
118

119
export default ExampleComponent;

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

5
registerAllModules();
6

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

16
type UserRow = {
17
  id: number;
18
  name: string;
19
  username: string;
20
  email: string;
21
  city: string;
22
  company: string;
23
};
24

25
const STATUS_LOADING = 'Loading users...';
26
const STATUS_READY =
27
  'Users loaded. Sort a column, then click "Refresh" to see that the column sort order is preserved.';
28
const STATUS_REFRESHING = 'Refreshing...';
29
const STATUS_REFRESHED = 'Data refreshed -- column sort order was preserved.';
30
const STATUS_ERROR = 'Failed to load users. Try again.';
31

32
async function fetchUsers(): Promise<ApiUser[]> {
33
  const response = await fetch('https://jsonplaceholder.typicode.com/users');
34

35
  if (!response.ok) {
36
    throw new Error(`Request failed with status: ${response.status}`);
37
  }
38

39
  return response.json() as Promise<ApiUser[]>;
40
}
41

42
function mapUsersToGridRows(users: ApiUser[]): UserRow[] {
43
  return users.map((user) => ({
44
    id: user.id,
45
    name: user.name,
46
    username: user.username,
47
    email: user.email,
48
    city: user.address?.city ?? '',
49
    company: user.company?.name ?? '',
50
  }));
51
}
52

53
const ExampleComponent = () => {
54
  const hotRef = useRef<InstanceType<typeof HotTable>>(null);
55
  const [status, setStatus] = useState(STATUS_LOADING);
56
  const [hasError, setHasError] = useState(false);
57
  const [showRefresh, setShowRefresh] = useState(false);
58

59
  const initialLoad = async () => {
60
    setStatus(STATUS_LOADING);
61
    setHasError(false);
62
    setShowRefresh(false);
63

64
    try {
65
      const users = await fetchUsers();
66

67
      hotRef.current?.hotInstance?.loadData(mapUsersToGridRows(users));
68
      setStatus(STATUS_READY);
69
      setShowRefresh(true);
70
    } catch (_error) {
71
      hotRef.current?.hotInstance?.loadData([]);
72
      setHasError(true);
73
      setStatus(STATUS_ERROR);
74
    }
75
  };
76

77
  const refreshUsers = async () => {
78
    setStatus(STATUS_REFRESHING);
79
    setHasError(false);
80
    setShowRefresh(false);
81

82
    try {
83
      const users = await fetchUsers();
84

85
      hotRef.current?.hotInstance?.updateData(mapUsersToGridRows(users));
86
      setStatus(STATUS_REFRESHED);
87
      setShowRefresh(true);
88
    } catch (_error) {
89
      setHasError(true);
90
      setStatus(STATUS_ERROR);
91
    }
92
  };
93

94
  // eslint-disable-next-line react-hooks/exhaustive-deps
95
  useEffect(() => { initialLoad(); }, []);
96

97
  return (
98
    <div>
99
      <div style={{ display: 'flex', gap: '12px', alignItems: 'center', marginBottom: '8px' }}>
100
        <p style={{ margin: 0, fontFamily: 'Arial, sans-serif', fontSize: '14px', color: hasError ? '#c62828' : '#202124' }}>
101
          {status}
102
        </p>
103
        {showRefresh && !hasError && (
104
          <button type="button" onClick={refreshUsers} style={{ marginBottom: 0 }}>
105
            Refresh
106
          </button>
107
        )}
108
        {hasError && (
109
          <button type="button" onClick={initialLoad} style={{ marginBottom: 0 }}>
110
            Retry
111
          </button>
112
        )}
113
      </div>
114
      <HotTable
115
        ref={hotRef}
116
        colHeaders={['ID', 'Name', 'Username', 'Email', 'City', 'Company']}
117
        columns={[
118
          { data: 'id', type: 'numeric', width: 70, readOnly: true },
119
          { data: 'name', type: 'text', width: 190, readOnly: true },
120
          { data: 'username', type: 'text', width: 150, readOnly: true },
121
          { data: 'email', type: 'text', width: 220, readOnly: true },
122
          { data: 'city', type: 'text', width: 140, readOnly: true },
123
          { data: 'company', type: 'text', width: 180, readOnly: true },
124
        ]}
125
        columnSorting={true}
126
        rowHeaders={true}
127
        height={360}
128
        width="100%"
129
        stretchH="all"
130
        autoWrapRow={true}
131
        licenseKey="non-commercial-and-evaluation"
132
      />
133
    </div>
134
  );
135
};
136

137
export default ExampleComponent;

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 { useCallback, useMemo, useRef } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
registerAllModules();
6

7
const pagination = { pageSize: 5 };
8

9
const ExampleComponent = () => {
10
  const cachedRowsRef = useRef(null);
11
  const statusRef = useRef(null);
12

13
  const loadAllRows = useCallback(async (signal) => {
14
    if (cachedRowsRef.current !== null) {
15
      return cachedRowsRef.current;
16
    }
17

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

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

24
    const users = await response.json();
25

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

35
    return cachedRowsRef.current;
36
  }, []);
37

38
  const fetchRows = useCallback(
39
    async ({ page, pageSize, sort }, { signal }) => {
40
      let rows = await loadAllRows(signal);
41

42
      if (sort) {
43
        rows = [...rows].sort((a, b) => {
44
          const av = a[sort.prop];
45
          const bv = b[sort.prop];
46
          const cmp = av < bv ? -1 : av > bv ? 1 : 0;
47

48
          return sort.order === 'asc' ? cmp : -cmp;
49
        });
50
      }
51

52
      const start = (page - 1) * pageSize;
53

54
      return {
55
        rows: rows.slice(start, start + pageSize),
56
        totalRows: rows.length,
57
      };
58
    },
59
    [loadAllRows]
60
  );
61

62
  const dataProvider = useMemo(
63
    () => ({
64
      rowId: 'id',
65
      fetchRows,
66
      onRowsCreate: async () => {},
67
      onRowsUpdate: async () => {},
68
      onRowsRemove: async () => {},
69
    }),
70
    [fetchRows]
71
  );
72

73
  const beforeDataProviderFetch = useCallback((params) => {
74
    if (params.skipLoading || !statusRef.current) return;
75
    statusRef.current.textContent = 'Loading...';
76
    statusRef.current.style.color = '#202124';
77
  }, []);
78

79
  const afterDataProviderFetch = useCallback(() => {
80
    if (!statusRef.current) return;
81
    statusRef.current.textContent = 'Loaded from REST API via dataProvider.';
82
    statusRef.current.style.color = '#202124';
83
  }, []);
84

85
  const afterDataProviderFetchError = useCallback((error) => {
86
    if (!statusRef.current) return;
87
    statusRef.current.textContent = `Error: ${error.message}`;
88
    statusRef.current.style.color = '#c62828';
89
  }, []);
90

91
  return (
92
    <div>
93
      <p
94
        ref={statusRef}
95
        style={{ margin: '0 0 8px', fontFamily: 'Arial, sans-serif', fontSize: '14px', color: '#202124' }}
96
      >
97
        Loading...
98
      </p>
99
      <HotTable
100
        dataProvider={dataProvider}
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
        pagination={pagination}
111
        columnSorting={true}
112
        emptyDataState={true}
113
        rowHeaders={true}
114
        height={360}
115
        width="100%"
116
        stretchH="all"
117
        autoWrapRow={true}
118
        beforeDataProviderFetch={beforeDataProviderFetch}
119
        afterDataProviderFetch={afterDataProviderFetch}
120
        afterDataProviderFetchError={afterDataProviderFetchError}
121
        licenseKey="non-commercial-and-evaluation"
122
      />
123
    </div>
124
  );
125
};
126

127
export default ExampleComponent;

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

5
registerAllModules();
6

7
const pagination = { pageSize: 5 };
8

9
type ApiUser = {
10
  id: number;
11
  name: string;
12
  username: string;
13
  email: string;
14
  address?: { city?: string };
15
  company?: { name?: string };
16
};
17

18
type UserRow = {
19
  id: number;
20
  name: string;
21
  username: string;
22
  email: string;
23
  city: string;
24
  company: string;
25
};
26

27
type SortDescriptor = { prop: string; order: 'asc' | 'desc' } | null;
28

29
const ExampleComponent = () => {
30
  const cachedRowsRef = useRef<UserRow[] | null>(null);
31
  const statusRef = useRef<HTMLParagraphElement | null>(null);
32

33
  const loadAllRows = useCallback(async (signal: AbortSignal): Promise<UserRow[]> => {
34
    if (cachedRowsRef.current !== null) {
35
      return cachedRowsRef.current;
36
    }
37

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

40
    if (!response.ok) {
41
      throw new Error(`HTTP ${response.status}`);
42
    }
43

44
    const users = (await response.json()) as ApiUser[];
45

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

55
    return cachedRowsRef.current;
56
  }, []);
57

58
  const fetchRows = useCallback(
59
    async (
60
      { page, pageSize, sort }: { page: number; pageSize: number; sort: SortDescriptor },
61
      { signal }: { signal: AbortSignal }
62
    ) => {
63
      let rows = await loadAllRows(signal);
64

65
      if (sort) {
66
        rows = [...rows].sort((a, b) => {
67
          const av = a[sort.prop as keyof UserRow];
68
          const bv = b[sort.prop as keyof UserRow];
69
          const cmp = av < bv ? -1 : av > bv ? 1 : 0;
70

71
          return sort.order === 'asc' ? cmp : -cmp;
72
        });
73
      }
74

75
      const start = (page - 1) * pageSize;
76

77
      return {
78
        rows: rows.slice(start, start + pageSize),
79
        totalRows: rows.length,
80
      };
81
    },
82
    [loadAllRows]
83
  );
84

85
  const dataProvider = useMemo(
86
    () => ({
87
      rowId: 'id',
88
      fetchRows,
89
      onRowsCreate: async () => {},
90
      onRowsUpdate: async () => {},
91
      onRowsRemove: async () => {},
92
    }),
93
    [fetchRows]
94
  );
95

96
  const beforeDataProviderFetch = useCallback((params: { skipLoading?: boolean }) => {
97
    if (params.skipLoading || !statusRef.current) return;
98
    statusRef.current.textContent = 'Loading...';
99
    statusRef.current.style.color = '#202124';
100
  }, []);
101

102
  const afterDataProviderFetch = useCallback(() => {
103
    if (!statusRef.current) return;
104
    statusRef.current.textContent = 'Loaded from REST API via dataProvider.';
105
    statusRef.current.style.color = '#202124';
106
  }, []);
107

108
  const afterDataProviderFetchError = useCallback((error: Error) => {
109
    if (!statusRef.current) return;
110
    statusRef.current.textContent = `Error: ${error.message}`;
111
    statusRef.current.style.color = '#c62828';
112
  }, []);
113

114
  return (
115
    <div>
116
      <p
117
        ref={statusRef}
118
        style={{ margin: '0 0 8px', fontFamily: 'Arial, sans-serif', fontSize: '14px', color: '#202124' }}
119
      >
120
        Loading...
121
      </p>
122
      <HotTable
123
        dataProvider={dataProvider}
124
        colHeaders={['ID', 'Name', 'Username', 'Email', 'City', 'Company']}
125
        columns={[
126
          { data: 'id', type: 'numeric', width: 70, readOnly: true },
127
          { data: 'name', type: 'text', width: 190, readOnly: true },
128
          { data: 'username', type: 'text', width: 150, readOnly: true },
129
          { data: 'email', type: 'text', width: 220, readOnly: true },
130
          { data: 'city', type: 'text', width: 140, readOnly: true },
131
          { data: 'company', type: 'text', width: 180, readOnly: true },
132
        ]}
133
        pagination={pagination}
134
        columnSorting={true}
135
        emptyDataState={true}
136
        rowHeaders={true}
137
        height={360}
138
        width="100%"
139
        stretchH="all"
140
        autoWrapRow={true}
141
        beforeDataProviderFetch={beforeDataProviderFetch}
142
        afterDataProviderFetch={afterDataProviderFetch}
143
        afterDataProviderFetchError={afterDataProviderFetchError}
144
        licenseKey="non-commercial-and-evaluation"
145
      />
146
    </div>
147
  );
148
};
149

150
export default ExampleComponent;

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`