Load data from a GraphQL API

This tutorial shows two GraphQL approaches for Handsontable. The first approach loads data on the client with fetch, loadData(), and updateData(). The second approach uses the server-side DataProvider architecture for paging, sorting, filtering, and CRUD callbacks.

1
/* file: app.component.ts */
2
import { Component, OnInit } from '@angular/core';
3
import { GridSettings, HotTableModule } from '@handsontable/angular-wrapper';
4

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

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

23
const USERS_QUERY = `
24
  query {
25
    users {
26
      data {
27
        id
28
        name
29
        username
30
        email
31
        address {
32
          city
33
        }
34
        company {
35
          name
36
        }
37
      }
38
    }
39
  }
40
`;
41

42
@Component({
43
  standalone: true,
44
  imports: [HotTableModule],
45
  selector: 'example1-load-data-graphql',
46
  template: `
47
    <div>
48
      <div style="display: flex; gap: 12px; align-items: center; margin-bottom: 8px;">
49
        <p
50
          style="margin: 0; font-family: Arial, sans-serif; font-size: 14px;"
51
          [style.color]="hasError ? '#c62828' : '#202124'"
52
        >
53
          {{ status }}
54
        </p>
55
        @if (hasError) {
56
          <button type="button" (click)="loadUsers()">Retry</button>
57
        }
58
      </div>
59
      <hot-table [data]="rows" [settings]="gridSettings"></hot-table>
60
    </div>
61
  `,
62
})
63
export class AppComponent implements OnInit {
64
  status = 'Loading users...';
65
  hasError = false;
66
  rows: UserRow[] = [];
67

68
  readonly gridSettings: GridSettings = {
69
    colHeaders: ['ID', 'Name', 'Username', 'Email', 'City', 'Company'],
70
    columns: [
71
      { data: 'id', type: 'numeric', width: 70 },
72
      { data: 'name', type: 'text', width: 190 },
73
      { data: 'username', type: 'text', width: 150 },
74
      { data: 'email', type: 'text', width: 220 },
75
      { data: 'city', type: 'text', width: 140 },
76
      { data: 'company', type: 'text', width: 180 },
77
    ],
78
    rowHeaders: true,
79
    height: 360,
80
    width: '100%',
81
    stretchH: 'all',
82
    autoWrapRow: true,
83
  };
84

85
  ngOnInit(): void {
86
    this.loadUsers();
87
  }
88

89
  async loadUsers(): Promise<void> {
90
    this.status = 'Loading users...';
91
    this.hasError = false;
92

93
    try {
94
      const users = await this.fetchUsers();
95

96
      this.rows = this.mapUsersToGridRows(users);
97
      this.status = 'Loaded users from GraphQL API.';
98
    } catch (_error) {
99
      this.rows = [];
100
      this.hasError = true;
101
      this.status = 'Failed to load users. Try again.';
102
    }
103
  }
104

105
  private async fetchUsers(): Promise<ApiUser[]> {
106
    const response = await fetch('https://graphqlzero.almansi.me/api', {
107
      method: 'POST',
108
      headers: { 'Content-Type': 'application/json' },
109
      body: JSON.stringify({ query: USERS_QUERY }),
110
    });
111

112
    if (!response.ok) {
113
      throw new Error(`Request failed with status: ${response.status}`);
114
    }
115

116
    const payload = (await response.json()) as {
117
      data?: { users?: { data?: ApiUser[] } };
118
      errors?: Array<{ message?: string }>;
119
    };
120

121
    // GraphQL APIs can return HTTP 200 and still include execution errors.
122
    if (payload.errors?.length) {
123
      throw new Error(payload.errors[0]?.message ?? 'GraphQL request failed.');
124
    }
125

126
    return payload.data?.users?.data ?? [];
127
  }
128

129
  private mapUsersToGridRows(users: ApiUser[]): UserRow[] {
130
    return users.map((user) => ({
131
      id: user.id,
132
      name: user.name,
133
      username: user.username,
134
      email: user.email,
135
      city: user.address?.city ?? '',
136
      company: user.company?.name ?? '',
137
    }));
138
  }
139
}
140
/* end-file */
141

142
/* file: app.config.ts */
143
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
144
import { registerAllModules } from 'handsontable/registry';
145
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
146

147
registerAllModules();
148

149
export const appConfig: ApplicationConfig = {
150
  providers: [
151
    provideZoneChangeDetection({ eventCoalescing: true }),
152
    {
153
      provide: HOT_GLOBAL_CONFIG,
154
      useValue: { license: NON_COMMERCIAL_LICENSE } as HotGlobalConfig,
155
    },
156
  ],
157
};
158
/* end-file */

1
<div><example1-load-data-graphql></example1-load-data-graphql></div>

Approach 1 - Client-side fetch with `loadData()` and `updateData()`

Sending a GraphQL POST request to https://graphqlzero.almansi.me/api from the browser.
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.
Send a GraphQL query 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
/* file: app.component.ts */
2
import { Component, ViewChild, AfterViewInit } from '@angular/core';
3
import { GridSettings, HotTableComponent, HotTableModule } from '@handsontable/angular-wrapper';
4

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

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

23
const USERS_QUERY = `
24
  query {
25
    users {
26
      data {
27
        id
28
        name
29
        username
30
        email
31
        address {
32
          city
33
        }
34
        company {
35
          name
36
        }
37
      }
38
    }
39
  }
40
`;
41

42
@Component({
43
  standalone: true,
44
  imports: [HotTableModule],
45
  selector: 'example2-load-data-graphql',
46
  template: `
47
    <div>
48
      <div style="display: flex; gap: 12px; align-items: center; margin-bottom: 8px;">
49
        <p
50
          style="margin: 0; font-family: Arial, sans-serif; font-size: 14px;"
51
          [style.color]="hasError ? '#c62828' : '#202124'"
52
        >
53
          {{ status }}
54
        </p>
55
        @if (showRefresh && !hasError) {
56
          <button type="button" (click)="refreshUsers()" style="margin-bottom: 0">Refresh</button>
57
        }
58
        @if (hasError) {
59
          <button type="button" (click)="initialLoad()" style="margin-bottom: 0">Retry</button>
60
        }
61
      </div>
62
      <hot-table [settings]="gridSettings"></hot-table>
63
    </div>
64
  `,
65
})
66
export class AppComponent implements AfterViewInit {
67
  @ViewChild(HotTableComponent, { static: false }) readonly hotTable!: HotTableComponent;
68

69
  status = 'Loading users...';
70
  hasError = false;
71
  showRefresh = false;
72

73
  readonly gridSettings: GridSettings = {
74
    colHeaders: ['ID', 'Name', 'Username', 'Email', 'City', 'Company'],
75
    columns: [
76
      { data: 'id', type: 'numeric', width: 70 },
77
      { data: 'name', type: 'text', width: 190 },
78
      { data: 'username', type: 'text', width: 150 },
79
      { data: 'email', type: 'text', width: 220 },
80
      { data: 'city', type: 'text', width: 140 },
81
      { data: 'company', type: 'text', width: 180 },
82
    ],
83
    // Enables clickable sort indicators on column headers.
84
    columnSorting: true,
85
    rowHeaders: true,
86
    height: 360,
87
    width: '100%',
88
    stretchH: 'all',
89
    autoWrapRow: true,
90
  };
91

92
  ngAfterViewInit(): void {
93
    this.initialLoad();
94
  }
95

96
  // Step 5: Initial load uses loadData() directly on the hot instance, which resets all grid states.
97
  // This is correct for a first load -- there is no existing state to preserve.
98
  async initialLoad(): Promise<void> {
99
    this.status = 'Loading users...';
100
    this.hasError = false;
101
    this.showRefresh = false;
102

103
    try {
104
      const users = await this.fetchUsers();
105

106
      this.hotTable.hotInstance?.loadData(this.mapUsersToGridRows(users));
107
      this.status =
108
        'Users loaded. Sort a column, then click "Refresh" to see that the column sort order is preserved.';
109
      this.showRefresh = true;
110
    } catch (_error) {
111
      this.hotTable.hotInstance?.loadData([]);
112
      this.hasError = true;
113
      this.status = 'Failed to load users. Try again.';
114
    }
115
  }
116

117
  // Step 6: Subsequent refreshes use updateData(), which replaces the data
118
  // without resetting column sort order, selection, or column order.
119
  async refreshUsers(): Promise<void> {
120
    this.status = 'Refreshing...';
121
    this.hasError = false;
122
    this.showRefresh = false;
123

124
    try {
125
      const users = await this.fetchUsers();
126

127
      this.hotTable.hotInstance?.updateData(this.mapUsersToGridRows(users));
128
      this.status = 'Data refreshed -- column sort order was preserved.';
129
      this.showRefresh = true;
130
    } catch (_error) {
131
      // On error, do not clear the grid -- the existing data is still valid.
132
      this.hasError = true;
133
      this.status = 'Failed to load users. Try again.';
134
    }
135
  }
136

137
  private async fetchUsers(): Promise<ApiUser[]> {
138
    const response = await fetch('https://graphqlzero.almansi.me/api', {
139
      method: 'POST',
140
      headers: { 'Content-Type': 'application/json' },
141
      body: JSON.stringify({ query: USERS_QUERY }),
142
    });
143

144
    if (!response.ok) {
145
      throw new Error(`Request failed with status: ${response.status}`);
146
    }
147

148
    const payload = (await response.json()) as {
149
      data?: { users?: { data?: ApiUser[] } };
150
      errors?: Array<{ message?: string }>;
151
    };
152

153
    // GraphQL APIs can return HTTP 200 and still include execution errors.
154
    if (payload.errors?.length) {
155
      throw new Error(payload.errors[0]?.message ?? 'GraphQL request failed.');
156
    }
157

158
    return payload.data?.users?.data ?? [];
159
  }
160

161
  private mapUsersToGridRows(users: ApiUser[]): UserRow[] {
162
    return users.map((user) => ({
163
      id: user.id,
164
      name: user.name,
165
      username: user.username,
166
      email: user.email,
167
      city: user.address?.city ?? '',
168
      company: user.company?.name ?? '',
169
    }));
170
  }
171
}
172
/* end-file */
173

174
/* file: app.config.ts */
175
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
176
import { registerAllModules } from 'handsontable/registry';
177
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
178

179
registerAllModules();
180

181
export const appConfig: ApplicationConfig = {
182
  providers: [
183
    provideZoneChangeDetection({ eventCoalescing: true }),
184
    {
185
      provide: HOT_GLOBAL_CONFIG,
186
      useValue: { license: NON_COMMERCIAL_LICENSE } as HotGlobalConfig,
187
    },
188
  ],
189
};
190
/* end-file */

1
<div><example2-load-data-graphql></example2-load-data-graphql></div>

What the second example covers

Enabling columnSorting so the user can sort by any column header.
Using hot.loadData() for the first query - 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

Approach 2 - Server-side GraphQL with `dataProvider`

Use this approach when your dataset is large, or when you need server-driven pagination, sorting, filtering, and CRUD. Instead of downloading all rows in one browser request, Handsontable requests only the current page through dataProvider.fetchRows.

1
const hot = new Handsontable(container, {
2
  dataProvider: {
3
    rowId: 'id',
4
    fetchRows: async (queryParameters, { signal }) => {
5
      const response = await fetch('/graphql', {
6
        method: 'POST',
7
        signal,
8
        headers: { 'Content-Type': 'application/json' },
9
        body: JSON.stringify({
10
          query: buildUsersQuery(queryParameters),
11
        }),
12
      });
13

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

18
      const payload = await response.json();
19

20
      if (payload.errors?.length) {
21
        throw new Error(payload.errors[0]?.message ?? 'GraphQL request failed.');
22
      }
23

24
      return {
25
        rows: payload.data.users.data,
26
        totalRows: payload.data.users.meta.totalCount,
27
      };
28
    },
29
    onRowsCreate: async (rowsCreatePayload) => {
30
      await createRowsMutation(rowsCreatePayload);
31
    },
32
    onRowsUpdate: async (rows) => {
33
      await updateRowsMutation(rows);
34
    },
35
    onRowsRemove: async (rowIds) => {
36
      await removeRowsMutation(rowIds);
37
    },
38
  },
39
  pagination: { pageSize: 10 },
40
  columnSorting: true,
41
  filters: true,
42
  emptyDataState: true,
43
  notification: true,
44
  licenseKey: 'non-commercial-and-evaluation',
45
});

The example above maps directly to the latest server-side data guides and APIs:

Overview and plugin behavior: Server-side data
Required settings and query fields: Server-side configuration
Fetch lifecycle, hooks, and REST/GraphQL examples: Server-side fetching and examples
Mutation callbacks and rollback behavior: Server-side CRUD
Upgrade checklist from client-only loading: Migrate to server-side data

Client-side recipe vs server-side DataProvider

Approach	Where data lives	Sorting/filtering	Pagination	CRUD	Use when
Client-side `fetch` + `loadData()` / `updateData()`	Browser memory	Client-side	Manual, if you build it	Manual	Small/medium datasets, quick integration
`dataProvider` + GraphQL backend	Backend + paged slices in browser	Server-side via query parameters	Built in with `pagination`	Built in via callbacks	Large datasets, production server-driven flows

GraphQL request specifics

GraphQL requires one extra check compared to REST:

Send requests with method: 'POST'.
Use Content-Type: application/json.
Put your operation in body: JSON.stringify({ query: '...' }).
Check errors in the JSON response body, even when HTTP status is 200.

For basic scenarios, fetch is sufficient. In larger applications, a dedicated GraphQL client such as graphql-request or Apollo Client can simplify caching, retries, and schema-aware tooling.

Define the GraphQL query

Keep the user fields aligned with your Handsontable columns:
```
1
const USERS_QUERY = `
2
  query {
3
    users {
4
      data {
5
        id
6
        name
7
        username
8
        email
9
        address { city }
10
        company { name }
11
      }
12
    }
13
  }
14
`;
```
What’s happening:
- The query requests the same user dataset shape used by the REST recipe.
- Nested GraphQL fields (address.city, company.name) are flattened later by mapUsersToGridRows().

Send a GraphQL POST request

Use fetch with a JSON payload that contains the query string.

1
const response = await fetch('https://graphqlzero.almansi.me/api', {
2
  method: 'POST',
3
  headers: { 'Content-Type': 'application/json' },
4
  body: JSON.stringify({ query: USERS_QUERY }),
5
});

What’s happening:

GraphQL APIs typically use POST for operations.
The payload format is always JSON with a query field.

Validate both HTTP status and GraphQL errors

GraphQL APIs can return HTTP 200 while still reporting operation errors.
```
1
const payload = await response.json();
2

3
if (payload.errors?.length) {
4
  throw new Error(payload.errors[0]?.message ?? 'GraphQL request failed.');
5
}
```
What’s happening:
- HTTP status validation catches transport-level failures.
- payload.errors catches GraphQL execution and validation failures.
- The same catch block handles both cases and updates the recipe UI consistently.
Use loadData() for initial query and updateData() for refreshes

loadData() is used once for initial population, and updateData() is used for subsequent refreshes to preserve state.
```
1
hot.loadData(mapUsersToGridRows(users)); // initial query
2
hot.updateData(mapUsersToGridRows(users)); // refresh query
```
What’s happening:
- loadData() resets state - ideal for first render.
- updateData() preserves state - ideal after users have interacted with the grid.

Saving data

Server-side data

What you learned

How to send a GraphQL POST request with fetch using Content-Type: application/json and a query field in the body.
Why you must check payload.errors in addition to HTTP status, because GraphQL APIs return HTTP 200 even for operation errors.
How hot.loadData() resets all grid state on first load and hot.updateData() preserves column sort order and selection on subsequent refreshes.
How to use the dataProvider architecture for server-side pagination, sorting, filtering, and CRUD when your dataset is too large for client-side loading.

Next steps

Explore Load data from a REST API for the same client-side and server-side approaches with a REST backend.
Read the Server-side data guides for the full dataProvider configuration reference.

Load data from a GraphQL API

Approach 1 - Client-side fetch with loadData() and updateData()

How it works

Using updateData() to preserve sorting and other states

What the second example covers

loadData() vs updateData()

Approach 2 - Server-side GraphQL with dataProvider

Client-side recipe vs server-side DataProvider

GraphQL request specifics

Define the GraphQL query

Send a GraphQL POST request

Validate both HTTP status and GraphQL errors

Use loadData() for initial query and updateData() for refreshes

Related