Skip to content

Server-side fetching and examples

Added in Handsontable 17.1.0

Hooks 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 — return false to cancel a fetch. The argument merges query fields with optional skipLoading (set on internal refetches after sort or CRUD). That flag is not passed to fetchRows.
  • afterDataProviderFetch — result includes rows, totalRows, queryParameters, columnSortConfig, and filtersConditionsStack (the latter two mirror ColumnSorting and Filters state for the query that just ran).
  • afterDataProviderFetchError — (error, queryParameters) when fetchRows throws or rejects with a non-abort error.
  • afterDataProviderFetchAbort — (queryParameters, reason) when a fetch is superseded, aborted, or ends with AbortError.

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-only skipLoading). Overrides are merged into the current query; page is clamped to at least 1, and Handsontable DataGrid may issue a follow-up fetch if totalRows from the server implies a lower last page than requested. After init, passing another dataProvider object through updateSettings runs the plugin’s update path and triggers a refetch when the grid is already rendered.
  • isFetching — whether the visible sheet is waiting for a fetchRows response that shows the loading overlay. A fetch that passes skipLoading (like the refetch after a sort or a row change) does not count, and inside the afterDataProviderFetch, afterDataProviderFetchError, and afterDataProviderFetchAbort listeners of the fetch that settled, it’s already false.
  • updateSettings and loaded rows — When hasExternalDataSource is true, Handsontable only resets the in-memory placeholder to an empty array during init or when the updateSettings payload replaces dataProvider with another value, and the DataProvider plugin then refetches. A data value is ignored with a console warning and keeps the current rows. Passing the same dataProvider object again keeps the rows and does not refetch either, unless the same call also passes pagination, columnSorting, filters, or columns: 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 the dataProvider object stable with useMemo. A change made inside the same object is used by the next request; to load the rows right away, call fetchData. Other keys alone (for example height or colHeaders) keep the current page of rows and send no request. pagination, columnSorting, filters, or columns sent without dataProvider reset the page, sort, or filters the same way, and the rows are fetched again; a new columns value also clears the sort. The Pagination and Filters plugins follow a dataProvider added 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 — current page, 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 / DELETE on /api/stock-lines). Reference server: server-rest.mjs (the same file ships in every data-provider example 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_BASE and VITE_GRAPHQL_URL.
  • React (Vite) — override with VITE_API_BASE and VITE_GRAPHQL_URL.
  • Vue 3 (Vite) — override with VITE_API_BASE and VITE_GRAPHQL_URL.
  • Angular — set restApiBase and graphqlUrl in src/environments/environment.ts.

More in this guide

Options

Plugins

Hooks