Skip to content

DataProvider

Description

A truthy [[Options#dataProvider]] value enables this plugin. Each key (rowId, fetchRows, onRowsCreate, onRowsUpdate, onRowsRemove) is validated like other plugin options. When the object is a complete server-backed configuration (all of those keys present and valid), Handsontable loads rows via fetchRows, runs mutations through the callbacks, and the [[Hooks#hasExternalDataSource]] hook returns true so plugins such as Filters and Pagination can treat the grid as server-driven. If required callbacks are missing or invalid, fetchRows and the affected mutation paths no-op until the configuration is valid. Valid edits apply to the grid immediately; if onRowsUpdate fails, if validation fails later, or if beforeRowsMutation cancels, those cells revert to their previous values. When the [[Options#notification]] plugin is enabled, failed fetchRows, onRowsCreate, onRowsUpdate, or onRowsRemove requests (including a refetch after a successful mutation) show an error notification toast with the same translated titles and description text as before.

If trimRows, manualRowMove, manualColumnMove, or multiColumnSorting is enabled, the DataProvider plugin does not enable. Handsontable logs a console warning when you still set a complete dataProvider configuration. Use [[Options#columnSorting]] for server-driven sort (single column). Query sort uses prop (column data key).

Members

DataProvider

dataProvider.DataProvider

hot

dataProvider.hot : Core

Handsontable instance.

options

dataProvider.options : object

Format type class options.

Methods

createRows

dataProvider.createRows([options]) ⇒ Promise<void>

Server create via onRowsCreate. Use rowsAmount to insert more than one row in one call.

Param	Type	Description
[options]	`object`	`optional` `position`, `referenceRowId`, `rowsAmount`.

destroy

dataProvider.destroy()

Destroys the plugin.

disablePlugin

dataProvider.disablePlugin()

Disables the plugin, aborts fetch, resets query state. Hook listeners registered with addHook are removed by super.disablePlugin() via clearHooks(). The constructor registers [[Hooks#hasExternalDataSource]] for the period before the first enablePlugin(); enablePlugin() registers it again so it survives each updatePlugin() cycle.

enablePlugin

dataProvider.enablePlugin()

Enables the plugin, syncs query parameters from Pagination, ColumnSorting, and Filters, and registers hooks.

fetchData

dataProvider.fetchData([overrides]) ⇒ Promise<({rows: Array<*>, totalRows: number}|null)>

Fetches rows from fetchRows with current or overridden query parameters.

Emits: [Hooks#event:afterDataProviderFetch](/docs/javascript-data-grid/api/hooks/#afterdataproviderfetch) when data loads., [Hooks#event:afterDataProviderFetchError](/docs/javascript-data-grid/api/hooks/#afterdataproviderfetcherror) when `fetchRows` throws a non-abort error., Hooks#afterDataProviderFetchAbort when the request is superseded, aborted,event: or ends with `AbortError`.

Param	Type	Description
[overrides]	`object`	`optional` Partial query overrides (e.g. `{ page: 2 }`, `{ pageSize: 20, page: 1 }`, `{ sort }`, `{ filters }`). Pass `{ skipLoading: true }` to mark internal refetches (for example sort or CRUD); [[Hooks#beforeDataProviderFetch]] receives it, and it is not passed to `fetchRows`. Numeric `page` is clamped to at least 1. When the response `totalRows` implies fewer pages than the requested `page`, fetches again at the last valid page without applying the out-of-range result (avoids redundant `afterPageChange` loads and aborted duplicate requests after row removal on the last page).

getCellElements

dataProvider.getCellElements() ⇒ Array

Gets rendered DOM elements for all cells in the export range.

Returns a 2D array of HTMLElement | null values with the same structure as DataProvider#getCellsMeta. An entry is null when the cell is outside the rendered viewport (virtualised grid).

getCellsMeta

dataProvider.getCellsMeta() ⇒ Array

Gets cell meta for all cells in the export range.

Returns a 2D array of cell meta objects with the same structure as DataProvider#getData. Each entry corresponds to the cell at the same position in the data array.

getColumnHeaders

dataProvider.getColumnHeaders() ⇒ Array

Gets list of columns headers.

getColumnHeadersClassNames

dataProvider.getColumnHeadersClassNames() ⇒ Array<string>

Gets headerClassName values for all visible column headers in the export range.

Returns values in the same column order as DataProvider#getColumnHeaders. An empty string is returned for columns that have no headerClassName configured.

getColumnSummaries

dataProvider.getColumnSummaries() ⇒ Array

Gets column summary endpoint descriptors from the ColumnSummary plugin, translated into the coordinate space of the exported data array.

Returns an empty array when the plugin is absent or disabled. Each descriptor contains:

destRow / destCol — 0-based indices into getData() identifying the destination cell.
type — lowercase summary type ('sum', 'min', 'max', 'count', 'average', 'custom').
sourceCol — 0-based data-array column index of the source column.
sourceRanges — array of [startDataRow, endDataRow] pairs (inclusive, 0-based) covering the source rows after hidden-row exclusion and range clamping.

getColumnsWidths

dataProvider.getColumnsWidths() ⇒ Array

Gets widths (in pixels) for all visible columns in the export range.

Returns values in the same column order as DataProvider#getData.

getData

dataProvider.getData() ⇒ Array

Get table data based on provided settings to the class constructor.

getExcludedHiddenColumns

dataProvider.getExcludedHiddenColumns() ⇒ Set<number>

Returns the set of physical HOT column indices that are hidden and excluded from the exported data matrix (i.e. exportHiddenColumns is false and the column is hidden).

Returns an empty set when exportHiddenColumns is true or 'hide', because in those cases all columns are included in the data matrix and no formula-offset adjustment is needed.

Used by the formula normalizer to adjust per-reference column offsets when building live Excel formulas from HyperFormula formula strings.

getExcludedHiddenRows

dataProvider.getExcludedHiddenRows() ⇒ Set<number>

Returns the set of physical HOT row indices that are hidden and excluded from the exported data matrix (i.e. exportHiddenRows is false and the row is hidden).

Returns an empty set when exportHiddenRows is true or 'hide', because in those cases all rows are included in the data matrix and no formula-offset adjustment is needed.

Used by the formula normalizer to adjust per-reference row offsets when building live Excel formulas from HyperFormula formula strings.

getFormulasSeparator

dataProvider.getFormulasSeparator() ⇒ string

Gets the function argument separator used by the HyperFormula engine, if active.

Returns ',' when the Formulas plugin is absent or disabled, since that is the separator OOXML (Excel) always expects.

getFrozenColumns

dataProvider.getFrozenColumns() ⇒ number

Gets the number of frozen columns (fixedColumnsStart setting).

getFrozenRows

dataProvider.getFrozenRows() ⇒ number

Gets the number of frozen rows (fixedRowsTop setting).

getHiddenColumnDataIndices

dataProvider.getHiddenColumnDataIndices() ⇒ Array<number>

Returns the 0-based data-array column indices for columns that are hidden in Handsontable and are included in the exported data matrix.

Only returns a non-empty array when exportHiddenColumns is 'hide'. When true, all columns are visible in Excel. When false, hidden columns are omitted entirely and there is nothing to mark as hidden.

getHiddenRowDataIndices

dataProvider.getHiddenRowDataIndices() ⇒ Array<number>

Returns the 0-based data-array row indices for rows that are hidden in Handsontable and are included in the exported data matrix.

Only returns a non-empty array when exportHiddenRows is 'hide'. When true, all rows are visible in Excel. When false, hidden rows are omitted entirely and there is nothing to mark as hidden.

getLayoutDirection

dataProvider.getLayoutDirection() ⇒ ‘ltr’ | ‘rtl’

Gets the layout direction of the Handsontable instance.

getMergeCells

dataProvider.getMergeCells() ⇒ Array

Gets the merged cells configuration filtered to the current export range.

Returned coordinates are 0-based data-array indices (matching the same coordinate space as DataProvider#getData). Hidden rows/columns excluded from the export are accounted for: the row/col offsets are compressed and the rowspan/colspan values are reduced to cover only the exported cells within the merge span.

Merges whose top-left cell is excluded, or that collapse to a single cell after exclusion, are omitted from the result.

getNestedColumnHeaders

dataProvider.getNestedColumnHeaders() ⇒ Array<Array> | null

Gets nested column header data from the NestedHeaders plugin for the current export range.

Returns null when the NestedHeaders plugin is not enabled. Otherwise returns an array of layers, where each layer is an array of { label, colspan, className } objects representing the visible column headers in that layer. Hidden columns (when exportHiddenColumns is false) are excluded and their colspan contribution is removed from spanning headers.

getQueryParameters

dataProvider.getQueryParameters() ⇒ DataProviderQueryParameters

Returns: DataProviderQueryParameters - Copy of current query parameters (sort and filters are cloned when non-null).

getRowHeaders

dataProvider.getRowHeaders() ⇒ Array

Gets list of row headers.

getRowId

dataProvider.getRowId(visualRow) ⇒ *

Param	Type	Description
visualRow	`number`	Visual row index.

Returns: * - Row id from rowId option, or undefined.

getRowsHeights

dataProvider.getRowsHeights() ⇒ Array

Gets heights (in pixels) for all visible rows in the export range.

Returns values in the same row order as DataProvider#getData.

getSourceData

dataProvider.getSourceData() ⇒ Array

Get raw source data (formulas) based on provided settings to the class constructor.

Mirrors DataProvider#getData but uses getSourceDataAtCell so that cells containing HyperFormula formulas return the raw formula string (e.g. '=SUM(A1:A3)') rather than the calculated value.

isEnabled

dataProvider.isEnabled() ⇒ boolean

Check if the plugin is enabled in the handsontable settings.

removeRows

dataProvider.removeRows(rowIds) ⇒ Promise<void>

Server remove via onRowsRemove. Pass one row id or an array of ids.

After a successful onRowsRemove, refetches from the server. When the remove clears every row currently loaded (typical when emptying the last page) and the current page is greater than 1, loads the previous page in one request. Otherwise refetches the current page, then loads the previous page when that response is empty and the current page is still greater than 1.

Throws:

Error When any id is null or undefined.

Param	Type	Description
rowIds	`Array<>` ``	Row id or ids.

setOptions

dataProvider.setOptions(options)

Set options for data provider.

Param	Type	Description
options	`object`	Object with specified options.

updatePlugin

dataProvider.updatePlugin()

Re-applies settings and refetches when the instance is already initialized.

updateRows

dataProvider.updateRows(rows) ⇒ Promise<void>

Server update via onRowsUpdate. Pass an array of { id, changes, rowData? } (same shape as onRowsUpdate).

Throws:

Error When any payload omits id or id is null.

Param	Type	Description
rows	`Array<object>`	Row update payloads (one or more).