Server-side fetching and examples
Added in Handsontable 17.1.0Hooks around fetchRows, loading and error UI, and the DataProvider plugin API. For CRUD callbacks, see Server-side CRUD. For query fields passed into fetchRows, see Server-side configuration.
Fetch hooks and loading UI
beforeDataProviderFetch— returnfalseto cancel a fetch. The argument merges query fields with optionalskipLoading(set on internal refetches after sort or CRUD). That flag is not passed tofetchRows.afterDataProviderFetch— result includesrows,totalRows,queryParameters,columnSortConfig, andfiltersConditionsStack(the latter two mirror ColumnSorting and Filters state for the query that just ran).afterDataProviderFetchError—(error, queryParameters)whenfetchRowsthrows or rejects with a non-abort error.afterDataProviderFetchAbort—(queryParameters, reason)when a fetch is superseded, aborted, or ends withAbortError.
When notification is enabled, the Notification plugin shows an error toast if fetchRows rejects or if onRowsCreate, onRowsUpdate, or onRowsRemove rejects, including when a refetch after a successful mutation fails. The title is translated per operation (load vs create vs update vs remove). The message text prefers a string message, error, or detail from a JSON body, including when that body is nested on the error object (error.response?.data, error.data, or error.body, as with some HTTP clients). Otherwise it falls back to an Error message, a string rejection, or a generic fallback. Fetch errors (including a failed refetch after a mutation) also add a Refetch button on the toast that retries the request that failed, with the same page, page size, sort, and filters. If a later request has succeeded since, Refetch reloads the current data instead. The toast stays until you dismiss it or use Refetch. If Notification is disabled, use afterDataProviderFetchError for failed loads and refetches, and afterRowsMutationError for rejected mutation callbacks; you supply your own error UI.
The Empty data state / loading overlay follows DataProvider for the "loading" branch: beforeDataProviderFetch turns loading on when skipLoading is not set; afterDataProviderFetch and afterDataProviderFetchError turn it off. afterDataProviderFetchAbort does not clear loading by itself (for example when the user changes page while a request is in flight), so the overlay stays until a fetch finishes successfully or with an error. Refetches after column sort or CRUD pass skipLoading: true into beforeDataProviderFetch, so the Empty data state plugin skips the full loading overlay for those internal loads.
DataProvider plugin methods
From hot.getPlugin('dataProvider'):
fetchData— fetches the visible sheet, with optional overrides (page,pageSize,sort,filters, and client-onlyskipLoading). Overrides are merged into the current query;pageis clamped to at least 1, and Handsontable DataGrid may issue a follow-up fetch iftotalRowsfrom the server implies a lower last page than requested. After init, passing anotherdataProviderobject throughupdateSettingsruns the plugin’s update path and triggers a refetch when the grid is already rendered.isFetching— whether the visible sheet is waiting for afetchRowsresponse that shows the loading overlay. A fetch that passesskipLoading(like the refetch after a sort or a row change) does not count, and inside theafterDataProviderFetch,afterDataProviderFetchError, andafterDataProviderFetchAbortlisteners of the fetch that settled, it’s alreadyfalse.updateSettingsand loaded rows — WhenhasExternalDataSourceistrue, Handsontable only resets the in-memory placeholder to an empty array during init or when theupdateSettingspayload replacesdataProviderwith another value, and the DataProvider plugin then refetches. Adatavalue is ignored with a console warning and keeps the current rows. Passing the samedataProviderobject again keeps the rows and does not refetch either, unless the same call also passespagination,columnSorting,filters, orcolumns: those reset the page, sort, or filters, so the rows are fetched again. The React and Angular wrappers pass only the settings that changed; in React, keep thedataProviderobject stable withuseMemo. A change made inside the same object is used by the next request; to load the rows right away, callfetchData. Other keys alone (for exampleheightorcolHeaders) keep the current page of rows and send no request.pagination,columnSorting,filters, orcolumnssent withoutdataProviderreset the page, sort, or filters the same way, and the rows are fetched again; a newcolumnsvalue also clears the sort. ThePaginationandFiltersplugins follow adataProvideradded or removed this way too: both read live whether a data provider backs the grid, so they switch between server-side and client-side behavior the moment the setting changes. Destroying the grid while a fetch is in flight aborts that fetch without logging a console error.getQueryParameters— currentpage,pageSize,sort,filters.getRowId— resolve the id for a visual row.createRows,updateRows,removeRows— programmatic CRUD through the same server callbacks (see Server-side CRUD).
Use DataProvider with the sheets bar
With the sheets bar, set dataProvider in the settings of each sheet that loads from a server. For how server sheets fetch and behave when you switch, see Server-backed sheets.
Examples (REST and GraphQL)
These end-to-end patterns pair a browser grid with a small backend:
- REST (warehouse stock) — SKU / bin / quantity columns with an Express-style JSON API (
GET/PATCH/POST/DELETEon/api/stock-lines). Reference server:server-rest.mjs(the same file ships in everydata-providerexample folder). - GraphQL (support queue) — Paged open tickets, sort mapping, and mutations aligned to a helpdesk-style schema. Reference server:
server-graphql.mjs(same layout in each example folder).
The JavaScript, React, Vue 3, and Angular examples under examples/next/docs/ each run both backends on one page (default ports 4010 and 4011). See CodeSandbox examples below.
In TypeScript projects, you can import DataProviderQueryParameters, DataProviderFetchOptions, and related interfaces from handsontable/plugins/dataProvider (same pattern as the framework examples that share dataProviderClients with the REST and GraphQL clients).
When you enable filters, add the parameters your backend needs and serialize queryParameters.filters the way your storage layer expects. Handle errors with afterDataProviderFetchError and afterRowsMutationError.
CodeSandbox examples
Runnable projects under the Handsontable examples monorepo (Devbox):
End-to-end backends (Node servers + UI)
Each folder includes the same Express servers (server-rest.mjs, server-graphql.mjs, start-servers.mjs). Run npm run server, then npm run start for the framework dev server.
- JavaScript (Vite) — override URLs with
VITE_API_BASEandVITE_GRAPHQL_URL. - React (Vite) — override with
VITE_API_BASEandVITE_GRAPHQL_URL. - Vue 3 (Vite) — override with
VITE_API_BASEandVITE_GRAPHQL_URL. - Angular — set
restApiBaseandgraphqlUrlinsrc/environments/environment.ts.
More in this guide
Related guides
Related API reference
Options
Plugins
Hooks