Hooks
See the Events and hooks guide for examples and configuration details.
Members
afterAddChild
afterAddChild(parent, element, index)
Fired by NestedRows plugin after adding a children to the NestedRows structure. This hook is fired when
Options#nestedRows option is enabled.
| Param | Type | Description |
|---|---|---|
| parent | object | The parent object. |
| element | object undefined | The element added as a child. If undefined, a blank child was added. |
| index | number undefined | The index within the parent where the new child was added. If undefined, the element was added as the last child. |
afterAsyncValueCancel
afterAsyncValueCancel(physicalRow, prop, reason, rowId)
Fired by the AsyncValues plugin after it cancels a cell’s pending request. A late result of the request is ignored.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| physicalRow | number | Physical row index of the cell, at the time of the cancellation. For a removal of several non-contiguous groups of rows, it is the index just before that row’s own group is removed. |
| prop | string number | The property of the cell’s column. |
| reason | string | Why the request was canceled: 'edit', 'dependency', 'restart', 'rowRemoved', 'columnsChanged', 'dataReplaced', 'manual', 'disabled', or 'vetoed'. |
| rowId | * | The id of the cell’s row (see the rowId option), or null. For a row that was removed or replaced, it is the id the row held before. |
afterAsyncValueReject
afterAsyncValueReject(physicalRow, prop, error, message, rowId)
Fired by the AsyncValues plugin after a cell’s request rejects. The cell keeps its previous value and is in the error state.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| physicalRow | number | Physical row index of the cell. |
| prop | string number | The property of the cell’s column. |
| error | * | The rejection reason. |
| message | string | The error message shown on the cell. |
| rowId | * | The id of the cell’s row (see the rowId option), or null. |
afterAsyncValueResolve
afterAsyncValueResolve(physicalRow, prop, value, rowId)
Fired by the AsyncValues plugin after it passes a resolved value to the grid. A beforeChange
listener or the cell’s validator can still change or reject the value, and an asynchronous validator
delays the write.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| physicalRow | number | Physical row index of the cell. |
| prop | string number | The property of the cell’s column. |
| value | * | The resolved value. |
| rowId | * | The id of the cell’s row (see the rowId option), or null. |
afterAsyncValuesIdle
afterAsyncValuesIdle
Fired by the AsyncValues plugin when the last pending request settles (resolves, rejects, or is canceled), so no cell is pending any more.
Since: 19.0.0
afterAsyncValueStart
afterAsyncValueStart(physicalRow, prop, rowId)
Fired by the AsyncValues plugin after it starts an asynchronous computation of a cell’s value. The cell is in the pending state.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| physicalRow | number | Physical row index of the cell. |
| prop | string number | The property of the cell’s column. |
| rowId | * | The id of the cell’s row (see the rowId option), or null. |
afterAutofill
afterAutofill(fillData, sourceRange, targetRange, direction)
Fired by Autofill plugin after populating the data in the autofill feature. This hook is fired when Options#fillHandle option is enabled.
Since: 8.0.0
| Param | Type | Description |
|---|---|---|
| fillData | Array<Array> | The data that was used to fill the targetRange. If beforeAutofill was used and returned [[]], this will be the same object that was returned from beforeAutofill. |
| sourceRange | CellRange | The range values will be filled from. |
| targetRange | CellRange | The range new values will be filled into. |
| direction | string | Declares the direction of the autofill. Possible values: up, down, left, right. |
afterBeginEditing
afterBeginEditing(row, column)
Fired after the editor is opened and rendered.
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index of the edited cell. |
| column | number | Visual column index of the edited cell. |
afterCellMetaReset
afterCellMetaReset
Fired after resetting a cell’s meta. This happens when the Core#updateSettings method is called.
afterChange
afterChange(changes, [source])
Fired after one or more cells has been changed. The changes are triggered in any situation when the
value is entered using an editor or changed using API (e.q setDataAtCell method).
For performance reasons, the changes array is null when the source is "loadData" or "updateData".
Calling updateSettings() with the data option inside this hook
triggers another afterChange call with the "updateData" source. Check the source argument
to prevent an infinite loop.
A change to a cell with a validator is written when the validator answers,
which is always at least one microtask after the change was made. The change is written to the record it was
made on, even when a sort, a row move, a filter, or a row insert or removal moved that record in the meantime,
and row is the visual row the record has when the value lands. When a filter or another trimming feature
took the record out of the visual space in the meantime, row is null; to find that record, pass the change
to getPhysicalRowOfChange() inside this hook. When the record was
removed in the meantime, the change is not written, and this hook does not report it.
Breaking change (19.0): row can be null, and the type of changes is AppliedCellChange[] | null
instead of CellChange[] | null. See the migration guide.
Example
<HotTable afterChange={(changes, source) => { changes?.forEach(([row, prop, oldValue, newValue]) => { // Some logic... }); }}/>| Param | Type | Description |
|---|---|---|
| changes | Array<Array> null | 2D array containing information about each of the edited cells [[row, prop, oldVal, newVal], ...], or null for the "loadData" and "updateData" sources. row is a visual row index, or null for a record trimmed out of the visual space. prop is a property name, a column index, or – when columns[].data is a function – the column accessor function. To resolve a visual column index from prop, call propToCol(). Unlike beforeValidate and afterValidate, this hook passes the accessor function as prop so the grid can write data back. Read more: Binding to data: Identify changed columns in hooks. |
| [source] | string | optional String that identifies source of hook call (list of all available sources). |
afterColumnCollapse
afterColumnCollapse(currentCollapsedColumns, destinationCollapsedColumns, collapsePossible, successfullyCollapsed)
Fired by CollapsibleColumns plugin before columns collapse. This hook is fired when Options#collapsibleColumns option is enabled.
Since: 8.0.0
| Param | Type | Description |
|---|---|---|
| currentCollapsedColumns | Array | Current collapsible configuration - a list of collapsible physical column indexes. |
| destinationCollapsedColumns | Array | Destination collapsible configuration - a list of collapsible physical column indexes. |
| collapsePossible | boolean | true, if all of the column indexes are withing the bounds of the collapsed sections, false otherwise. |
| successfullyCollapsed | boolean | true, if the action affected any non-collapsible column, false otherwise. |
afterColumnExpand
afterColumnExpand(currentCollapsedColumns, destinationCollapsedColumns, expandPossible, successfullyExpanded)
Fired by CollapsibleColumns plugin before columns expand. This hook is fired when Options#collapsibleColumns option is enabled.
Since: 8.0.0
| Param | Type | Description |
|---|---|---|
| currentCollapsedColumns | Array | Current collapsible configuration - a list of collapsible physical column indexes. |
| destinationCollapsedColumns | Array | Destination collapsible configuration - a list of collapsible physical column indexes. |
| expandPossible | boolean | true, if all of the column indexes are withing the bounds of the collapsed sections, false otherwise. |
| successfullyExpanded | boolean | true, if the action affected any non-collapsible column, false otherwise. |
afterColumnFreeze
afterColumnFreeze(column, freezePerformed)
Fired by the ManualColumnFreeze plugin, right after freezing a column.
Since: 12.1.0
| Param | Type | Description |
|---|---|---|
| column | number | The visual index of the frozen column. |
| freezePerformed | boolean | If true: the column got successfully frozen. If false: the column didn’t get frozen. |
afterColumnMove
afterColumnMove(movedColumns, finalIndex, dropIndex, movePossible, orderChanged)
Fired by ManualColumnMove plugin after changing order of the visual indexes. This hook is fired when Options#manualColumnMove option is enabled.
The hook also fires when the move leaves the order unchanged, for example when you drop a column back where it
was. In that case, orderChanged is false.
| Param | Type | Description |
|---|---|---|
| movedColumns | Array | Array of visual column indexes to be moved. |
| finalIndex | number | Visual column index, being a start index for the moved columns. Points to where the elements will be placed after the moving action. To check visualization of final index please take a look at documentation. |
| dropIndex | number undefined | Visual column index, being a drop index for the moved columns. Points to where we are going to drop the moved elements. To check visualization of drop index please take a look at documentation. It’s undefined when dragColumns function wasn’t called. |
| movePossible | boolean | Indicates if it was possible to move columns to the desired position. |
| orderChanged | boolean | Indicates if order of columns was changed by move. |
afterColumnResize
afterColumnResize(newSize, column, isDoubleClick)
Fired by ManualColumnResize plugin after rendering the table with modified column sizes. This hook is fired when Options#manualColumnResize option is enabled.
| Param | Type | Description |
|---|---|---|
| newSize | number | Calculated new column width. It excludes the room that the hidden-column indicator adds to a column next to a hidden column, as the width taken by setManualSize() does. |
| column | number | Visual index of the resized column. |
| isDoubleClick | boolean | Flag that determines whether there was a double-click. |
afterColumnSequenceCacheUpdate
afterColumnSequenceCacheUpdate(indexesChangesState)
Fired after the cache of the column sequence has been updated.
Since: 16.2.0
| Param | Type | Description |
|---|---|---|
| indexesChangesState | object | Object containing information about the changes to the column sequence. |
| indexesChangesState.indexesSequenceChanged | boolean | Indicates if the sequence of indexes has changed. |
| indexesChangesState.trimmedIndexesChanged | boolean | Indicates if the trimmed indexes have changed. |
| indexesChangesState.hiddenIndexesChanged | boolean | Indicates if the hidden indexes have changed. |
| [indexesChangesState.indexesChangeSource] | 'init' 'remove' 'insert' 'move' 'update' | optional Indicates what caused a sequence change. |
afterColumnSequenceChange
afterColumnSequenceChange([source])
Fired after the order of columns has changed. This hook is fired by changing column indexes of any type supported by the IndexMapper.
| Param | Type | Description |
|---|---|---|
| [source] | 'init' 'remove' 'insert' 'move' 'update' | optional A string that indicates what caused the change to the order of columns. |
afterColumnSort
afterColumnSort(currentSortConfig, destinationSortConfigs, sortPossible)
Fired by ColumnSorting and MultiColumnSorting plugins after sorting the column. This hook is fired when Options#columnSorting or Options#multiColumnSorting option is enabled.
The hook receives the same arguments as Hooks#beforeColumnSort, in the same format.
| Param | Type | Description |
|---|---|---|
| currentSortConfig | Array | Sort configuration from before the sort (for all sorted columns), not the one the grid is sorted by now. |
| destinationSortConfigs | Array | Sort configuration that the sort applied (for all sorted columns). It repeats currentSortConfig when sortPossible is false. |
| sortPossible | boolean | Indicates if it was possible to sort the table with the provided configuration. |
afterColumnUnfreeze
afterColumnUnfreeze(column, unfreezePerformed, finalIndex)
Fired by the ManualColumnFreeze plugin, right after unfreezing a column.
Since: 12.1.0
| Param | Type | Description |
|---|---|---|
| column | number | The visual index of the unfrozen column. |
| unfreezePerformed | boolean | If true: the column got successfully unfrozen. If false: the column didn’t get unfrozen. |
| finalIndex | number | The visual index the column was moved to (available since 19.0.0). Equal to column when unfreezePerformed is false. |
afterContextMenuDefaultOptions
afterContextMenuDefaultOptions(predefinedItems)
Fired each time user opens ContextMenu and after setting up the context menu’s default options. These options are a collection which user can select by setting an array of keys or an array of objects in Options#contextMenu option.
| Param | Type | Description |
|---|---|---|
| predefinedItems | Array | An array of objects containing information about the pre-defined context menu items. |
afterContextMenuHide
afterContextMenuHide(context)
Fired by ContextMenu plugin after hiding the context menu. This hook is fired when Options#contextMenu option is enabled.
| Param | Type | Description |
|---|---|---|
| context | object | The ContextMenu plugin instance. |
afterContextMenuShow
afterContextMenuShow(context)
Fired by ContextMenu plugin after opening the context menu. This hook is fired when Options#contextMenu option is enabled.
| Param | Type | Description |
|---|---|---|
| context | object | The ContextMenu plugin instance. |
afterCopy
afterCopy(data, coords, copiedHeadersCount)
Fired by CopyPaste plugin after data are pasted into table. This hook is fired when Options#copyPaste option is enabled.
| Param | Type | Description |
|---|---|---|
| data | Array<Array> | An array of arrays which contains the copied data. |
| coords | Array<object> | An array of objects with ranges of the visual indexes (startRow, startCol, endRow, endCol) which was copied. |
| copiedHeadersCount | Object | (Since 12.3.0) The number of copied column headers. |
afterCopyLimit
afterCopyLimit(selectedRows, selectedColumns, copyRowsLimit, copyColumnsLimit)
Fired by CopyPaste plugin after reaching the copy limit while copying data. This hook is fired when Options#copyPaste option is enabled.
| Param | Type | Description |
|---|---|---|
| selectedRows | number | Count of selected copyable rows. |
| selectedColumns | number | Count of selected copyable columns. |
| copyRowsLimit | number | Current copy rows limit. |
| copyColumnsLimit | number | Current copy columns limit. |
afterCreateCol
afterCreateCol(index, amount, [source])
Fired after created a new column.
| Param | Type | Description |
|---|---|---|
| index | number | Represents the visual index of first newly created column in the data source. |
| amount | number | Number of newly created columns in the data source. |
| [source] | string | optional String that identifies source of hook call (list of all available sources). For example, 'ContextMenu.columnLeft' or 'ContextMenu.columnRight' when the user inserts a column from the context menu, and 'auto' when the minCols or minSpareCols option adds columns. These are not the context menu item keys (col_left, col_right). |
afterCreateRow
afterCreateRow(index, amount, [source])
Fired after created a new row.
| Param | Type | Description |
|---|---|---|
| index | number | Represents the visual index of first newly created row in the data source array. |
| amount | number | Number of newly created rows in the data source array. |
| [source] | string | optional String that identifies source of hook call (list of all available sources). For example, 'ContextMenu.rowAbove' or 'ContextMenu.rowBelow' when the user inserts a row from the context menu, and 'auto' when the minRows or minSpareRows option adds rows. These are not the context menu item keys (row_above, row_below). |
afterCustomBordersUpdate
afterCustomBordersUpdate
Fired by the CustomBorders plugin after all custom borders from the configuration have
been applied. With customBordersProgressive
disabled it fires once, synchronously, right after the borders are built. With progressive
application enabled it fires when the last background batch has been applied, signaling that
getBorders() and the borders’ cell meta are now complete.
Since: 18.1.0
afterCut
afterCut(data, coords)
Fired by CopyPaste plugin after data was cut out from the table. This hook is fired when Options#copyPaste option is enabled.
| Param | Type | Description |
|---|---|---|
| data | Array<Array> | An array of arrays with the cut data. |
| coords | Array<object> | An array of objects with ranges of the visual indexes (startRow, startCol, endRow, endCol) which was cut out. |
afterDataProviderFetch
afterDataProviderFetch(result)
Fired after the dataProvider has fetched and loaded data.
With the SheetsBar plugin, it also fires when you switch back to a sheet whose rows were fetched
earlier, with that sheet’s saved response. Such a payload carries isRestored: true, so you can tell it apart
from a new fetchRows response.
Since: 17.1.0
| Param | Type | Description |
|---|---|---|
| result | object | Result object: { rows, totalRows, queryParameters, columnSortConfig, filtersConditionsStack }, plus isRestored: true when the payload replays a saved response instead of a new fetchRows response. |
afterDataProviderFetchAbort
afterDataProviderFetchAbort(queryParameters, reason)
Fired after a dataProvider fetchRows request ends without loading data because it was aborted
(superseded by a newer fetch, AbortSignal, or plugin disable/destroy).
A newer fetch supersedes the running one only once it starts: when a Hooks#beforeDataProviderFetch listener cancels the newer fetch, the running one keeps going and this hook does not fire for it.
Since: 17.1.0
| Param | Type | Description |
|---|---|---|
| queryParameters | object | The query parameters that were used for the aborted request. |
| reason | Error undefined | Abort reason when available (e.g. AbortError). |
afterDataProviderFetchError
afterDataProviderFetchError(error, queryParameters, [isVisible])
Fired when the dataProvider fetch throws an error (e.g. network error).
With the SheetsBar plugin, it also fires for a sheet you have switched away from, right when its
fetch fails; isVisible is then passed as false, and the error notification waits until you switch back to
that sheet.
Since: 17.1.0
| Param | Type | Description |
|---|---|---|
| error | Error | The thrown error. |
| queryParameters | object | The query parameters that were used for the request. |
| [isVisible] | boolean | optional Passed as false when the request was made for a SheetsBar sheet other than the one the grid shows; omitted otherwise, so a grid without SheetsBar gets the same two arguments as before. |
afterDeselect
afterDeselect
Fired after all selected cells are deselected.
afterDestroy
afterDestroy
Fired after destroying the Handsontable instance.
afterDetachChild
afterDetachChild(parent, element, finalElementPosition, [source])
Fired by NestedRows plugin after detaching a child from its parent. This hook is fired when Options#nestedRows option is enabled.
| Param | Type | Description |
|---|---|---|
| parent | object | An object representing the parent from which the element was detached. |
| element | object | The detached element. |
| finalElementPosition | number | The final row index of the detached element. |
| [source] | string | optional String that identifies source of hook call. It is 'NestedRows' for a detach made through the plugin, and 'UndoRedo.redo' when the UndoRedo plugin replays one (list of all available sources). |
afterDialogFocus
afterDialogFocus(focusSource)
Fired by Dialog plugin when the focus is set. This hook is fired when Options#dialog option is enabled.
Since: 16.1.0
| Param | Type | Description |
|---|---|---|
| focusSource | 'tab_from_above' 'tab_from_below' 'click' 'show' | The source of the focus. |
afterDialogHide
afterDialogHide
Fired by Dialog plugin after hiding the dialog. This hook is fired when Options#dialog option is enabled.
Since: 16.1.0
afterDialogShow
afterDialogShow
Fired by Dialog plugin after showing the dialog. This hook is fired when Options#dialog option is enabled.
Since: 16.1.0
afterDocumentKeyDown
afterDocumentKeyDown(event)
Hook fired after keydown event is handled.
| Param | Type | Description |
|---|---|---|
| event | Event | A native keydown event object. |
afterDrawSelection
afterDrawSelection(currentRow, currentColumn, cornersOfSelection, layerLevel) ⇒ string | undefined
Fired inside the Walkontable’s selection draw method. Can be used to add additional class names to cells, depending on the current selection.
Since: 0.38.1
| Param | Type | Description |
|---|---|---|
| currentRow | number | Row index of the currently processed cell. |
| currentColumn | number | Column index of the currently cell. |
| cornersOfSelection | Array<number> | Array of the current selection in a form of [startRow, startColumn, endRow, endColumn]. |
| layerLevel | number undefined | Number indicating which layer of selection is currently processed. |
Returns: string | undefined - Can return a String, which will act as an additional className to be added to the currently processed cell.
afterDropdownMenuDefaultOptions
afterDropdownMenuDefaultOptions(predefinedItems)
Fired by DropdownMenu plugin after setting up the dropdown menu’s default options. These options are a collection which user can select by setting an array of keys or an array of objects in Options#dropdownMenu option.
| Param | Type | Description |
|---|---|---|
| predefinedItems | Array<object> | An array of objects containing information about the pre-defined dropdown menu items. |
afterDropdownMenuHide
afterDropdownMenuHide(instance)
Fired by DropdownMenu plugin after hiding the dropdown menu. This hook is fired when Options#dropdownMenu option is enabled.
| Param | Type | Description |
|---|---|---|
| instance | DropdownMenu | The DropdownMenu instance. |
afterDropdownMenuShow
afterDropdownMenuShow(dropdownMenu)
Fired by DropdownMenu plugin after opening the dropdown menu. This hook is fired when Options#dropdownMenu option is enabled.
| Param | Type | Description |
|---|---|---|
| dropdownMenu | DropdownMenu | The DropdownMenu instance. |
afterEmptyDataStateHide
afterEmptyDataStateHide
Fired by EmptyDataState plugin after hiding the empty data state overlay. This hook is fired when Options#emptyDataState option is enabled.
Since: 16.2.0
afterEmptyDataStateShow
afterEmptyDataStateShow
Fired by EmptyDataState plugin after showing the empty data state overlay. This hook is fired when Options#emptyDataState option is enabled.
Since: 16.2.0
afterFilter
afterFilter(conditionsStack)
Fired by the Filters plugin,
after a column filter gets applied.
afterFilter takes one argument (conditionsStack), which is an array of objects.
Each object represents one of your column filters,
and consists of the following properties:
| Property | Possible values | Description |
|---|---|---|
column | Number | A physical index of the column to which the filter was applied. |
conditions | Array of objects | Each object represents one condition. For details, see addCondition(). |
operation | 'conjunction' | 'disjunction' | 'disjunctionWithExtraCondition' | An operation to perform on your set of conditions. For details, see addCondition(). |
An example of the format of the conditionsStack argument:
[ { column: 2, conditions: [ {name: 'begins_with', args: [['S']]} ], operation: 'conjunction' }, { column: 4, conditions: [ {name: 'not_empty', args: []} ], operation: 'conjunction' },]Read more:
- Guides: Column filter
- Hooks:
beforeFilter - Options:
filters - Plugins:
Filters– Plugin methods:addCondition()
| Param | Type | Description |
|---|---|---|
| conditionsStack | Array<object> | An array of objects with your column filters. |
afterFontsLoad
afterFontsLoad
Fired after the document finishes loading a web font, before Handsontable renders the grid again. A font that loads after the grid renders changes the size of the text without changing the size of the container, so a plugin that caches sizes measured from text drops or re-measures them here. The sizing plugins that ship with Handsontable re-measure on this hook too, after the listeners you add with the default order (including a listener in the settings object), so a listener that drops a custom renderer’s cached sizes runs before they measure.
The hook fires for every font the document loads, whether or not the grid uses it. On a hidden grid
(for example, display: none), it fires once the grid is shown and comes into view.
Since: 19.0.0
afterFormulasValuesUpdate
afterFormulasValuesUpdate(changes)
Fired by the Formulas plugin, when any cell value changes.
Returns an array of objects that contains:
- The addresses (
sheet,row,col) and new values (newValue) of the changed cells. - The addresses and new values of any cells that had to be recalculated (because their formulas depend on the cells that changed).
This hook gets also fired on Handsontable’s initialization, returning the addresses and values of all cells.
The row and col of each address are HyperFormula engine indexes, not Handsontable visual indexes.
They match Handsontable’s physical and visual indexes only when no rows or columns are moved, trimmed, or hidden.
Once you reorder, trim, or hide rows or columns, the engine indexes diverge from the visual ones.
Read more:
Since: 9.0.0
| Param | Type | Description |
|---|---|---|
| changes | Array | The addresses and new values of all the changed and recalculated cells. |
afterFreezeChange
afterFreezeChange(edge, newCount, oldCount, source)
Fired by FreezeBar plugin after the number of frozen rows or columns changed. The plugin changes the count on the grid only, and does not write it back to the settings you passed in. Copy the new count into your own state here. This hook is fired when the Options#freezeBar option is enabled.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| edge | 'top' 'bottom' 'start' 'end' | The edge of the frozen area. start and end follow the layout direction. |
| newCount | number | The new number of frozen rows or columns on that edge. |
| oldCount | number | The previous number of frozen rows or columns on that edge. |
| source | 'drag' 'keyboard' 'api' | What requested the change. |
afterGetCellMeta
afterGetCellMeta(row, column, cellProperties)
Fired after getting the cell settings.
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
| column | number | Visual column index. |
| cellProperties | object | Object containing the cell properties. |
afterGetColHeader
afterGetColHeader(column, TH, [headerLevel])
Fired after retrieving information about a column header and appending it to the table header.
| Param | Type | Default | Description |
|---|---|---|---|
| column | number | Visual column index. In a grid scrolled horizontally, the corner of the main table and of the top overlay gets the index of the column before the first rendered one, not a negative index. | |
| TH | HTMLTableCellElement | Header’s TH element. | |
| [headerLevel] | number | 0 | optional (Since 12.2.0) Header level index. Accepts positive (0 to n) and negative (-1 to -n) values. For positive values, 0 points to the topmost header. For negative values, -1 points to the bottom-most header (the header closest to the cells). |
afterGetColumnHeaderRenderers
afterGetColumnHeaderRenderers(renderers)
Fired after getting the column header renderers.
The renderers array initially contains one renderer function when colHeaders
is enabled, or zero functions when it is disabled. Each function in the array renders one layer of
column headers above the grid. By pushing additional renderer functions to the array, you can display
more than one layer of column headers simultaneously.
Each renderer function receives the following arguments:
| Argument | Type | Description |
|---|---|---|
renderedColumnIndex | number | The renderable index of the column. |
TH | HTMLTableCellElement | The <th> element to modify. |
Handsontable also calls the first renderer in the array on the <th> elements of an off-screen table,
to measure the height of the column headers. Such a <th> is not in the grid’s overlays.
new Handsontable(container, { colHeaders: true, afterGetColumnHeaderRenderers(renderers) { // Add a second layer of column headers above the default one. renderers.push((renderedColumnIndex, TH) => { TH.innerText = `Extra: ${renderedColumnIndex}`; }); },});Read more:
| Param | Type | Description |
|---|---|---|
| renderers | Array<function()> | An array of the column header renderers. |
afterGetRowHeader
afterGetRowHeader(row, TH)
Fired after retrieving information about a row header and appending it to the table header.
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
| TH | HTMLTableCellElement | Header’s TH element. |
afterGetRowHeaderRenderers
afterGetRowHeaderRenderers(renderers)
Fired after getting the row header renderers.
The renderers array initially contains one renderer function when rowHeaders
is enabled, or zero functions when it is disabled. Each function in the array renders one layer of
row headers to the left of the grid. By pushing additional renderer functions to the array, you can display
more than one layer of row headers simultaneously.
Each renderer function receives the following arguments:
| Argument | Type | Description |
|---|---|---|
renderableRowIndex | number | The renderable index of the row. |
TH | HTMLTableCellElement | The <th> element to modify. |
new Handsontable(container, { rowHeaders: true, afterGetRowHeaderRenderers(renderers) { // Add a second layer of row headers next to the default one. renderers.push((renderableRowIndex, TH) => { TH.innerText = `Extra: ${renderableRowIndex}`; }); },});Read more:
| Param | Type | Description |
|---|---|---|
| renderers | Array<function()> | An array of the row header renderers. |
afterHeaderChange
afterHeaderChange(axis, visualIndex, newValue, oldValue)
Fired by the EditableHeaders plugin after a column or row header is renamed, and for every header an undo, a redo or EditableHeaders#clearHeaders changes. Use it to save the new value in your application.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| axis | string | 'column' for a column header, 'row' for a row header. |
| visualIndex | number | The visual index of the column or row. |
| newValue | string | The new header value. |
| oldValue | * | The header value shown before the change. |
afterHideColumns
afterHideColumns(currentHideConfig, destinationHideConfig, actionPossible, stateChanged)
Fired by HiddenColumns plugin after marking the columns as hidden. Fired only if the Options#hiddenColumns option is enabled.
The hook also fires once while Handsontable initializes, before the grid has a view. At that point,
Core#getFirstFullyVisibleColumn and the other viewport getters of Core return null, and
AutoColumnSize#getFirstVisibleColumn and AutoColumnSize#getLastVisibleColumn return -1.
Methods that need the rendered grid, such as Core#selectCell, are not available yet.
| Param | Type | Description |
|---|---|---|
| currentHideConfig | Array | Current hide configuration - a list of hidden physical column indexes. |
| destinationHideConfig | Array | Destination hide configuration - a list of hidden physical column indexes. |
| actionPossible | boolean | true, if the provided column indexes are valid, false otherwise. |
| stateChanged | boolean | true, if the action affected any non-hidden columns, false otherwise. |
afterHideRows
afterHideRows(currentHideConfig, destinationHideConfig, actionPossible, stateChanged)
Fired by HiddenRows plugin after marking the rows as hidden. Fired only if the Options#hiddenRows option is enabled.
The hook also fires once while Handsontable initializes, before the grid has a view. At that point,
Core#getFirstFullyVisibleRow and the other viewport getters of Core return null, and
AutoRowSize#getFirstVisibleRow and AutoRowSize#getLastVisibleRow return -1.
Methods that need the rendered grid, such as Core#selectCell, are not available yet.
| Param | Type | Description |
|---|---|---|
| currentHideConfig | Array | Current hide configuration - a list of hidden physical row indexes. |
| destinationHideConfig | Array | Destination hide configuration - a list of hidden physical row indexes. |
| actionPossible | boolean | true, if provided row indexes are valid, false otherwise. |
| stateChanged | boolean | true, if the action affected any non-hidden rows, false otherwise. |
afterImport
afterImport(result, format)
Fired by the ImportFile plugin after the imported result was applied to the grid. Not
fired for an import with apply: false, for one that a newer import replaced, or for one the
plugin was disabled during (importFile: false while the file was being read).
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| result | ImportResult | The applied ImportFile result. |
| format | string | The import format, e.g. 'xlsx'. |
afterInit
afterInit
Fired after the Handsontable instance is initiated.
afterLanguageChange
afterLanguageChange(languageCode)
Fired after successful change of language (when proper language code was set).
Since: 0.35.0
| Param | Type | Description |
|---|---|---|
| languageCode | string | New language code. |
afterListen
afterListen
Fired after the table was switched into listening mode. This allows Handsontable to capture keyboard events and respond in the right way.
afterLoadData
afterLoadData(sourceData, initialLoad, source)
Fired after Handsontable’s data
gets modified by the loadData() method
or the updateSettings() method.
The hook also fires once while Handsontable initializes (initialLoad is true), before the grid has a view.
The data getters, such as Core#getDataAtCol, and the writes, such as Core#setDataAtCell, work there. The viewport getters, such as
Core#getFirstFullyVisibleColumn, and Core#getCell return null. Methods that need the rendered grid,
such as Core#selectCell and Core#scrollViewportTo, select or scroll nothing and return false.
Read more:
| Param | Type | Description |
|---|---|---|
| sourceData | Array | An array of arrays, or an array of objects, that contains Handsontable’s data |
| initialLoad | boolean | A flag that indicates whether the data was loaded at Handsontable’s initialization (true) or later (false) |
| source | string | The source of the call |
afterLoadingHide
afterLoadingHide
Fired by Loading plugin after hiding the loading indicator. This hook is fired when Options#loading option is enabled.
It also fires when the loading indicator goes away through the Dialog plugin: Dialog#hide, the Escape key on a closable dialog, or a dialog shown over the loading indicator. Hooks#beforeLoadingHide does not fire in those cases.
Since: 16.1.0
afterLoadingShow
afterLoadingShow
Fired by Loading plugin after showing the loading indicator. This hook is fired when Options#loading option is enabled.
Since: 16.1.0
afterMergeCells
afterMergeCells(cellRange, mergeParent, [auto])
Fired by MergeCells plugin after cell merging. This hook is fired when Options#mergeCells option is enabled.
| Param | Type | Default | Description |
|---|---|---|---|
| cellRange | CellRange | Selection cell range. | |
| mergeParent | object | The parent collection of the provided cell range. | |
| [auto] | boolean | false | optional true if called automatically by the plugin. |
afterModifyTransformEnd
afterModifyTransformEnd(coords, rowTransformDir, colTransformDir)
Fired after the end of the selection is being modified (e.g. Moving the selection with the arrow keys).
| Param | Type | Description |
|---|---|---|
| coords | CellCoords | Visual coords of the freshly selected cell. |
| rowTransformDir | number | -1 if trying to select a cell with a negative row index. 0 otherwise. |
| colTransformDir | number | -1 if trying to select a cell with a negative column index. 0 otherwise. |
afterModifyTransformFocus
afterModifyTransformFocus(coords, rowTransformDir, colTransformDir)
Fired after the focus of the selection is being modified (e.g. Moving the focus with the enter/tab keys).
Since: 14.3.0
| Param | Type | Description |
|---|---|---|
| coords | CellCoords | Coords of the freshly focused cell. |
| rowTransformDir | number | -1 if trying to focus a cell with a negative row index. 0 otherwise. |
| colTransformDir | number | -1 if trying to focus a cell with a negative column index. 0 otherwise. |
afterModifyTransformStart
afterModifyTransformStart(coords, rowTransformDir, colTransformDir)
Fired after the start of the selection is being modified (e.g. Moving the selection with the arrow keys).
| Param | Type | Description |
|---|---|---|
| coords | CellCoords | Coords of the freshly selected cell. |
| rowTransformDir | number | -1 if trying to select a cell with a negative row index. 0 otherwise. |
| colTransformDir | number | -1 if trying to select a cell with a negative column index. 0 otherwise. |
afterMomentumScroll
afterMomentumScroll
Fired after a scroll event, which is identified as a momentum scroll (e.g. on an iPad).
afterMoveCells
afterMoveCells(sourceRange, targetRange, isCopy)
Fired after a moveCells drag has relocated a selection.
Since: 18.1.0
| Param | Type | Description |
|---|---|---|
| sourceRange | CellRange | The original range. |
| targetRange | CellRange | The range the data was moved to. |
| isCopy | boolean | true when the operation was a copy. |
afterNamedExpressionAdded
afterNamedExpressionAdded(namedExpressionName, changes)
Fired by the Formulas plugin when a named expression is added to the engine instance.
This hook fires after the HyperFormula engine’s addNamedExpression() method runs, either
because you called it directly or because you defined the namedExpressions configuration option.
Read more:
Since: 9.0.0
| Param | Type | Description |
|---|---|---|
| namedExpressionName | string | The name of the added expression. |
| changes | Array | The values and location of applied changes. |
afterNamedExpressionRemoved
afterNamedExpressionRemoved(namedExpressionName, changes)
Fired by the Formulas plugin when a named expression is removed from the engine instance.
This hook fires after the HyperFormula engine’s removeNamedExpression() method runs.
Read more:
Since: 9.0.0
| Param | Type | Description |
|---|---|---|
| namedExpressionName | string | The name of the removed expression. |
| changes | Array | The values and location of applied changes. |
afterNotificationHide
afterNotificationHide(id)
Fired by Notification plugin after a toast is hidden.
Since: 17.1.0
| Param | Type | Description |
|---|---|---|
| id | string | Toast id. |
afterNotificationShow
afterNotificationShow(id, options)
Fired by Notification plugin after a toast is shown.
Since: 17.1.0
| Param | Type | Description |
|---|---|---|
| id | string | Toast id. |
| options | object | Normalized toast options. |
afterOnCellContextMenu
afterOnCellContextMenu(event, coords, TD)
Fired after clicking right mouse button on a cell or row/column header.
For example clicking on the row header of cell (0, 0) results with afterOnCellContextMenu called
with coordinates {row: 0, col: -1}.
Since: 4.1.0
| Param | Type | Description |
|---|---|---|
| event | Event | contextmenu event object. |
| coords | CellCoords | Coordinates object containing the visual row and visual column indexes of the clicked cell. |
| TD | HTMLTableCellElement | Cell’s TD (or TH) element. |
afterOnCellCornerDblClick
afterOnCellCornerDblClick(event)
Fired after a dblclick event is triggered on the cell corner (the drag handle).
| Param | Type | Description |
|---|---|---|
| event | Event | dblclick event object. |
afterOnCellCornerMouseDown
afterOnCellCornerMouseDown(event)
Fired after a mousedown event is triggered on the cell corner (the drag handle).
| Param | Type | Description |
|---|---|---|
| event | Event | mousedown event object. |
afterOnCellMouseDown
afterOnCellMouseDown(event, coords, TD)
Fired after clicking on a cell or row/column header. In case the row/column header was clicked, the coordinate indexes are negative.
For example clicking on the row header of cell (0, 0) results with afterOnCellMouseDown called
with coordinates {row: 0, col: -1}.
| Param | Type | Description |
|---|---|---|
| event | Event | mousedown event object. |
| coords | CellCoords | Coordinates object containing the visual row and visual column indexes of the clicked cell. |
| TD | HTMLTableCellElement | Cell’s TD (or TH) element. |
afterOnCellMouseOut
afterOnCellMouseOut(event, coords, TD)
Fired after leaving a cell or row/column header with the mouse cursor.
| Param | Type | Description |
|---|---|---|
| event | Event | mouseout event object. |
| coords | CellCoords | Leaved cell’s visual coordinate object. |
| TD | HTMLTableCellElement | Cell’s TD (or TH) element. |
afterOnCellMouseOver
afterOnCellMouseOver(event, coords, TD)
Fired after hovering a cell or row/column header with the mouse cursor. In case the row/column header was hovered, the index is negative.
For example, hovering over the row header of cell (0, 0) results with afterOnCellMouseOver called
with coords {row: 0, col: -1}.
| Param | Type | Description |
|---|---|---|
| event | Event | mouseover event object. |
| coords | CellCoords | Hovered cell’s visual coordinate object. |
| TD | HTMLTableCellElement | Cell’s TD (or TH) element. |
afterOnCellMouseOverOutside
afterOnCellMouseOverOutside(event, coords, TD)
Fired after the mouse cursor moves outside the visible viewport while a mouse button is held down (e.g. during a drag-to-scroll operation). The event fires once per mousemove tick for as long as the cursor remains outside the viewport.
Since: 17.2.0
| Param | Type | Description |
|---|---|---|
| event | Event | mousemove event object. |
| coords | CellCoords | Visual coordinates of the nearest viewport-edge cell. |
| TD | HTMLTableCellElement | Cell’s TD (or TH) element. |
afterOnCellMouseUp
afterOnCellMouseUp(event, coords, TD)
Fired after clicking on a cell or row/column header. In case the row/column header was clicked, the coordinate indexes are negative.
For example clicking on the row header of cell (0, 0) results with afterOnCellMouseUp called
with coordinates {row: 0, col: -1}.
| Param | Type | Description |
|---|---|---|
| event | Event | mouseup event object. |
| coords | CellCoords | Coordinates object containing the visual row and visual column indexes of the clicked cell. |
| TD | HTMLTableCellElement | Cell’s TD (or TH) element. |
afterOnSelectionEdgeMouseDown
afterOnSelectionEdgeMouseDown(event, edge)
Fired after the user presses a selection edge move zone.
Since: 18.1.0
| Param | Type | Description |
|---|---|---|
| event | Event | The mousedown event. |
| edge | 'top' 'bottom' 'start' 'end' | The pressed edge. |
afterOnSelectionHandleMouseDown
afterOnSelectionHandleMouseDown(event, edge)
Fired after the user presses a selection-adjustment handle (see selectionHandles).
Since: 18.1.0
| Param | Type | Description |
|---|---|---|
| event | Event | The mousedown event. |
| edge | 'top' 'bottom' 'start' 'end' | The pressed handle’s edge. |
afterPageChange
afterPageChange(oldPage, newPage)
Fired by Pagination plugin after changing the page. This hook is fired when
Options#pagination option is enabled. When a complete Options#dataProvider configuration
handles paging, DataProvider loads the requested page via fetchRows. Pagination then aligns its
UI from Hooks#afterDataProviderFetch.
Since: 16.1.0
| Param | Type | Description |
|---|---|---|
| oldPage | number | The old page number. |
| newPage | number | The new page number. |
afterPageCounterVisibilityChange
afterPageCounterVisibilityChange(isVisible)
Fired by Pagination plugin after changing the visibility state of the page counter section. This hook is fired when Options#pagination option is enabled.
Since: 16.1.0
| Param | Type | Description |
|---|---|---|
| isVisible | boolean | The visibility state of the page size section. |
afterPageNavigationVisibilityChange
afterPageNavigationVisibilityChange(isVisible)
Fired by Pagination plugin after changing the visibility state of the page navigation section. This hook is fired when Options#pagination option is enabled.
Since: 16.1.0
| Param | Type | Description |
|---|---|---|
| isVisible | boolean | The visibility state of the page size section. |
afterPageSizeChange
afterPageSizeChange(oldPageSize, newPageSize)
Fired by Pagination plugin after changing the page size. This hook is fired when
Options#pagination option is enabled. When a complete Options#dataProvider configuration
handles paging, DataProvider loads page 1 for the new size via fetchRows. Pagination then aligns
its UI from Hooks#afterDataProviderFetch.
Since: 16.1.0
| Param | Type | Description |
|---|---|---|
| oldPageSize | number 'auto' | The old page size. |
| newPageSize | number 'auto' | The new page size. |
afterPageSizeVisibilityChange
afterPageSizeVisibilityChange(isVisible)
Fired by Pagination plugin after changing the visibility state of the page size section. This hook is fired when Options#pagination option is enabled.
Since: 16.1.0
| Param | Type | Description |
|---|---|---|
| isVisible | boolean | The visibility state of the page size section. |
afterPaste
afterPaste(data, coords)
Fired by CopyPaste plugin after the plugin hands the pasted values to the grid. This hook is fired when Options#copyPaste option is enabled.
afterPaste doesn’t wait for the values to be written. The order depends on whether any pasted
cell has a validator:
- With a validator,
afterPasteruns before Handsontable writes any pasted value, including the cells without a validator. The validator runs afterafterPaste, so a cell still holds its previous value andvalidflag. If the paste adds rows,afterPastealso runs before those rows exist. The order is thenafterPaste,afterCreateRow, andafterChange. - Without a validator,
afterChangeruns first andafterPastefollows. A paste that adds rows runsafterCreateRowbeforeafterChange.
A cell has a validator when you set one, when its cell type provides one (for example numeric,
date, dropdown, or autocomplete), or when you set a maxLength
that is a finite number of 0 or more.
To change or cancel the pasted values, use beforePaste. To react once the cells hold
the new values, use afterChange and check for the 'CopyPaste.paste' source.
When copyPaste sets pasteMode to 'shift_down' or 'shift_right',
the source is 'populateFromArray'.
| Param | Type | Description |
|---|---|---|
| data | Array<Array> | An array of arrays with the pasted data. |
| coords | Array<object> | An array of objects with ranges of the visual indexes (startRow, startCol, endRow, endCol) that correspond to the previously selected area. |
afterPluginsInitialized
afterPluginsInitialized
Fired after initializing all the plugins. This hook should be added before Handsontable is initialized.
This hook runs while beforeInit is being dispatched, before Handsontable reads the callbacks
from the settings object. An afterPluginsInitialized callback passed in the settings object is
registered too late, so it never runs. To listen to this hook, register it globally with
Handsontable.hooks.add('afterPluginsInitialized', callback).
Example
Handsontable.hooks.add('afterPluginsInitialized', myCallback);afterRedo
afterRedo(action)
Fired by UndoRedo plugin after the redo action. Contains information about the action that is being redone. This hook is fired when Options#undo option is enabled.
| Param | Type | Description |
|---|---|---|
| action | object | The action object. Contains information about the action being redone. The actionType property of the object specifies the type of the action in a String format (e.g. 'remove_row'). |
afterRedoStackChange
afterRedoStackChange(undoneActionsBefore, undoneActionsAfter)
Fired by UndoRedo plugin after changing redo stack.
Since: 8.4.0
| Param | Type | Description |
|---|---|---|
| undoneActionsBefore | Array | Stack of actions which could be redone before performing new action. |
| undoneActionsAfter | Array | Stack of actions which can be redone after performing new action. |
afterRefreshDimensions
afterRefreshDimensions(previousDimensions, currentDimensions, stateChanged)
Fired after the window was resized or the size of the Handsontable root element was changed. A
re-measure after a web font loads does not fire it (see afterFontsLoad).
| Param | Type | Description |
|---|---|---|
| previousDimensions | Object | Previous dimensions of the container. |
| currentDimensions | Object | Current dimensions of the container. |
| stateChanged | boolean | true, if the container was re-render, false otherwise. |
afterRemoveCellMeta
afterRemoveCellMeta(row, column, key, value)
Fired after cell meta is removed.
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
| column | number | Visual column index. |
| key | string | The removed meta key. |
| value | * | Value which was under removed key of cell meta. |
afterRemoveCol
afterRemoveCol(index, amount, physicalColumns, [source])
Fired after one or more columns are removed.
Columns are removed in runs of neighboring columns, and this hook fires once per run. This
is by design. Removing columns 1, 2, and 3 fires the hook once. Removing columns 0, 1,
and 3 (for example, by selecting columns with Ctrl/Cmd held) fires it twice: once for the
0, 1 run, then once for 3.
Two columns count as neighbors by their visual index, so sorting or moving columns changes how one selection is grouped into runs.
amount is the number of columns the call asked to remove, which is not always the number
it removed. A request that runs past the last column is cut short, but amount is not:
alter('remove_col', 4, 5) on a six-column grid reports amount as 5 and removes two.
Read physicalColumns.length for the count that was really removed.
Every call describes the data source as it stands at that moment, so the index and
physicalColumns of a later call already account for the columns that the earlier calls
removed.
This hook fires on every non-canceled removal call, including a no-op that removed nothing
(for example alter('remove_col') on a grid with no columns, where physicalColumns is
empty). It is therefore not paired one-to-one with an undo-stack entry: a no-op removal
does not stack an undo action, so do not treat “afterRemoveCol fired” as proof that an undo
entry now exists.
| Param | Type | Description |
|---|---|---|
| index | number | Visual index of starter column. |
| amount | number | The number of columns the call requested to remove, which may exceed the number actually removed - read physicalColumns.length for the removed count. |
| physicalColumns | Array<number> | An array of physical columns removed from the data source. |
| [source] | string | optional String that identifies source of hook call (list of all available sources). |
afterRemoveRow
afterRemoveRow(index, amount, physicalRows, [source])
Fired after one or more rows are removed.
Rows are removed in runs of neighboring rows, and this hook fires once per run. This is by
design. Removing rows 1, 2, and 3 fires the hook once, with amount set to 3. Removing
rows 0, 1, and 3 (for example, by selecting rows with Ctrl/Cmd held) fires it twice: first
with amount set to 2, then with amount set to 1.
Two rows count as neighbors by their visual index, so sorting, moving, or hiding rows changes how one selection is grouped into runs. Two rows that sit next to each other on screen with a hidden row between them are not neighbors, and they fire two calls.
amount is the number of rows this call really removed, which is always
physicalRows.length. A beforeRemoveRow handler that edits that
array changes both, which is how the NestedRows plugin adds the
descendants of a removed parent.
physicalRows holds physical indexes, so on a sorted or reordered grid it is neither
ascending nor contiguous even for a single run. Every call also describes the data source
as it stands at that moment, so the index and physicalRows of a later call already
account for the rows that the earlier calls removed.
This hook fires on every non-canceled removal call, including a no-op that removed nothing
(for example alter('remove_row') on a grid with no rows, where physicalRows is empty and
amount is 0). It is therefore not paired one-to-one with an undo-stack entry: a no-op
removal does not stack an undo action, so do not treat “afterRemoveRow fired” as proof that
an undo entry now exists.
| Param | Type | Description |
|---|---|---|
| index | number | Visual index of starter row. |
| amount | number | An amount of removed rows. |
| physicalRows | Array<number> | An array of physical rows removed from the data source. |
| [source] | string | optional String that identifies source of hook call (list of all available sources). |
afterRender
afterRender(isForced)
Fired after Handsontable’s view-rendering engine updates the view.
| Param | Type | Description |
|---|---|---|
| isForced | boolean | If set to true, the rendering gets triggered by a change of settings, a change of data, or a logic that needs a full Handsontable render cycle. If set to false, the rendering gets triggered by something lighter, such as moving the selection. The flag describes what triggered the render, not how much was redrawn: a false render still redraws cells when it brings a new row or column band into view. Scrolling does not fire this hook at all. |
afterRenderer
afterRenderer(TD, row, column, prop, value, cellProperties)
Fired after finishing rendering the cell (after the renderer finishes).
| Param | Type | Description |
|---|---|---|
| TD | HTMLTableCellElement | Currently rendered cell’s TD element. |
| row | number | Visual row index. |
| column | number | Visual column index. |
| prop | string number | Column property name or a column index, if datasource is an array of arrays. |
| value | * | Value of the rendered cell. |
| cellProperties | object | Object containing the cell’s properties. |
afterResumeExecution
afterResumeExecution
Fired by Core#resumeExecution after it resumes the execution and updates the index cache, so
the index changes made while the execution was suspended are already applied.
batch() and batchExecution() resume the
execution the same way, and so does Handsontable itself (for example, to size columns on a render).
batch() resumes rendering after this hook.
The hook fires only when the execution changes from suspended to resumed: a nested call, a forced
nested call, and a call while the execution is not suspended fire nothing. It fires even when a
beforeResumeExecution listener or the index cache update throws. The hook does not fire while the
instance is being destroyed. A listener that suspends the execution again, directly or through a render,
starts a new cycle, which fires all four hooks again, this one included.
Since: 19.0.0
Example
<HotTable afterResumeExecution={() => { console.log('The execution is resumed'); }}/>afterRowCollapse
afterRowCollapse(currentCollapsedRows, destinationCollapsedRows, collapsePossible, successfullyCollapsed)
Fired by the NestedRows plugin after parent rows are collapsed. This hook is fired when the Options#nestedRows option is enabled.
Since: 18.1.0
| Param | Type | Description |
|---|---|---|
| currentCollapsedRows | Array | A list of the physical indexes of the parent rows that were collapsed before the action. |
| destinationCollapsedRows | Array | A list of the physical indexes of the parent rows collapsed after the action. |
| collapsePossible | boolean | true, if every provided index points at a row that has children, false otherwise. |
| successfullyCollapsed | boolean | true, if the action changed the collapsed state, false otherwise. |
afterRowExpand
afterRowExpand(currentCollapsedRows, destinationCollapsedRows, expandPossible, successfullyExpanded)
Fired by the NestedRows plugin after parent rows are expanded. This hook is fired when the Options#nestedRows option is enabled.
Since: 18.1.0
| Param | Type | Description |
|---|---|---|
| currentCollapsedRows | Array | A list of the physical indexes of the parent rows that were collapsed before the action. |
| destinationCollapsedRows | Array | A list of the physical indexes of the parent rows collapsed after the action. |
| expandPossible | boolean | true, if every provided index points at a row that has children, false otherwise. |
| successfullyExpanded | boolean | true, if the action changed the collapsed state, false otherwise. |
afterRowIdsRemoved
afterRowIdsRemoved(rowIds, [source])
Fired after rows that had ids (see the rowId option) stopped existing: after a row
removal (an undo or a redo included), and after loadData() or
updateData() replaced the data with data that no longer holds those ids.
Use it to cancel pending work, such as an asynchronous request, made for those rows. A row that is trimmed or filtered out still exists, so it is not reported.
The hook fires in a microtask once the call that removed the rows has finished, with every id that call
removed. So the rows a call takes away and puts back, like a NestedRows detach or
row move, are not reported.
A grid backed by an external data source (the DataProvider plugin) loads every
page, sort, and filter with loadData(), and the rows it drops still exist on the server, so a data load
there reports nothing. A removal the server confirms (afterRowsMutation with 'remove') is reported with
the 'dataProvider' source.
The hook reads the ids only while it has listeners, so a grid that does not listen to it pays nothing.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| rowIds | Array | The ids of the rows that no longer exist. |
| [source] | string | optional String that identifies the source of the change (list of all available sources). |
afterRowIdsReset
afterRowIdsReset
Fired after a settings update changed how rows get their ids (the rowId
option, or dataProvider.rowId), while the rows had ids before it. Every id read before the update may now
name another row or none, so look the rows up again or cancel the pending work made for them.
A function passed as rowId is compared by reference: pass the same function on every settings update, or
the hook fires each time.
Since: 19.0.0
afterRowMove
afterRowMove(movedRows, finalIndex, dropIndex, movePossible, orderChanged)
Fired by ManualRowMove plugin after changing the order of the visual indexes. This hook is fired when Options#manualRowMove option is enabled. It doesn’t fire when the user presses a row header and releases it without moving the pointer more than a few pixels.
The hook also fires when the move leaves the order unchanged, for example when you drop a row back where it
was. In that case, orderChanged is false.
| Param | Type | Description |
|---|---|---|
| movedRows | Array | Array of visual row indexes to be moved. |
| finalIndex | number | Visual row index, being a start index for the moved rows. Points to where the elements will be placed after the moving action. To check visualization of final index please take a look at documentation. |
| dropIndex | number undefined | Visual row index, being a drop index for the moved rows. Points to where we are going to drop the moved elements. To check visualization of drop index please take a look at documentation. It’s undefined when dragRows function wasn’t called. |
| movePossible | boolean | Indicates if it was possible to move rows to the desired position. |
| orderChanged | boolean | Indicates if order of rows was changed by move. |
afterRowResize
afterRowResize(newSize, row, isDoubleClick)
Fired by ManualRowResize plugin after rendering the table with modified row sizes. This hook is fired when Options#manualRowResize option is enabled.
| Param | Type | Description |
|---|---|---|
| newSize | number | Calculated new row height. |
| row | number | Visual index of the resized row. |
| isDoubleClick | boolean | Flag that determines whether there was a double-click. |
afterRowSelectionChange
afterRowSelectionChange(selectedRows, deselectedRows, source)
Fired by the RowSelection plugin after the row selection changes. Fired only if the Options#rowSelection option is enabled.
With a server-backed grid (the DataProvider plugin), the lists hold only the loaded rows: a
change that affects only rows on other pages runs the hook with two empty lists. To read the full
selection, call getServerSelection().
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| selectedRows | Array<number> | Physical indexes of the rows that were selected. |
| deselectedRows | Array<number> | Physical indexes of the rows that were deselected. |
| source | string | What changed the selection: 'checkbox', 'headerCheckbox', 'click', 'keyboard', 'api', or 'dataChange'. 'dataChange' means a write to the bound checkbox column (see Options#rowSelection) that did not come from editing the cell – for example a paste, an autofill, or a setDataAtCell() call. |
afterRowSequenceCacheUpdate
afterRowSequenceCacheUpdate(indexesChangesState)
Fired after the cache of the row sequence has been updated.
Since: 16.2.0
| Param | Type | Description |
|---|---|---|
| indexesChangesState | object | Object containing information about the changes to the row sequence. |
| indexesChangesState.indexesSequenceChanged | boolean | Indicates if the sequence of indexes has changed. |
| indexesChangesState.trimmedIndexesChanged | boolean | Indicates if the trimmed indexes have changed. |
| indexesChangesState.hiddenIndexesChanged | boolean | Indicates if the hidden indexes have changed. |
| [indexesChangesState.indexesChangeSource] | 'init' 'remove' 'insert' 'move' 'update' | optional Indicates what caused a sequence change. |
afterRowSequenceChange
afterRowSequenceChange([source])
Fired after the order of rows has changed. This hook is fired by changing row indexes of any type supported by the IndexMapper.
| Param | Type | Description |
|---|---|---|
| [source] | 'init' 'remove' 'insert' 'move' 'update' | optional A string that indicates what caused the change to the order of rows. |
afterRowsMutation
afterRowsMutation(operation, payload)
Fired after rows mutation (create, update, remove) succeeds on the server.
Since: 17.1.0
| Param | Type | Description |
|---|---|---|
| operation | string | One of 'create', 'update', 'remove'. |
| payload | object | Operation-specific payload. |
afterRowsMutationError
afterRowsMutationError(operation, error, payload)
Fired when rows mutation (create, update, remove) fails on the server.
Since: 17.1.0
| Param | Type | Description |
|---|---|---|
| operation | string | One of 'create', 'update', 'remove'. |
| error | Error | The thrown error. |
| payload | object | Operation-specific payload. |
afterScroll
afterScroll
Fired after the vertical or horizontal scroll event.
Since: 14.0.0
afterScrollHorizontally
afterScrollHorizontally
Fired after the horizontal scroll event.
afterScrollVertically
afterScrollVertically
Fired after the vertical scroll event.
afterSelectAll
afterSelectAll(from, to, [highlight])
Fired after all cells are selected (e.g. during mouse corner click or Core#selectAll API call).
Since: 16.1.0
| Param | Type | Description |
|---|---|---|
| from | CellCoords | Selection start coords object. |
| to | CellCoords | Selection end coords object. |
| [highlight] | CellCoords | optional Selection cell focus coords object. |
afterSelectColumns
afterSelectColumns(from, to, highlight)
Fired after one or more columns are selected (e.g. during mouse header click or Core#selectColumns API call).
Since: 14.0.0
| Param | Type | Description |
|---|---|---|
| from | CellCoords | Selection start coords object. |
| to | CellCoords | Selection end coords object. |
| highlight | CellCoords | Selection cell focus coords object. |
afterSelection
afterSelection(row, column, row2, column2, preventScrolling, selectionLayerLevel)
Fired after one or more cells are selected (e.g. during mouse move).
Example
<HotTable afterSelection={(row, column, row2, column2, preventScrolling, selectionLayerLevel) => { // If set to `false` (default): when cell selection is outside the viewport, // Handsontable scrolls the viewport to cell selection's end corner. // If set to `true`: when cell selection is outside the viewport, // Handsontable doesn't scroll to cell selection's end corner. preventScrolling.value = true; }}/>| Param | Type | Description |
|---|---|---|
| row | number | Selection start visual row index. |
| column | number | Selection start visual column index. |
| row2 | number | Selection end visual row index. |
| column2 | number | Selection end visual column index. |
| preventScrolling | object | A reference to the observable object with the value property. Property preventScrolling.value expects a boolean value that Handsontable uses to control scroll behavior after selection. |
| selectionLayerLevel | number | The number which indicates what selection layer is currently modified. |
afterSelectionByProp
afterSelectionByProp(row, prop, row2, prop2, preventScrolling, selectionLayerLevel)
Fired after one or more cells are selected.
The prop and prop2 arguments represent the source object property name instead of the column number.
Example
<HotTable afterSelectionByProp={(row, column, row2, column2, preventScrolling, selectionLayerLevel) => { // setting if prevent scrolling after selection preventScrolling.value = true; }}/>| Param | Type | Description |
|---|---|---|
| row | number | Selection start visual row index. |
| prop | string | Selection start data source object property name. |
| row2 | number | Selection end visual row index. |
| prop2 | string | Selection end data source object property name. |
| preventScrolling | object | A reference to the observable object with the value property. Property preventScrolling.value expects a boolean value that Handsontable uses to control scroll behavior after selection. |
| selectionLayerLevel | number | The number which indicates what selection layer is currently modified. |
afterSelectionEnd
afterSelectionEnd(row, column, row2, column2, selectionLayerLevel)
Fired after one or more cells are selected (e.g. on mouse up).
| Param | Type | Description |
|---|---|---|
| row | number | Selection start visual row index. |
| column | number | Selection start visual column index. |
| row2 | number | Selection end visual row index. |
| column2 | number | Selection end visual column index. |
| selectionLayerLevel | number | The number which indicates what selection layer is currently modified. |
afterSelectionEndByProp
afterSelectionEndByProp(row, prop, row2, prop2, selectionLayerLevel)
Fired after one or more cells are selected (e.g. on mouse up).
The prop and prop2 arguments represent the source object property name instead of the column number.
| Param | Type | Description |
|---|---|---|
| row | number | Selection start visual row index. |
| prop | string | Selection start data source object property index. |
| row2 | number | Selection end visual row index. |
| prop2 | string | Selection end data source object property index. |
| selectionLayerLevel | number | The number which indicates what selection layer is currently modified. |
afterSelectionFocusSet
afterSelectionFocusSet(row, column, preventScrolling)
Fired after the focus position within a selected range is changed.
With merged cells, row and column name the cell the focus lands on: Enter and Tab stop once on
a merged cell and skip the cells it covers.
Since: 14.3.0
Example
<HotTable afterSelectionFocusSet={(row, column, preventScrolling) => { // If set to `false` (default): when focused cell selection is outside the viewport, // Handsontable scrolls the viewport to that cell. // If set to `true`: when focused cell selection is outside the viewport, // Handsontable doesn't scroll the viewport. preventScrolling.value = true; }}/>| Param | Type | Description |
|---|---|---|
| row | number | The focus visual row index position. |
| column | number | The focus visual column index position. |
| preventScrolling | object | A reference to the observable object with the value property. Property preventScrolling.value expects a boolean value that Handsontable uses to control scroll behavior after selection. |
afterSelectRows
afterSelectRows(from, to, highlight)
Fired after one or more rows are selected (e.g. during mouse header click or Core#selectRows API call).
Since: 14.0.0
| Param | Type | Description |
|---|---|---|
| from | CellCoords | Selection start coords object. |
| to | CellCoords | Selection end coords object. |
| highlight | CellCoords | Selection cell focus coords object. |
afterSetCellMeta
afterSetCellMeta(row, column, key, value)
Fired after cell meta is changed.
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
| column | number | Visual column index. |
| key | string | The updated meta key. |
| value | * | The updated meta value. |
afterSetDataAtCell
afterSetDataAtCell(changes, [source])
Fired after setDataAtCell is called and changes are processed,
before they are validated and applied to the data source.
Use afterChange if you need to react after the data has been written.
This hook fires for every setDataAtCell() call – not only when you call it directly, but also
for regular cell edits, paste, cut, Delete/Backspace, the fill handle, Ctrl+Enter, a checkbox
click, and undo/redo, since those are applied internally via setDataAtCell() too. It also fires
when a beforeChange handler cancels the change, with an empty changes array. Changes made
through setDataAtRowProp() fire afterSetDataAtRowProp
instead – never both for the same change.
| Param | Type | Description |
|---|---|---|
| changes | Array | An array of changes in format [[row, prop, oldValue, value], ...]. |
| [source] | string | optional String that identifies source of hook call (list of all available sources). |
afterSetDataAtRowProp
afterSetDataAtRowProp(changes, [source])
Fired after setDataAtRowProp is called and changes are processed,
before they are validated and applied to the data source.
Use afterChange if you need to react after the data has been written.
This hook fires for every setDataAtRowProp() call, yours or a plugin’s – for example, the
DataProvider plugin calls it internally (with source set to 'DataProvider.revert') to roll
back an optimistic edit after a failed server update. Changes made through setDataAtCell() –
including regular cell edits, paste, cut, Delete/Backspace, the fill handle, Ctrl+Enter, a
checkbox click, and undo/redo, which apply internally via setDataAtCell() – fire
afterSetDataAtCell instead – never both for the same change.
| Param | Type | Description |
|---|---|---|
| changes | Array | An array of changes in format [[row, prop, oldValue, value], ...]. |
| [source] | string | optional String that identifies source of hook call (list of all available sources). |
afterSetSourceDataAtCell
afterSetSourceDataAtCell(changes, [source])
Fired after cell source data was changed.
Since: 8.0.0
| Param | Type | Description |
|---|---|---|
| changes | Array | An array of changes in format [[row, column, oldValue, value], ...]. |
| [source] | string | optional String that identifies source of hook call. |
afterSetTheme
afterSetTheme(themeName, firstRun)
Fired after a theme is enabled, changed, or disabled.
Since: 15.0.0
| Param | Type | Description |
|---|---|---|
| themeName | string boolean undefined | The theme name. |
| firstRun | boolean | true if it’s the initial setting of the theme, false otherwise. |
afterSheetAdded
afterSheetAdded(addedSheetDisplayName)
Fired by the Formulas plugin when a new sheet is added to the engine instance.
The Formulas plugin creates a sheet on Handsontable’s initialization (using the sheet name from
Options#formulas, or a name auto-generated by HyperFormula, e.g. Sheet1, if none was provided), so
this hook also fires once during initialization, before any user-triggered sheet additions.
Read more:
Since: 9.0.0
| Param | Type | Description |
|---|---|---|
| addedSheetDisplayName | string | The name of the added sheet. |
afterSheetRemoved
afterSheetRemoved(removedSheetDisplayName, changes)
Fired by the Formulas plugin when a sheet is removed from the engine instance.
Read more:
Since: 9.0.0
| Param | Type | Description |
|---|---|---|
| removedSheetDisplayName | string | The removed sheet name. |
| changes | Array | The values and location of applied changes. |
afterSheetRenamed
afterSheetRenamed(oldDisplayName, newDisplayName)
Fired by the Formulas plugin when a sheet in the engine instance is renamed.
Read more:
Since: 9.0.0
| Param | Type | Description |
|---|---|---|
| oldDisplayName | string | The old name of the sheet. |
| newDisplayName | string | The new name of the sheet. |
afterSheetTabAdd
afterSheetTabAdd(sheetId, name, duplicateOfId, source)
Fired by SheetsBar plugin after adding a new sheet. This hook is fired when Options#sheetsBar option is enabled.
It fires for an added sheet and for a duplicate.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| sheetId | number | The id of the added sheet. |
| name | string | The name of the added sheet. |
| duplicateOfId | number null | The id of the sheet that was copied, or null for an added sheet. |
| source | string | String that identifies source of hook call. |
afterSheetTabChange
afterSheetTabChange(oldSheetId, newSheetId, source)
Fired by SheetsBar plugin after changing the active sheet. This hook is fired when Options#sheetsBar option is enabled.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| oldSheetId | number | The id of the sheet being left. |
| newSheetId | number | The id of the sheet being activated. |
| source | string | String that identifies source of hook call. |
afterSheetTabMove
afterSheetTabMove(sheetId, finalIndex, source)
Fired by SheetsBar plugin after moving a sheet to a new tab position. This hook is fired when Options#sheetsBar option is enabled.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| sheetId | number | The id of the moved sheet. |
| finalIndex | number | The tab index the sheet was moved to. |
| source | string | String that identifies source of hook call. |
afterSheetTabRemove
afterSheetTabRemove(sheetId, source)
Fired by SheetsBar plugin after removing a sheet. This hook is fired when Options#sheetsBar option is enabled.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| sheetId | number | The id of the removed sheet. |
| source | string | String that identifies source of hook call. |
afterSheetTabRename
afterSheetTabRename(sheetId, oldName, newName, source)
Fired by SheetsBar plugin after renaming a sheet. This hook is fired when Options#sheetsBar option is enabled.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| sheetId | number | The id of the renamed sheet. |
| oldName | string | The previous name of the sheet. |
| newName | string | The new name of the sheet. |
| source | string | String that identifies source of hook call. |
afterSheetTabStateCapture
afterSheetTabStateCapture(sheetId, viewState, source)
Fired by SheetsBar plugin after capturing a sheet’s runtime view state (e.g. scroll position, selection) before switching away from it. This hook is fired when Options#sheetsBar option is enabled.
A listener cannot switch, add, remove, rename, duplicate, or move a sheet: those calls return
false (null for an add or a duplicate). A change it makes to a cell with a validator refuses
the switch, because the change would otherwise be written into the arriving sheet.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| sheetId | number | The id of the sheet the view state was captured from. |
| viewState | object | The captured view state. Its sortConfig names each column by its physical index. Its cellMeta lists the cell meta the sheet keeps, one { row, col, key, value } entry per key, where row and col are physical indexes: every key set through setCellMeta() except hidden, spanned and valid, internal keys starting with _ included, and a valid: false entry for each cell marked invalid. Its customBorders lists the borders on screen for reading only: the sheet’s borders come back with cellMeta, so a change made to that list is not applied. |
| source | string | String that identifies source of hook call. |
afterSheetTabStateRestore
afterSheetTabStateRestore(sheetId, viewState, source)
Fired by SheetsBar plugin after restoring a sheet’s runtime view state (e.g. scroll position, selection) when switching to it. This hook is fired when Options#sheetsBar option is enabled.
It fires before the switch has finished, so a listener cannot switch, add, remove, rename, duplicate,
or move a sheet: those calls return false (null for an add or a duplicate).
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| sheetId | number | The id of the sheet the view state was restored to. |
| viewState | object | The restored view state. Its sortConfig names each column by its physical index. |
| source | string | String that identifies source of hook call. |
afterSuspendExecution
afterSuspendExecution
Fired by Core#suspendExecution after it suspends the execution (the index cache updates).
batch() and batchExecution() suspend the
execution the same way, and so does Handsontable itself (for example, to size columns on a render).
The hook fires only when the execution changes from resumed to suspended: a nested call fires nothing.
When a listener throws, the execution is resumed (the beforeResumeExecution and
afterResumeExecution hooks fire) and the error reaches the caller. The hook does not fire while the
instance is being destroyed.
Since: 19.0.0
Example
<HotTable afterSuspendExecution={() => { console.log('The execution is suspended'); }}/>afterTrimRow
afterTrimRow(currentTrimConfig, destinationTrimConfig, actionPossible, stateChanged) ⇒ undefined | boolean
Fired by TrimRows plugin after trimming rows. This hook is fired when Options#trimRows option is enabled.
| Param | Type | Description |
|---|---|---|
| currentTrimConfig | Array | Current trim configuration - a list of trimmed physical row indexes. |
| destinationTrimConfig | Array | Destination trim configuration - a list of trimmed physical row indexes. |
| actionPossible | boolean | true, if all of the row indexes are withing the bounds of the table, false otherwise. |
| stateChanged | boolean | true, if the action affected any non-trimmed rows, false otherwise. |
Returns: undefined | boolean - If the callback returns false, the trimming action will not be completed.
afterUndo
afterUndo(action)
Fired by UndoRedo plugin after the undo action. Contains information about the action that is being undone. This hook is fired when Options#undo option is enabled.
| Param | Type | Description |
|---|---|---|
| action | object | The action object. Contains information about the action being undone. The actionType property of the object specifies the type of the action in a String format. (e.g. 'remove_row'). |
afterUndoStackChange
afterUndoStackChange(doneActionsBefore, doneActionsAfter)
Fired by UndoRedo plugin after changing undo stack.
Since: 8.4.0
| Param | Type | Description |
|---|---|---|
| doneActionsBefore | Array | Stack of actions which could be undone before performing new action. |
| doneActionsAfter | Array | Stack of actions which can be undone after performing new action. |
afterUnhideColumns
afterUnhideColumns(currentHideConfig, destinationHideConfig, actionPossible, stateChanged)
Fired by HiddenColumns plugin after marking the columns as not hidden. Fired only if the Options#hiddenColumns option is enabled.
| Param | Type | Description |
|---|---|---|
| currentHideConfig | Array | Current hide configuration - a list of hidden physical column indexes. |
| destinationHideConfig | Array | Destination hide configuration - a list of hidden physical column indexes. |
| actionPossible | boolean | true, if the provided column indexes are valid, false otherwise. |
| stateChanged | boolean | true, if the action affected any hidden columns, false otherwise. |
afterUnhideRows
afterUnhideRows(currentHideConfig, destinationHideConfig, actionPossible, stateChanged)
Fired by HiddenRows plugin after marking the rows as not hidden. Fired only if the Options#hiddenRows option is enabled.
| Param | Type | Description |
|---|---|---|
| currentHideConfig | Array | Current hide configuration - a list of hidden physical row indexes. |
| destinationHideConfig | Array | Destination hide configuration - a list of hidden physical row indexes. |
| actionPossible | boolean | true, if provided row indexes are valid, false otherwise. |
| stateChanged | boolean | true, if the action affected any hidden rows, false otherwise. |
afterUnlisten
afterUnlisten
Fired after the table was switched off from the listening mode. This makes the Handsontable inert for any keyboard events.
afterUnmergeCells
afterUnmergeCells(cellRange, [auto])
Fired by MergeCells plugin after unmerging the cells. This hook is fired when Options#mergeCells option is enabled.
| Param | Type | Default | Description |
|---|---|---|---|
| cellRange | CellRange | Selection cell range. | |
| [auto] | boolean | false | optional true if called automatically by the plugin. |
afterUntrimRow
afterUntrimRow(currentTrimConfig, destinationTrimConfig, actionPossible, stateChanged) ⇒ undefined | boolean
Fired by TrimRows plugin after untrimming rows. This hook is fired when Options#trimRows option is enabled.
| Param | Type | Description |
|---|---|---|
| currentTrimConfig | Array | Current trim configuration - a list of trimmed physical row indexes. |
| destinationTrimConfig | Array | Destination trim configuration - a list of trimmed physical row indexes. |
| actionPossible | boolean | true, if all of the row indexes are withing the bounds of the table, false otherwise. |
| stateChanged | boolean | true, if the action affected any trimmed rows, false otherwise. |
Returns: undefined | boolean - If the callback returns false, the untrimming action will not be completed.
afterUpdateData
afterUpdateData(sourceData, initialLoad, source)
Fired after the updateData() method
modifies Handsontable’s data.
Read more:
Since: 11.1.0
| Param | Type | Description |
|---|---|---|
| sourceData | Array | An array of arrays, or an array of objects, that contains Handsontable’s data |
| initialLoad | boolean | A flag that indicates whether the data was loaded at Handsontable’s initialization (true) or later (false) |
| source | string | The source of the call |
afterUpdateSettings
afterUpdateSettings(newSettings)
Fired after calling the updateSettings method.
A legacy fixedColumnsLeft passed to updateSettings() stays
fixedColumnsLeft in newSettings, though the grid applies it as
fixedColumnsStart.
| Param | Type | Description |
|---|---|---|
| newSettings | object | New settings object. |
afterValidate
afterValidate(isValid, value, row, prop, [source]) ⇒ undefined | boolean
A plugin hook executed after validator function, only if validator function is defined. Validation result is the first parameter. This can be used to determinate if validation passed successfully or not.
Returning false from the callback will mark the cell as invalid.
| Param | Type | Description |
|---|---|---|
| isValid | boolean | true if valid, false if not. |
| value | * | The value in question. |
| row | number null | Visual row index. For a change, the row the edited record has when the validator answers, not the row the change was made at: a sort, a move, a filter, or a row insert or removal can land while the validator runs. null when a filter or a trim took the record out of the visual rows, or a removal took it, in the meantime. |
| prop | string number | Property name or column index. For array-based data, this is the physical column index. When columns[i].data is a function, this is the visual column index. |
| [source] | string | optional String that identifies source of hook call (list of all available sources). |
Returns: undefined | boolean - If false the cell will be marked as invalid, true otherwise.
afterViewportColumnCalculatorOverride
afterViewportColumnCalculatorOverride(calc)
Fired inside the viewportColumnCalculatorOverride method. Allows modifying the row calculator parameters.
| Param | Type | Description |
|---|---|---|
| calc | object | The row calculator. |
afterViewportRowCalculatorOverride
afterViewportRowCalculatorOverride(calc)
Fired inside the viewportRowCalculatorOverride method. Allows modifying the row calculator parameters.
| Param | Type | Description |
|---|---|---|
| calc | object | The row calculator. |
afterViewRender
afterViewRender(isForced)
Fired after Handsontable’s view-rendering engine is rendered, but before redrawing the selection borders and before scroll syncing.
Note: In Handsontable 9.x and earlier, the afterViewRender hook was named afterRender.
Since: 10.0.0
| Param | Type | Description |
|---|---|---|
| isForced | boolean | If set to true, the rendering gets triggered by a change of settings, a change of data, or a logic that needs a full Handsontable render cycle. If set to false, the rendering gets triggered by scrolling or moving the selection. |
beforeAddChild
beforeAddChild(parent, element, index)
Fired by NestedRows plugin before adding a children to the NestedRows structure. This hook is fired when
Options#nestedRows option is enabled.
| Param | Type | Description |
|---|---|---|
| parent | object | The parent object. |
| element | object undefined | The element added as a child. If undefined, a blank child was added. |
| index | number undefined | The index within the parent where the new child was added. If undefined, the element was added as the last child. |
beforeAlter
beforeAlter(action, index, amount, [source], [keepEmptyRows]) ⇒ * | boolean
Fired before an alter action is applied (e.g. insert_row_above, insert_row_below, remove_row).
Return false to cancel the default alter behavior (e.g. so a plugin can handle it via server-side CRUD).
Since: 17.1.0
| Param | Type | Description |
|---|---|---|
| action | string | The alter action: 'insert_row_above', 'insert_row_below', 'remove_row', 'insert_col_start', 'insert_col_end', 'remove_col'. |
| index | number Array | Visual row/column index, or for remove actions an array of [[index, amount], ...]. |
| amount | number | Number of rows/columns to insert or remove (default 1). |
| [source] | string | optional Source of the alter call (e.g. 'ContextMenu.rowAbove'). |
| [keepEmptyRows] | boolean | optional Whether to keep empty rows (remove_row only). |
Returns: * | boolean - Return false to cancel the alter; the table will not be modified locally.
beforeAsyncValueResolve
beforeAsyncValueResolve(value, physicalRow, prop, rowId) ⇒ *
Fired by the AsyncValues plugin before it passes a resolved value to the grid. Return a value
to write it instead, or false to discard the value: the cell keeps its previous value, and the
request ends as canceled with the 'vetoed' reason. Because false discards, a listener cannot
replace a value with a literal false; a resolved false that no listener changes is written.
The callbacks run one after another, and each one receives the previous callback’s result as its first
argument when that result is not undefined. So a callback that keeps the value returns undefined, and
a callback that checks for an earlier discard compares its first argument with false. Every callback of
a flush runs before any value is written. A callback that throws fails its own cell with the error it
threw. The other cells are written, and then the error is reported as an uncaught error.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| value | * | The resolved value. |
| physicalRow | number | Physical row index of the cell. |
| prop | string number | The property of the cell’s column. |
| rowId | * | The id of the cell’s row (see the rowId option), or null. |
Returns: * - The value to write, false to discard it, or undefined to keep it.
beforeAsyncValueStart
beforeAsyncValueStart(physicalRow, prop, rowId) ⇒ boolean | undefined
Fired by the AsyncValues plugin before it starts an asynchronous computation of a cell’s
value. Return false to skip the request: the cell does not become pending, its source is not
called, and the request’s promise resolves as canceled with the 'vetoed' reason. No
afterAsyncValueCancel hook fires for a skipped request, because nothing was pending.
The callbacks run one after another, and each one receives the previous callback’s result as its first
argument instead of the row index when that result is not undefined. So a callback that only allows a
request returns undefined, never true, and a callback that checks the decision of an earlier one
compares its first argument with false. A callback that throws skips its cell’s request, and the error
is thrown again once the call has started its other cells.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| physicalRow | number | Physical row index of the cell. |
| prop | string number | The property of the cell’s column. |
| rowId | * | The id of the cell’s row (see the rowId option), or null. |
Returns: boolean | undefined - Return false to skip the request.
beforeAutofill
beforeAutofill(selectionData, sourceRange, targetRange, direction) ⇒ boolean | Array<Array>
Fired by Autofill plugin before populating the data in the autofill feature. This hook is fired when Options#fillHandle option is enabled.
Several callbacks can return a result for this hook, and the last callback that returns a value decides
the outcome. Global hooks (added with Handsontable.hooks.add()) run first, then the hooks of the
instance (the beforeAutofill option and addHook()). Within each group, callbacks run in ascending
orderIndex order, and callbacks with the same orderIndex run in the order they were registered. Each
callback receives the previous result as its first argument. A callback that returns a value replaces
the earlier results. A callback that returns undefined keeps them. Returning false doesn’t stop the
callbacks that run later, so a later callback can still return data and the autofill goes ahead.
When the Formulas plugin is enabled, it registers its own beforeAutofill callback with the
default orderIndex of 0. That callback ignores the results of earlier callbacks. It returns false when
the engine can’t set the target cells, or the filled data with the formulas adjusted. Your callback
overrides the plugin’s only if it runs after it. The beforeAutofill option set at initialization and a
callback added with addHook() after the plugin is enabled run after it. A global hook, a callback added
with addHook() before the plugin is enabled, and the beforeAutofill option when you enable the plugin
later with updateSettings() run before it and are overridden. Disabling and re-enabling the plugin
registers its callback again, after your callbacks that have an orderIndex of 0. To always override the
plugin, add your callback with addHook('beforeAutofill', callback, 1): an orderIndex greater than 0
runs after the plugin’s callback, whenever you add it.
| Param | Type | Description |
|---|---|---|
| selectionData | Array<Array> boolean | Data the autofill operation will start from. A callback that runs after another callback that returned a value receives that value instead (for example, false). |
| sourceRange | CellRange | The range values will be filled from. |
| targetRange | CellRange | The range new values will be filled into. |
| direction | string | Declares the direction of the autofill. Possible values: up, down, left, right. |
Returns: boolean | Array<Array> - If the final result is false, the operation is canceled. If the final result is
an array of arrays, the returned data
will be passed into populateFromArray instead of the default autofill
algorithm’s result.
beforeBeginEditing
beforeBeginEditing(row, column, initialValue, event, fullEditMode) ⇒ boolean | undefined
Fired before the editor is opened and rendered.
Since: 14.2.0
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index of the edited cell. |
| column | number | Visual column index of the edited cell. |
| initialValue | * | The initial editor value. |
| event | MouseEvent KeyboardEvent | The event which was responsible for opening the editor. |
| fullEditMode | boolean | true if the editor is opened in full edit mode, false otherwise. Editor opened in full edit mode does not close after pressing Arrow keys. |
Returns: boolean | undefined - If the callback returns false, the editor won’t be opened after
the mouse double click or after pressing the Enter key. Returning undefined (or other value
than boolean) will result in default behavior, which disallows opening an editor for non-contiguous
selection (while pressing Ctrl/Cmd) and for multiple selected cells (while pressing Shift).
Returning true removes those restrictions.
beforeCellAlignment
beforeCellAlignment(stateBefore, range, type, alignmentClass)
Fired before aligning the cell contents.
| Param | Type | Description |
|---|---|---|
| stateBefore | object | An object where each key is a visual row index and each value is an array indexed by visual column. Each entry holds the alignment class names set in the cell’s className (htLeft, htCenter, htRight, htJustify, htTop, htMiddle, htBottom), separated by a space. Other class names are left out, and so are the class names a renderer adds, such as the htRight of a numeric cell. The entry is undefined when the className holds no alignment class name. |
| range | Array<CellRange> | An array of CellRange coordinates where the alignment will be applied. |
| type | string | Type of the alignment - either horizontal or vertical. |
| alignmentClass | string | String defining the alignment class added to the cell. Possible values: htLeft , htCenter, htRight, htJustify, htTop, htMiddle, htBottom. |
beforeChange
beforeChange(changes, [source]) ⇒ undefined | boolean
Fired before one or more cells are changed.
Use this hook to silently alter the user’s changes before Handsontable re-renders.
To ignore the user’s changes, use a nullified array or return false.
This hook doesn’t run when the entire data source is replaced through
loadData(), updateData(), or
updateSettings() with the data option. To intercept these
replacements, use beforeLoadData or
beforeUpdateData.
Example
// to alter a single change, overwrite the desired value with `changes[i][3]`<HotTable beforeChange={(changes, source) => { // [[row, prop, oldVal, newVal], ...] changes[0][3] = 10; }}/>
// to ignore a single change, set `changes[i]` to `null`// or remove `changes[i]` from the array, by using changes.splice(i, 1).<HotTable beforeChange={(changes, source) => { // [[row, prop, oldVal, newVal], ...] changes[0] = null; }}/>
// to ignore all changes, return `false`// or set the array's length to 0 (`changes.length = 0`)<HotTable beforeChange={(changes, source) => { // [[row, prop, oldVal, newVal], ...] return false; }}/>| Param | Type | Description |
|---|---|---|
| changes | Array<Array> | 2D array containing information about each of the edited cells [[row, prop, oldVal, newVal], ...]. row is a visual row index. prop is a property name, a column index, or – when columns[].data is a function – the column accessor function. To resolve a visual column index from prop, call propToCol(). Unlike beforeValidate and afterValidate, this hook passes the accessor function as prop so the grid can write data back. Read more: Binding to data: Identify changed columns in hooks. |
| [source] | string | optional String that identifies source of hook call (list of all available sources). |
Returns: undefined | boolean - If false all changes were canceled, true otherwise.
beforeChangeRender
beforeChangeRender(changes, [source])
Fired right before rendering the changes.
row is a visual row index. For a change that waited for a validator, it is
the visual row the changed record has when the value lands, or null when a filter or another trimming feature
took the record out of the visual space while the change waited (see Hooks#afterChange). To find that
record, pass the change to getPhysicalRowOfChange().
Breaking change (19.0): row can be null, and the type of changes is AppliedCellChange[] instead of
CellChange[].
| Param | Type | Description |
|---|---|---|
| changes | Array<Array> | Array in form of [row, prop, oldValue, newValue]. |
| [source] | string | optional String that identifies source of hook call (list of all available sources). |
beforeColumnCollapse
beforeColumnCollapse(currentCollapsedColumns, destinationCollapsedColumns, collapsePossible) ⇒ undefined | boolean
Fired by CollapsibleColumns plugin before columns collapse. This hook is fired when Options#collapsibleColumns option is enabled.
Since: 8.0.0
| Param | Type | Description |
|---|---|---|
| currentCollapsedColumns | Array | Current collapsible configuration - a list of collapsible physical column indexes. |
| destinationCollapsedColumns | Array | Destination collapsible configuration - a list of collapsible physical column indexes. |
| collapsePossible | boolean | true, if all of the column indexes are withing the bounds of the collapsed sections, false otherwise. |
Returns: undefined | boolean - If the callback returns false, the collapsing action will not be completed.
beforeColumnExpand
beforeColumnExpand(currentCollapsedColumns, destinationCollapsedColumns, expandPossible) ⇒ undefined | boolean
Fired by CollapsibleColumns plugin before columns expand. This hook is fired when Options#collapsibleColumns option is enabled.
Since: 8.0.0
| Param | Type | Description |
|---|---|---|
| currentCollapsedColumns | Array | Current collapsible configuration - a list of collapsible physical column indexes. |
| destinationCollapsedColumns | Array | Destination collapsible configuration - a list of collapsible physical column indexes. |
| expandPossible | boolean | true, if all of the column indexes are withing the bounds of the collapsed sections, false otherwise. |
Returns: undefined | boolean - If the callback returns false, the expanding action will not be completed.
beforeColumnFreeze
beforeColumnFreeze(column, freezePerformed) ⇒ boolean | undefined
Fired by the ManualColumnFreeze plugin, before freezing a column.
Since: 12.1.0
| Param | Type | Description |
|---|---|---|
| column | number | The visual index of the column that is going to freeze. |
| freezePerformed | boolean | If true: the column is going to freeze. If false: the column is not going to freeze (which might happen if the column is already frozen). |
Returns: boolean | undefined - If false: the column is not going to freeze, and the afterColumnFreeze hook won’t fire.
beforeColumnMove
beforeColumnMove(movedColumns, finalIndex, dropIndex, movePossible) ⇒ undefined | boolean
Fired by ManualColumnMove plugin before change order of the visual indexes. This hook is fired when Options#manualColumnMove option is enabled.
The hook also fires when the move leaves the order unchanged, for example when you drop a column back where it
was. To tell such a move apart, use the afterColumnMove hook and check its orderChanged parameter.
| Param | Type | Description |
|---|---|---|
| movedColumns | Array | Array of visual column indexes to be moved. |
| finalIndex | number | Visual column index, being a start index for the moved columns. Points to where the elements will be placed after the moving action. To check visualization of final index please take a look at documentation. |
| dropIndex | number undefined | Visual column index, being a drop index for the moved columns. Points to where we are going to drop the moved elements. To check visualization of drop index please take a look at documentation. It’s undefined when dragColumns function wasn’t called. |
| movePossible | boolean | Indicates if it’s possible to move rows to the desired position. |
Returns: undefined | boolean - If false the column will not be moved, true otherwise.
beforeColumnResize
beforeColumnResize(newSize, column, isDoubleClick) ⇒ number | false | undefined
Fired by ManualColumnResize plugin before rendering the table with modified column sizes. This hook is fired when Options#manualColumnResize option is enabled.
| Param | Type | Description |
|---|---|---|
| newSize | number | Calculated new column width. It excludes the room that the hidden-column indicator adds to a column next to a hidden column, as the width taken by setManualSize() does. |
| column | number | Visual index of the resized column. |
| isDoubleClick | boolean | Flag that determines whether there was a double-click. |
Returns: number | false | undefined - Returns a new column size, false to cancel the resize, or undefined to keep the size set by the drag or auto-calculation.
beforeColumnSort
beforeColumnSort(currentSortConfig, destinationSortConfigs, sortPossible) ⇒ boolean | undefined
Fired by ColumnSorting and MultiColumnSorting plugins before sorting the column. If you return false value inside callback for hook, then sorting
will be not applied by the Handsontable (useful for server-side sorting).
This hook is fired when Options#columnSorting or Options#multiColumnSorting option is enabled.
Each sort configuration is an array with one { column, sortOrder } object for each sorted column, where
column is a visual column index and sortOrder is 'asc' or 'desc'. An empty array means that no
column is sorted. With Options#multiColumnSorting, the objects follow the sort priority.
Example
// the grid is sorted by the first column, and the user clicks the header of the third columnnew Handsontable(element, { columnSorting: true, beforeColumnSort: (currentSortConfig, destinationSortConfigs) => { // currentSortConfig: [{ column: 0, sortOrder: 'asc' }] // destinationSortConfigs: [{ column: 2, sortOrder: 'asc' }] }});| Param | Type | Description |
|---|---|---|
| currentSortConfig | Array | Sort configuration from before the sort (for all sorted columns). |
| destinationSortConfigs | Array | Sort configuration that the sort is about to apply (for all sorted columns). |
| sortPossible | boolean | Indicates if it’s possible to sort the table with the provided configuration. |
Returns: boolean | undefined - If false the column will not be sorted, true otherwise.
beforeColumnUnfreeze
beforeColumnUnfreeze(column, unfreezePerformed, finalIndex) ⇒ boolean | undefined
Fired by the ManualColumnFreeze plugin, before unfreezing a column.
Since: 12.1.0
| Param | Type | Description |
|---|---|---|
| column | number | The visual index of the column that is going to unfreeze. |
| unfreezePerformed | boolean | If true: the column is going to unfreeze. If false: the column is not going to unfreeze (which might happen if the column is already unfrozen). |
| finalIndex | number | The visual index the column is going to be moved to (available since 19.0.0). It depends on the restoreColumnPosition setting of the manualColumnFreeze option. Equal to column when unfreezePerformed is false. |
Returns: boolean | undefined - If false: the column is not going to unfreeze, and the afterColumnUnfreeze hook won’t fire.
beforeColumnWrap
beforeColumnWrap(isWrapEnabled, newCoords, isFlipped)
When the focus position is moved to the next or previous column caused by the Options#autoWrapCol option the hook is triggered.
Since: 14.0.0
| Param | Type | Description |
|---|---|---|
| isWrapEnabled | boolean | Tells whether the column wrapping is going to happen. There may be situations where the option does not work even though it is enabled. This is due to the priority of other options that may block the feature. For example, when the Options#minSpareRows is defined, the Options#autoWrapCol option is not checked. Thus, column wrapping is off. |
| newCoords | CellCoords | The new focus position. It is an object with keys row and col, where a value of -1 indicates a header. |
| isFlipped | boolean | true if the column index was flipped, false otherwise. Flipped index means that the user reached the last column and the focus is moved to the first column or vice versa. |
beforeCompositionStart
beforeCompositionStart(event)
Hook fired after compositionstart event is handled.
Since: 15.3.0
| Param | Type | Description |
|---|---|---|
| event | Event | A native composition event object. |
beforeContextMenuSetItems
beforeContextMenuSetItems(menuItems)
Fired each time user opens ContextMenu plugin before setting up the context menu’s items but after filtering these options by
user (contextMenu option). This hook can by helpful to determine if user use specified menu item or to set up
one of the menu item to by always visible.
| Param | Type | Description |
|---|---|---|
| menuItems | Array<object> | An array of objects containing information about to generated context menu items. |
beforeContextMenuShow
beforeContextMenuShow(context)
Fired by ContextMenu plugin before opening the context menu. This hook is fired when Options#contextMenu option is enabled.
| Param | Type | Description |
|---|---|---|
| context | object | The ContextMenu instance. |
beforeCopy
beforeCopy(data, coords, copiedHeadersCount) ⇒ *
Fired before values are copied to the clipboard.
Changes the callback makes to data also apply to the data that a paste into another Handsontable grid reads.
Example
// To disregard a single row, remove it from array using data.splice(i, 1)....<HotTable beforeCopy={(data, coords) => { // data -> [[1, 2, 3], [4, 5, 6]] data.splice(0, 1); // data -> [[4, 5, 6]] // coords -> [{startRow: 0, startCol: 0, endRow: 1, endCol: 2}] }}/>...
// To cancel copying, return false from the callback....<HotTable beforeCopy={(data, coords) => { return false; }}/>...| Param | Type | Description |
|---|---|---|
| data | Array<Array> | An array of arrays which contains data to copied. |
| coords | Array<object> | An array of objects with ranges of the visual indexes (startRow, startCol, endRow, endCol) which will copied. |
| copiedHeadersCount | Object | (Since 12.3.0) The number of copied column headers. |
Returns: * - If returns false then copying is canceled.
beforeCreateCol
beforeCreateCol(index, amount, [source]) ⇒ *
Fired before created a new column.
Example
// Return `false` to cancel column inserting.<HotTable beforeCreateCol={(data, coords) => { return false; }}/>| Param | Type | Description |
|---|---|---|
| index | number | Represents the visual index of first newly created column in the data source array. |
| amount | number | Number of newly created columns in the data source array. |
| [source] | string | optional String that identifies source of hook call (list of all available sources). For example, 'ContextMenu.columnLeft' or 'ContextMenu.columnRight' when the user inserts a column from the context menu, and 'auto' when the minCols or minSpareCols option adds columns. These are not the context menu item keys (col_left, col_right). |
Returns: * - If false then creating columns is canceled.
beforeCreateRow
beforeCreateRow(index, amount, [source]) ⇒ * | boolean
Fired before a new row is created.
| Param | Type | Description |
|---|---|---|
| index | number | Represents the visual index at which new row(s) are about to be inserted. Note that the actual visual index of the inserted row(s) may differ - use the afterCreateRow hook to get the final position. |
| amount | number | Number of rows to be created. |
| [source] | string | optional String that identifies source of hook call (list of all available sources). For example, 'ContextMenu.rowAbove' or 'ContextMenu.rowBelow' when the user inserts a row from the context menu, and 'auto' when the minRows or minSpareRows option adds rows. These are not the context menu item keys (row_above, row_below). |
Returns: * | boolean - If false is returned the action is canceled.
beforeCut
beforeCut(data, coords) ⇒ *
Fired by CopyPaste plugin before copying the values to the clipboard and before clearing values of the selected cells. This hook is fired when Options#copyPaste option is enabled.
Changes the callback makes to data also apply to the data that a paste into another Handsontable grid reads.
Example
// To disregard a single row, remove it from the array using data.splice(i, 1).<HotTable beforeCut={(data, coords) => { // data -> [[1, 2, 3], [4, 5, 6]] data.splice(0, 1); // data -> [[4, 5, 6]] // coords -> [{startRow: 0, startCol: 0, endRow: 1, endCol: 2}] }}/>// To cancel a cutting action, just return `false`.<HotTable beforeCut={(data, coords) => { return false; }}/>| Param | Type | Description |
|---|---|---|
| data | Array<Array> | An array of arrays which contains data to cut. |
| coords | Array<object> | An array of objects with ranges of the visual indexes (startRow, startCol, endRow, endCol) which will be cut out. |
Returns: * - If returns false then operation of the cutting out is canceled.
beforeDataProviderFetch
beforeDataProviderFetch(queryParameters) ⇒ * | boolean
Fired before the dataProvider fetches data. Return false to cancel the fetch.
A canceled fetch leaves a fetch that is already running alone: that fetch still loads its rows. The
loading state of the emptyDataState overlay is updated after a
cancel, so the overlay shows loading only while a fetch still runs. The fetch starts only after every
listener returns, so a fetch a listener starts with fetchData() from inside this hook starts first, and the
fetch the hook was fired for then replaces it, unless the listener returns false.
Since: 17.1.0
| Param | Type | Description |
|---|---|---|
| queryParameters | object | Current query parameters: { page, pageSize, sort, filters }. May include skipLoading when the fetch was triggered internally (for example after column sort or CRUD); not sent to fetchRows. |
Returns: * | boolean - Return false to cancel the fetch; otherwise the fetch proceeds.
beforeDetachChild
beforeDetachChild(parent, element, [source])
Fired by NestedRows plugin before detaching a child from its parent. This hook is fired when Options#nestedRows option is enabled.
| Param | Type | Description |
|---|---|---|
| parent | object | An object representing the parent from which the element is to be detached. |
| element | object | The detached element. |
| [source] | string | optional String that identifies source of hook call. It is 'NestedRows' for a detach made through the plugin, and 'UndoRedo.redo' when the UndoRedo plugin replays one (list of all available sources). |
beforeDialogHide
beforeDialogHide
Fired by Dialog plugin before hiding the dialog. This hook is fired when Options#dialog option is enabled.
Since: 16.1.0
beforeDialogShow
beforeDialogShow
Fired by Dialog plugin before showing the dialog. This hook is fired when Options#dialog option is enabled.
Since: 16.1.0
beforeDrawBorders
beforeDrawBorders(corners, borderClassName)
Fired before drawing the borders.
| Param | Type | Description |
|---|---|---|
| corners | Array | Array specifying the current selection borders. |
| borderClassName | string | Specifies the border class name. |
beforeDropdownMenuSetItems
beforeDropdownMenuSetItems(menuItems)
Fired by DropdownMenu plugin before setting up the dropdown menu’s items but after filtering these options
by user (dropdownMenu option). This hook can by helpful to determine if user use specified menu item or to set
up one of the menu item to by always visible.
| Param | Type | Description |
|---|---|---|
| menuItems | Array<object> | An array of objects containing information about to generated dropdown menu items. |
beforeDropdownMenuShow
beforeDropdownMenuShow(dropdownMenu)
Fired by DropdownMenu plugin before opening the dropdown menu. This hook is fired when Options#dropdownMenu option is enabled.
| Param | Type | Description |
|---|---|---|
| dropdownMenu | DropdownMenu | The DropdownMenu instance. |
beforeEmptyDataStateHide
beforeEmptyDataStateHide
Fired by EmptyDataState plugin before hiding the empty data state overlay. This hook is fired when Options#emptyDataState option is enabled.
Since: 16.2.0
beforeEmptyDataStateShow
beforeEmptyDataStateShow
Fired by EmptyDataState plugin before showing the empty data state overlay. This hook is fired when Options#emptyDataState option is enabled.
Since: 16.2.0
beforeFilter
beforeFilter(conditionsStack, previousConditionsStack) ⇒ boolean
Fired by the Filters plugin,
before a column filter gets applied.
beforeFilter takes two arguments: conditionsStack and previousConditionsStack, both are
arrays of objects.
Each object represents one of your column filters, and consists of the following properties:
| Property | Possible values | Description |
|---|---|---|
column | Number | A physical index of the column to which the filter will be applied. |
conditions | Array of objects | Each object represents one condition. For details, see addCondition(). |
operation | 'conjunction' | 'disjunction' | 'disjunctionWithExtraCondition' | An operation to perform on your set of conditions. For details, see addCondition(). |
An example of the format of the conditionsStack argument:
[ { column: 2, conditions: [ {name: 'begins_with', args: [['S']]} ], operation: 'conjunction' }, { column: 4, conditions: [ {name: 'not_empty', args: []} ], operation: 'conjunction' },]To perform server-side filtering (i.e., to not apply filtering to Handsontable’s UI),
set beforeFilter to return false:
new Handsontable(document.getElementById('example'), { beforeFilter: (conditionsStack) => { return false; }});Read more:
- Guides: Column filter
- Hooks:
afterFilter - Options:
filters - Plugins:
Filters– Plugin methods:addCondition()
| Param | Type | Description |
|---|---|---|
| conditionsStack | Array<object> | An array of objects with your column filters. |
| previousConditionsStack | Array<object> null | An array of objects with your previous column filters. It can also be null if there was no previous filters applied or the conditions did not change between performing the filter action. |
Returns: boolean - To perform server-side filtering (i.e., to not apply filtering to Handsontable’s UI), return false.
beforeFreezeChange
beforeFreezeChange(edge, newCount, oldCount, source) ⇒ boolean | undefined
Fired by FreezeBar plugin before the number of frozen rows or columns changes. Return false to cancel
the change. This hook is fired when the Options#freezeBar option is enabled.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| edge | 'top' 'bottom' 'start' 'end' | The edge of the frozen area. start and end follow the layout direction. |
| newCount | number | The new number of frozen rows or columns on that edge. |
| oldCount | number | The current number of frozen rows or columns on that edge. |
| source | 'drag' 'keyboard' 'api' | What requested the change. |
Returns: boolean | undefined - If false is returned, the change is canceled.
beforeGetCellMeta
beforeGetCellMeta(row, column, cellProperties)
Fired before getting cell settings.
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
| column | number | Visual column index. |
| cellProperties | object | Object containing the cell’s properties. |
beforeHeaderChange
beforeHeaderChange(axis, visualIndex, newValue, oldValue) ⇒ boolean | undefined
Fired by the EditableHeaders plugin before a column or row header is renamed.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| axis | string | 'column' for a column header, 'row' for a row header. |
| visualIndex | number | The visual index of the column or row. |
| newValue | string | The header value about to be set. |
| oldValue | * | The header value shown before the change. |
Returns: boolean | undefined - If false: the header is not renamed, and the afterHeaderChange hook won’t fire.
beforeHeightChange
beforeHeightChange(height) ⇒ number | string
Fired before the height of the table is changed.
Since: 16.1.0
| Param | Type | Description |
|---|---|---|
| height | number string | Table height. |
Returns: number | string - Modified table height.
beforeHideColumns
beforeHideColumns(currentHideConfig, destinationHideConfig, actionPossible) ⇒ undefined | boolean
Fired by HiddenColumns plugin before marking the columns as hidden. Fired only if the Options#hiddenColumns option is enabled.
Returning false in the callback will prevent the hiding action from completing.
| Param | Type | Description |
|---|---|---|
| currentHideConfig | Array | Current hide configuration - a list of hidden physical column indexes. |
| destinationHideConfig | Array | Destination hide configuration - a list of hidden physical column indexes. |
| actionPossible | boolean | true, if the provided column indexes are valid, false otherwise. |
Returns: undefined | boolean - If the callback returns false, the hiding action will not be completed.
beforeHideRows
beforeHideRows(currentHideConfig, destinationHideConfig, actionPossible) ⇒ undefined | boolean
Fired by HiddenRows plugin before marking the rows as hidden. Fired only if the Options#hiddenRows option is enabled.
Returning false in the callback will prevent the hiding action from completing.
| Param | Type | Description |
|---|---|---|
| currentHideConfig | Array | Current hide configuration - a list of hidden physical row indexes. |
| destinationHideConfig | Array | Destination hide configuration - a list of hidden physical row indexes. |
| actionPossible | boolean | true, if provided row indexes are valid, false otherwise. |
Returns: undefined | boolean - If the callback returns false, the hiding action will not be completed.
beforeHighlightingColumnHeader
beforeHighlightingColumnHeader(column, headerLevel, highlightMeta) ⇒ number | undefined
Allows modify the visual column index that is used to retrieve the column header element (TH) before it’s highlighted (proper CSS class names are added). Modifying the visual column index allows building a custom implementation of the nested headers feature or other features that require highlighting other DOM elements than that the rendering engine, by default, would have highlighted.
Since: 8.4.0
| Param | Type | Description |
|---|---|---|
| column | number | Visual column index. |
| headerLevel | number | Row header level (0 = most distant to the table). |
| highlightMeta | object | An object that contains additional information about processed selection. |
beforeHighlightingRowHeader
beforeHighlightingRowHeader(row, headerLevel, highlightMeta) ⇒ number | undefined
Allows modify the visual row index that is used to retrieve the row header element (TH) before it’s highlighted (proper CSS class names are added). Modifying the visual row index allows building a custom implementation of the nested headers feature or other features that require highlighting other DOM elements than that the rendering engine, by default, would have highlighted.
Since: 8.4.0
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
| headerLevel | number | Column header level (0 = most distant to the table). |
| highlightMeta | object | An object that contains additional information about processed selection. |
beforeImport
beforeImport(result, format) ⇒ boolean | undefined
Fired by the ImportFile plugin after a workbook was read and mapped, and before the
result is applied to the grid. Mutating result changes what gets applied. Not fired for an
import with apply: false, for one that a newer import replaced, or for one the plugin was
disabled during. The dropped-features warning is already printed by then.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| result | ImportResult | The ImportFile result about to be applied. |
| format | string | The import format, e.g. 'xlsx'. |
Returns: boolean | undefined - If false, the result is not applied. The import promise still resolves with it.
beforeInit
beforeInit
Fired before the Handsontable instance is initiated.
At this point the grid is only partly built. Your settings are already readable through
getSettings(), but the data is not loaded and the table is not
rendered. Calling a method that reads the data, such as
countRows() or getData(), throws.
hot.view is still undefined, so reading it gives undefined and calling a method on it
throws. Use this hook to prepare your own state, and use
afterInit to work with the grid.
Where the callback runs depends on how you register it. A callback passed in the settings object
runs after the plugins are initialized. A callback registered globally with
Handsontable.hooks.add('beforeInit', callback), or with a negative orderIndex, runs before
them.
The hook fires once per instance creation. React’s StrictMode mounts a component twice in
development, so a grid created there fires it twice.
beforeInitWalkontable
beforeInitWalkontable(walkontableConfig)
Fired before the Walkontable instance is initiated.
| Param | Type | Description |
|---|---|---|
| walkontableConfig | object | Walkontable configuration object. |
beforeKeyDown
beforeKeyDown(event)
Hook fired before keydown event is handled. It can be used to stop default key bindings.
Note: To prevent default behavior you need to call false in your beforeKeyDown handler.
| Param | Type | Description |
|---|---|---|
| event | Event | Original DOM event. |
beforeLanguageChange
beforeLanguageChange(languageCode)
Fired before successful change of language (when proper language code was set).
Since: 0.35.0
| Param | Type | Description |
|---|---|---|
| languageCode | string | New language code. |
beforeLoadData
beforeLoadData(sourceData, initialLoad, source) ⇒ Array
Fired before Handsontable’s data
gets modified by the loadData() method
or the updateSettings() method.
Read more:
Since: 8.0.0
| Param | Type | Description |
|---|---|---|
| sourceData | Array | An array of arrays, or an array of objects, that contains Handsontable’s data |
| initialLoad | boolean | A flag that indicates whether the data was loaded at Handsontable’s initialization (true) or later (false) |
| source | string | The source of the call |
Returns: Array - The returned array will be used as Handsontable’s new dataset.
beforeLoadingHide
beforeLoadingHide ⇒ boolean | undefined
Fired by Loading plugin before hiding the loading indicator. This hook is fired when Options#loading option is enabled.
It fires only for a hide that Loading#hide makes. A hide made through the Dialog plugin (Dialog#hide, the Escape key on a closable dialog, or a dialog shown over the loading indicator) cannot be skipped, so this hook does not fire for it, while Hooks#afterLoadingHide does.
Since: 16.1.0
Returns: boolean | undefined - If returns false, the action will be skipped.
beforeLoadingShow
beforeLoadingShow ⇒ boolean | undefined
Fired by Loading plugin before showing the loading indicator. This hook is fired when Options#loading
option is enabled. The callback can return false to prevent the loading indicator from being shown.
Since: 16.1.0
Returns: boolean | undefined - If returns false, the action will be skipped.
beforeMergeCells
beforeMergeCells(cellRange, [auto])
Fired by MergeCells plugin before cell merging. This hook is fired when Options#mergeCells option is enabled.
The hook is fired only for a merge that the plugin applies. A merge that the plugin refuses – for example, one that overlaps an existing merged cell – doesn’t fire it. The plugin checks for the overlap before it fires the hook, so a listener can’t make room for a merge by unmerging the merged cell it overlaps.
| Param | Type | Default | Description |
|---|---|---|---|
| cellRange | CellRange | Selection cell range. | |
| [auto] | boolean | false | optional true if called automatically by the plugin. |
beforeMoveCells
beforeMoveCells(sourceRange, targetTopLeft, isCopy) ⇒ void | boolean
Fired before a moveCells drag relocates a selection. Return false to cancel the move. To let
the move through, return nothing, or the sourceRange the listener received. Any other value,
true included, cancels the move too.
Since: 18.1.0
| Param | Type | Description |
|---|---|---|
| sourceRange | CellRange | The range being moved. |
| targetTopLeft | CellCoords | The top-left target cell. |
| isCopy | boolean | true when copying (Ctrl held) instead of moving. |
beforeNotificationHide
beforeNotificationHide(id) ⇒ boolean | undefined
Fired by Notification plugin before a toast is hidden. Return false to keep it visible.
Timed toasts keep their auto-dismiss countdown; if the hide was triggered because the countdown
reached zero, the countdown restarts from the configured duration.
Since: 17.1.0
| Param | Type | Description |
|---|---|---|
| id | string | Toast id. |
Returns: boolean | undefined - If returns false, the toast stays visible.
beforeNotificationShow
beforeNotificationShow(options) ⇒ boolean | undefined
Fired by Notification plugin before a toast is shown or enqueued. This hook is fired when Options#notification
option is enabled. Return false to cancel Notification#showMessage (no id returned, nothing enqueued).
Queued toasts already passed this hook once when Notification#showMessage ran; it is not fired again when a slot opens.
Since: 17.1.0
| Param | Type | Description |
|---|---|---|
| options | object | Normalized toast options including id, variant, message, duration, position, closable, and actions. |
Returns: boolean | undefined - If returns false, the toast is not shown and not queued.
beforeOnCellContextMenu
beforeOnCellContextMenu(event, coords, TD)
Fired after the user clicked a cell, but before all the calculations related with it.
Since: 4.1.0
| Param | Type | Description |
|---|---|---|
| event | Event | The contextmenu event object. |
| coords | CellCoords | Cell coords object containing the visual coordinates of the clicked cell. |
| TD | HTMLTableCellElement | Cell’s TD (or TH) element. |
beforeOnCellMouseDown
beforeOnCellMouseDown(event, coords, TD, controller)
Fired after the user clicked a cell, but before all the calculations related with it.
| Param | Type | Description |
|---|---|---|
| event | Event | The mousedown event object. |
| coords | CellCoords | Cell coords object containing the visual coordinates of the clicked cell. |
| TD | HTMLTableCellElement | Cell’s TD (or TH) element. |
| controller | object | An object with properties row, column and cell. Each property contains a boolean value that allows or disallows changing the selection for that particular area. |
beforeOnCellMouseOut
beforeOnCellMouseOut(event, coords, TD)
Fired after the user moved cursor out from a cell, but before all the calculations related with it.
| Param | Type | Description |
|---|---|---|
| event | Event | The mouseout event object. |
| coords | CellCoords | CellCoords object containing the visual coordinates of the leaved cell. |
| TD | HTMLTableCellElement | Cell’s TD (or TH) element. |
beforeOnCellMouseOver
beforeOnCellMouseOver(event, coords, TD, controller)
Fired after the user moved cursor over a cell, but before all the calculations related with it.
| Param | Type | Description |
|---|---|---|
| event | Event | The mouseover event object. |
| coords | CellCoords | CellCoords object containing the visual coordinates of the clicked cell. |
| TD | HTMLTableCellElement | Cell’s TD (or TH) element. |
| controller | object | An object with properties row, column and cell. Each property contains a boolean value that allows or disallows changing the selection for that particular area. |
beforeOnCellMouseOverOutside
beforeOnCellMouseOverOutside(event, coords, TD, controller)
Fired when the mouse cursor moves outside the visible viewport while a mouse button is held down
(e.g. during a drag-to-scroll operation), before selection changes are applied. Use the controller
object to suppress row, column, or cell selection changes for this tick.
Since: 17.2.0
| Param | Type | Description |
|---|---|---|
| event | Event | mousemove event object. |
| coords | CellCoords | Visual coordinates of the nearest viewport-edge cell. |
| TD | HTMLTableCellElement | Cell’s TD (or TH) element. |
| controller | object | An object with properties row, column and cell. Each property contains a boolean value that allows or disallows changing the selection for that particular area. |
beforeOnCellMouseUp
beforeOnCellMouseUp(event, coords, TD)
Fired after the user clicked a cell.
| Param | Type | Description |
|---|---|---|
| event | Event | The mouseup event object. |
| coords | CellCoords | Cell coords object containing the visual coordinates of the clicked cell. |
| TD | HTMLTableCellElement | Cell’s TD (or TH) element. |
beforePageChange
beforePageChange(oldPage, newPage) ⇒ * | boolean
Fired by Pagination plugin before changing the page. This hook is fired when Options#pagination option is enabled.
Since: 16.1.0
| Param | Type | Description |
|---|---|---|
| oldPage | number | The old page number. |
| newPage | number | The new page number. |
Returns: * | boolean - If false is returned the action is canceled.
beforePageSizeChange
beforePageSizeChange(oldPageSize, newPageSize) ⇒ * | boolean
Fired by Pagination plugin before changing the page size. This hook is fired when Options#pagination option is enabled.
Since: 16.1.0
| Param | Type | Description |
|---|---|---|
| oldPageSize | number 'auto' | The old page size. |
| newPageSize | number 'auto' | The new page size. |
Returns: * | boolean - If false is returned the action is canceled.
beforePaste
beforePaste(data, coords) ⇒ *
Fired by CopyPaste plugin before values are pasted into table. This hook is fired when Options#copyPaste option is enabled.
Example
// To disregard a single row, remove it from array using data.splice(i, 1).<HotTable beforePaste={(data, coords) => { // data -> [[1, 2, 3], [4, 5, 6]] data.splice(0, 1); // data -> [[4, 5, 6]] // coords -> [{startRow: 0, startCol: 0, endRow: 1, endCol: 2}] }}/>// To cancel pasting, return false from the callback.<HotTable beforePaste={(data, coords) => { return false; }}/>| Param | Type | Description |
|---|---|---|
| data | Array<Array> | An array of arrays which contains data to paste. |
| coords | Array<object> | An array of objects with ranges of the visual indexes (startRow, startCol, endRow, endCol) that correspond to the previously selected area. |
Returns: * - If returns false then pasting is canceled.
beforePasteParse
beforePasteParse(clipboardData, event) ⇒ *
Fired by the CopyPaste plugin on every paste the grid is about to handle, before the clipboard content is sanitized and parsed. This hook is fired when the Options#copyPaste option is enabled.
Use it to clean the clipboard content that arrives from another application, for example the
text/html that a spreadsheet puts on the clipboard. After the hook, the plugin goes on as usual:
it sanitizes and parses the content, runs beforePaste, hands the values to the
grid, and runs afterPaste.
The hook doesn’t fire when the plugin is disabled, when the grid isn’t listening (on a page with more than one grid, only the active grid’s callbacks run), when nothing is selected, when a cell editor is open, or when the paste targets an element outside the grid.
The hook is synchronous. A callback can read the clipboard only while the browser dispatches the
event, so a returned Promise isn’t awaited. When more than one callback is registered, they all
receive the same clipboardData object, so each one sees the edits of the previous one.
The hook gets a writable copy of the clipboard, because the clipboardData of a native paste
event is read-only. Editing the copy doesn’t change the system clipboard.
Keep these rules in mind:
- If
text/htmlcontains a<table>, it wins overtext/plain. A spreadsheet paste always carries such HTML. To make your changes totext/plaincount, also callclipboardData.clearData('text/html'). - If you change
text/plainortext/htmland leave theapplication/ht-source-data-json-htmlflavor (the one Handsontable writes on copy) untouched, the plugin drops that flavor. Otherwise, a cell with theparsePastedValueoption would bring back the values you’ve just cleaned. - The
text/htmlandapplication/ht-source-data-json-htmlflavors still go through thesanitizerafter your callback. - Don’t call
paste()from the callback. EditclipboardDatainstead. A call topaste()runs the hook again, witheventset tonull. - Return
falseto cancel the paste, or return nothing.Hooks#runpasses a returned value (falseincluded) to the next callback as itsclipboardData. Returnfalseonly from the last callback, or the only one, and never return any other value.
Since: 19.0.0
Example
// Clean the regional number format of the plain text, and let it win over the HTML.<HotTable beforePasteParse={(clipboardData, event) => { const text = clipboardData.getData('text/plain');
clipboardData.setData('text/plain', text.replace(/[\u00a0\u202f]/g, '').replace(/(\d),(\d)/g, '$1.$2')); clipboardData.clearData('text/html'); }}/>// To cancel pasting, return false from the callback.<HotTable beforePasteParse={(clipboardData, event) => { return false; }}/>| Param | Type | Description |
|---|---|---|
| clipboardData | object | A writable copy of the clipboard. It holds every string flavor of the paste event: text/plain, text/html, the private application/ht-source-data-json-html, and any other listed type. Its types property lists the flavors. The getData(type) method returns '' for an absent flavor, like DataTransfer does. The setData(type, value) method sets a flavor. The clearData(type) method removes a flavor, or every flavor when you skip the argument. Files aren’t copied: read them from event.clipboardData.files. |
| event | ClipboardEvent null | The native ClipboardEvent of a user paste. It’s null when the paste comes from the paste() method of the plugin. |
Returns: * - If returns false then pasting is canceled. Nothing is written, and the beforePaste
and afterPaste hooks don’t fire.
beforeReadOnlyToggle
beforeReadOnlyToggle(stateBefore, ranges, readOnly)
Fired before toggling the read-only state of the selected cells, from the context menu or column menu “Read only” item.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| stateBefore | object | An object where each key is a visual row index and each value is an array of booleans (the previous readOnly state) indexed by visual column. |
| ranges | Array<CellRange> | An array of CellRange coordinates where the read-only state will be applied. |
| readOnly | boolean | The new read-only state being applied to every affected cell. |
beforeRedo
beforeRedo(action) ⇒ * | boolean
Fired by UndoRedo plugin before the redo action. Contains information about the action that is being redone. This hook is fired when Options#undo option is enabled.
| Param | Type | Description |
|---|---|---|
| action | object | The action object. Contains information about the action being redone. The actionType property of the object specifies the type of the action in a String format (e.g. 'remove_row'). |
Returns: * | boolean - If false is returned the action is canceled.
beforeRedoStackChange
beforeRedoStackChange(undoneActions)
Fired by UndoRedo plugin before changing redo stack.
Since: 8.4.0
| Param | Type | Description |
|---|---|---|
| undoneActions | Array | Stack of actions which may be redone. |
beforeRefreshDimensions
beforeRefreshDimensions(previousDimensions, currentDimensions, actionPossible) ⇒ undefined | boolean
Cancellable hook, called after resizing a window or after detecting size change of the
Handsontable root element, but before redrawing a table. A re-measure after a web font loads does not
fire it (see afterFontsLoad), so returning false does not stop that re-measure.
| Param | Type | Description |
|---|---|---|
| previousDimensions | Object | Previous dimensions of the container. |
| currentDimensions | Object | Current dimensions of the container. |
| actionPossible | boolean | true, if current and previous dimensions are different, false otherwise. |
Returns: undefined | boolean - If the callback returns false, the refresh action will not be completed.
beforeRemoveCellClassNames
beforeRemoveCellClassNames ⇒ Array<string> | undefined
Fired inside the Walkontable’s refreshSelections method. Can be used to remove additional class names from all cells in the table.
Since: 0.38.1
Returns: Array<string> | undefined - Can return an Array of Strings. Each of these strings will act like class names to be removed from all the cells in the table.
beforeRemoveCellMeta
beforeRemoveCellMeta(row, column, key, value) ⇒ * | boolean
Fired before cell meta is removed.
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
| column | number | Visual column index. |
| key | string | The removed meta key. |
| value | * | Value which is under removed key of cell meta. |
Returns: * | boolean - If false is returned the action is canceled.
beforeRemoveCol
beforeRemoveCol(index, amount, physicalColumns, [source]) ⇒ * | boolean
Fired before one or more columns are about to be removed.
Columns are removed in runs of neighboring columns, and this hook fires once per run. This
is by design. Removing columns 1, 2, and 3 fires the hook once. Removing columns 0, 1,
and 3 (for example, by selecting columns with Ctrl/Cmd held) fires it twice: once for the
0, 1 run, then once for 3.
Two columns count as neighbors by their visual index, so sorting or moving columns changes how one selection is grouped into runs.
amount is the number of columns the call asked to remove, which is not always the number
it removes. A request that runs past the last column is cut short, but amount is not, so
read physicalColumns.length for the count that is really going.
Returning false cancels only the run this call describes. Any later run of the same
removal still fires and still removes its columns, so blocking the first run of a
multi-run removal does not block the rest. Use beforeAlter to stop the
whole operation.
Editing physicalColumns in place is not supported. The splice order and amount are
fixed before this hook runs while the index mapper reads the edited array, so the change
only half-applies and leaves the two disagreeing. Cancel and re-issue
alter() instead.
Every call describes the data source as it stands at that moment, so the index and
physicalColumns of a later call already account for the columns that the earlier calls
removed.
| Param | Type | Description |
|---|---|---|
| index | number | Visual index of starter column. |
| amount | number | Amount of columns to be removed. |
| physicalColumns | Array<number> | An array of physical columns removed from the data source. |
| [source] | string | optional String that identifies source of hook call (list of all available sources). |
Returns: * | boolean - If false is returned the action is canceled.
beforeRemoveRow
beforeRemoveRow(index, amount, physicalRows, [source]) ⇒ * | boolean
Fired when one or more rows are about to be removed.
Rows are removed in runs of neighboring rows, and this hook fires once per run. This is by
design. Removing rows 1, 2, and 3 fires the hook once, with amount set to 3. Removing
rows 0, 1, and 3 (for example, by selecting rows with Ctrl/Cmd held) fires it twice: first
with amount set to 2, then with amount set to 1.
Two rows count as neighbors by their visual index, so sorting, moving, or hiding rows changes how one selection is grouped into runs. Two rows that sit next to each other on screen with a hidden row between them are not neighbors, and they fire two calls.
Returning false cancels only the run this call describes. Any later run of the same
removal still fires and still removes its rows, so blocking the first run of a multi-run
removal does not block the rest. Use beforeAlter to stop the whole
operation.
On the alter() path, physicalRows can be edited in place to
change which rows are removed; the NestedRows plugin uses this to
add the descendants of a removed parent. amount is counted before any such edit, so read
physicalRows.length for the current list, and read amount from
afterRemoveRow for the count that was really removed. Plugins that
fire this hook outside alter(), such as NestedRows when a child is detached, may
ignore both the edited array and the returned value.
physicalRows holds physical indexes, so on a sorted or reordered grid it is neither
ascending nor contiguous even for a single run. Every call also describes the data source
as it stands at that moment, so the index and physicalRows of a later call already
account for the rows that the earlier calls removed.
| Param | Type | Description |
|---|---|---|
| index | number | Visual index of starter row. |
| amount | number | Amount of rows to be removed. |
| physicalRows | Array<number> | An array of physical rows removed from the data source. |
| [source] | string | optional String that identifies source of hook call (list of all available sources). |
Returns: * | boolean - If false is returned the action is canceled.
beforeRender
beforeRender(isForced)
Fired before Handsontable’s view-rendering engine updates the view.
The beforeRender event is fired right after the Handsontable
business logic is executed and right before the rendering engine starts calling
the Core logic, renderers, cell meta objects etc. to update the view.
| Param | Type | Description |
|---|---|---|
| isForced | boolean | If set to true, the rendering gets triggered by a change of settings, a change of data, or a logic that needs a full Handsontable render cycle. If set to false, the rendering gets triggered by something lighter, such as moving the selection. The flag describes what triggered the render, not how much was redrawn: a false render still redraws cells when it brings a new row or column band into view. Scrolling does not fire this hook at all. |
beforeRenderer
beforeRenderer(TD, row, column, prop, value, cellProperties)
Fired before starting rendering the cell.
| Param | Type | Description |
|---|---|---|
| TD | HTMLTableCellElement | Currently rendered cell’s TD element. |
| row | number | Visual row index. |
| column | number | Visual column index. |
| prop | string number | Column property name or a column index, if datasource is an array of arrays. |
| value | * | Value of the rendered cell. |
| cellProperties | object | Object containing the cell’s properties. |
beforeResumeExecution
beforeResumeExecution
Fired by Core#resumeExecution before it resumes the execution and updates the index cache.
batch() and batchExecution() resume the
execution the same way, and so does Handsontable itself (for example, to size columns on a render).
The hook fires only when the execution changes from suspended to resumed: a nested call, a forced
nested call, and a call while the execution is not suspended fire nothing. It cannot cancel the resume.
When a listener throws, the execution still resumes, afterResumeExecution still fires, and the error
reaches the caller. The hook does not fire while the instance is being destroyed.
A listener can suspend and resume the execution of the same instance. Those calls belong to the resume in
progress, so they fire no execution hooks. A listener that leaves the execution suspended keeps it
suspended. beforeResumeExecution then fires again, and afterResumeExecution fires, with the call that
ends it.
Since: 19.0.0
Example
<HotTable beforeResumeExecution={() => { console.log('The execution is about to be resumed'); }}/>beforeRowCollapse
beforeRowCollapse(currentCollapsedRows, destinationCollapsedRows, collapsePossible) ⇒ undefined | boolean
Fired by the NestedRows plugin before parent rows are collapsed. This hook is fired when the Options#nestedRows option is enabled.
Returning false in the callback will prevent the collapsing action from completing.
Since: 18.1.0
| Param | Type | Description |
|---|---|---|
| currentCollapsedRows | Array | A list of the physical indexes of the currently collapsed parent rows. |
| destinationCollapsedRows | Array | A list of the physical indexes of the parent rows that will be collapsed. |
| collapsePossible | boolean | true, if every provided index points at a row that has children, false otherwise. |
Returns: undefined | boolean - If the callback returns false, the collapsing action will not be completed.
beforeRowExpand
beforeRowExpand(currentCollapsedRows, destinationCollapsedRows, expandPossible) ⇒ undefined | boolean
Fired by the NestedRows plugin before parent rows are expanded. This hook is fired when the Options#nestedRows option is enabled.
Returning false in the callback will prevent the expanding action from completing.
Since: 18.1.0
| Param | Type | Description |
|---|---|---|
| currentCollapsedRows | Array | A list of the physical indexes of the currently collapsed parent rows. |
| destinationCollapsedRows | Array | A list of the physical indexes of the parent rows that will stay collapsed. |
| expandPossible | boolean | true, if every provided index points at a row that has children, false otherwise. |
Returns: undefined | boolean - If the callback returns false, the expanding action will not be completed.
beforeRowMove
beforeRowMove(movedRows, finalIndex, dropIndex, movePossible) ⇒ * | boolean
Fired by ManualRowMove plugin before changing the order of the visual indexes. This hook is fired when Options#manualRowMove option is enabled. It doesn’t fire when the user presses a row header and releases it without moving the pointer more than a few pixels.
The hook also fires when the move leaves the order unchanged, for example when you drop a row back where it
was. To tell such a move apart, use the afterRowMove hook and check its orderChanged parameter.
| Param | Type | Description |
|---|---|---|
| movedRows | Array | Array of visual row indexes to be moved. |
| finalIndex | number | Visual row index, being a start index for the moved rows. Points to where the elements will be placed after the moving action. To check visualization of final index please take a look at documentation. |
| dropIndex | number undefined | Visual row index, being a drop index for the moved rows. Points to where we are going to drop the moved elements. To check visualization of drop index please take a look at documentation. It’s undefined when dragRows function wasn’t called. |
| movePossible | boolean | Indicates if it’s possible to move rows to the desired position. |
Returns: * | boolean - If false is returned the action is canceled.
beforeRowResize
beforeRowResize(newSize, row, isDoubleClick) ⇒ number | false | undefined
Fired by ManualRowResize plugin before rendering the table with modified row sizes. This hook is fired when Options#manualRowResize option is enabled.
| Param | Type | Description |
|---|---|---|
| newSize | number | Calculated new row height. |
| row | number | Visual index of the resized row. |
| isDoubleClick | boolean | Flag that determines whether there was a double-click. |
Returns: number | false | undefined - Returns a new row size, false to cancel the resize, or undefined to keep the size set by the drag or auto-calculation.
beforeRowSelectionChange
beforeRowSelectionChange(rowsToSelect, rowsToDeselect, source) ⇒ undefined | boolean
Fired by the RowSelection plugin before the row selection changes. Fired only if the
Options#rowSelection option is enabled. Returning false in the callback cancels the change.
The lists hold only the rows whose state really changes. With a server-backed grid (the
DataProvider plugin), the lists hold only the loaded rows: a change that affects only rows
on other pages (for example, “select all” while the loaded page is already selected) runs the hook
with two empty lists. To read the full selection, call getServerSelection().
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| rowsToSelect | Array<number> | Physical indexes of the rows about to be selected. |
| rowsToDeselect | Array<number> | Physical indexes of the rows about to be deselected. |
| source | string | What changed the selection: 'checkbox', 'headerCheckbox', 'click', 'keyboard', 'api', or 'dataChange'. 'dataChange' means a write to the bound checkbox column (see Options#rowSelection) that did not come from editing the cell – for example a paste, an autofill, or a setDataAtCell() call. |
Returns: undefined | boolean - If the callback returns false, the selection does not change.
beforeRowsMutation
beforeRowsMutation(operation, payload)
Fired before rows mutation (create, update, remove) is sent to the server. Return false to cancel.
Since: 17.1.0
| Param | Type | Description |
|---|---|---|
| operation | string | One of 'create', 'update', 'remove'. |
| payload | object | Operation-specific payload ({ rowsCreate }, { rows: [...] }, or { rowsRemove: [...] }). |
beforeRowWrap
beforeRowWrap(isWrapEnabled, newCoords, isFlipped)
When the focus position is moved to the next or previous row caused by the Options#autoWrapRow option the hook is triggered.
Since: 14.0.0
| Param | Type | Description |
|---|---|---|
| isWrapEnabled | boolean | Tells whether the row wrapping is going to happen. There may be situations where the option does not work even though it is enabled. This is due to the priority of other options that may block the feature. For example, when the Options#minSpareCols is defined, the Options#autoWrapRow option is not checked. Thus, row wrapping is off. |
| newCoords | CellCoords | The new focus position. It is an object with keys row and col, where a value of -1 indicates a header. |
| isFlipped | boolean | true if the row index was flipped, false otherwise. Flipped index means that the user reached the last row and the focus is moved to the first row or vice versa. |
beforeSelectAll
beforeSelectAll(from, to, [highlight])
Fired before all cells are selected (e.g. during mouse corner click or Core#selectAll API call).
Since: 16.1.0
Example
<HotTable beforeSelectAll={(from, to, highlight) => { // moves the focus to a new position if (highlight) { highlight.row = 3; highlight.col = 3; } }}/>| Param | Type | Description |
|---|---|---|
| from | CellCoords | Selection start coords object. |
| to | CellCoords | Selection end coords object. |
| [highlight] | CellCoords | optional Selection cell focus coords object. |
beforeSelectColumns
beforeSelectColumns(from, to, highlight)
Fired before one or more columns are selected (e.g. during mouse header click or Core#selectColumns API call).
Since: 14.0.0
Example
<HotTable beforeSelectColumns={(from, to, highlight) => { // Extend the column selection by one column left and one column right. from.col = Math.max(from.col - 1, 0); to.col = Math.min(to.col + 1, this.countCols() - 1); }}/>| Param | Type | Description |
|---|---|---|
| from | CellCoords | Selection start coords object. |
| to | CellCoords | Selection end coords object. |
| highlight | CellCoords | Selection cell focus coords object. |
beforeSelectionFocusSet
beforeSelectionFocusSet(coords)
Fired before setting focus selection.
With merged cells, the coordinates name the cell the focus moves to: Enter and Tab stop once on a merged cell and skip the cells it covers.
Since: 14.3.0
| Param | Type | Description |
|---|---|---|
| coords | CellCoords | CellCoords instance. |
beforeSelectionHighlightSet
beforeSelectionHighlightSet
Fired before applying selection coordinates to the renderable coordinates for Walkontable (rendering engine). It occurs even when cell coordinates remain unchanged and activates during cell selection and drag selection. The behavior of Shift+Tab differs from ← when there’s no further movement possible.
With merged cells, the selected range already covers every merged cell it touches, and its focus sits on a merged cell’s top-left visible cell. A range selected through a header keeps its own extent.
Since: 14.0.0
beforeSelectRows
beforeSelectRows(from, to, highlight)
Fired before one or more rows are selected (e.g. during mouse header click or Core#selectRows API call).
Since: 14.0.0
Example
<HotTable beforeSelectRows={(from, to, highlight) => { // Extend the row selection by one row up and one row bottom more. from.row = Math.max(from.row - 1, 0); to.row = Math.min(to.row + 1, this.countRows() - 1); }}/>| Param | Type | Description |
|---|---|---|
| from | CellCoords | Selection start coords object. |
| to | CellCoords | Selection end coords object. |
| highlight | CellCoords | Selection cell focus coords object. |
beforeSetCellMeta
beforeSetCellMeta(row, column, key, value) ⇒ boolean | undefined
Fired before cell meta is changed.
Since: 8.0.0
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
| column | number | Visual column index. |
| key | string | The updated meta key. |
| value | * | The updated meta value. |
Returns: boolean | undefined - If false is returned the action is canceled.
beforeSetRangeEnd
beforeSetRangeEnd(coords)
Fired before setting range is ended.
| Param | Type | Description |
|---|---|---|
| coords | CellCoords | CellCoords instance. |
beforeSetRangeStart
beforeSetRangeStart(coords)
Fired before setting range is started.
| Param | Type | Description |
|---|---|---|
| coords | CellCoords | CellCoords instance. |
beforeSetRangeStartOnly
beforeSetRangeStartOnly(coords)
Fired before setting range is started but not finished yet.
| Param | Type | Description |
|---|---|---|
| coords | CellCoords | CellCoords instance. |
beforeSheetTabAdd
beforeSheetTabAdd(name, duplicateOfId, source) ⇒ * | boolean
Fired by SheetsBar plugin before adding a new sheet. This hook is fired when Options#sheetsBar option is enabled.
It fires for an added sheet and for a duplicate.
A listener cannot switch, add, remove, rename, duplicate, or move a sheet: those calls return
false (null for an add or a duplicate).
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| name | string null | The requested sheet name, or null when it was omitted. For a duplicate, the name the copy gets. |
| duplicateOfId | number null | The id of the sheet being copied, or null for an added sheet. |
| source | string | String that identifies source of hook call. |
Returns: * | boolean - If false is returned the action is canceled.
beforeSheetTabChange
beforeSheetTabChange(oldSheetId, newSheetId, source) ⇒ * | boolean
Fired by SheetsBar plugin before changing the active sheet. This hook is fired when Options#sheetsBar option is enabled.
By the time it fires, the cell editor and the comment editor have saved and closed, so the
edit stays saved even when a listener cancels the switch. It does not fire when the switch is
refused because a cell value is still waiting for its validator, or because the editor holds a
value its validator rejected. A listener cannot switch, add, remove, rename, duplicate, or move
a sheet: those calls return false (null for an add or a duplicate). A change it makes to a cell
with a validator refuses the switch, because the change would otherwise be written into the
arriving sheet.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| oldSheetId | number | The id of the sheet being left. |
| newSheetId | number | The id of the sheet being activated. |
| source | string | String that identifies source of hook call. |
Returns: * | boolean - If false is returned the action is canceled.
beforeSheetTabMove
beforeSheetTabMove(sheetId, finalIndex, source) ⇒ * | boolean
Fired by SheetsBar plugin before moving a sheet to a new tab position. This hook is fired when Options#sheetsBar option is enabled.
A listener cannot switch, add, remove, rename, duplicate, or move a sheet: those calls return
false (null for an add or a duplicate).
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| sheetId | number | The id of the sheet being moved. |
| finalIndex | number | The requested tab index. |
| source | string | String that identifies source of hook call. |
Returns: * | boolean - If false is returned the action is canceled.
beforeSheetTabRemove
beforeSheetTabRemove(sheetId, source) ⇒ * | boolean
Fired by SheetsBar plugin before removing a sheet. This hook is fired when Options#sheetsBar option is enabled.
A listener cannot switch, add, remove, rename, duplicate, or move a sheet: those calls return
false (null for an add or a duplicate).
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| sheetId | number | The id of the sheet to be removed. |
| source | string | String that identifies source of hook call. |
Returns: * | boolean - If false is returned the action is canceled.
beforeSheetTabRename
beforeSheetTabRename(sheetId, oldName, newName, source) ⇒ * | boolean
Fired by SheetsBar plugin before renaming a sheet. This hook is fired when Options#sheetsBar option is enabled.
A listener cannot switch, add, remove, rename, duplicate, or move a sheet: those calls return
false (null for an add or a duplicate).
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| sheetId | number | The id of the sheet being renamed. |
| oldName | string | The current name of the sheet. |
| newName | string | The requested new name of the sheet. |
| source | string | String that identifies source of hook call. |
Returns: * | boolean - If false is returned the action is canceled.
beforeStretchingColumnWidth
beforeStretchingColumnWidth(stretchedWidth, column) ⇒ number | undefined
Fired before applying stretched column width to column.
| Param | Type | Description |
|---|---|---|
| stretchedWidth | number | Calculated width. |
| column | number | Visual column index. |
Returns: number | undefined - Returns new width which will be applied to the column element.
beforeSuspendExecution
beforeSuspendExecution
Fired by Core#suspendExecution before it suspends the execution (the index cache updates).
batch() and batchExecution() suspend the
execution the same way, and so does Handsontable itself (for example, to size columns on a render).
The hook fires only when the execution changes from resumed to suspended: a nested call fires nothing. Its return value cannot cancel the suspension, but a listener that throws stops it, and the error reaches the caller. The hook does not fire while the instance is being destroyed.
A listener can suspend and resume the execution of the same instance (for example, with
batch()). Those calls belong to the suspension in progress, so they fire no
execution hooks.
Since: 19.0.0
Example
<HotTable beforeSuspendExecution={() => { console.log('The execution is about to be suspended'); }}/>beforeTouchScroll
beforeTouchScroll
Fired before the logic of handling a touch scroll, when user started scrolling on a touch-enabled device.
beforeTrimRow
beforeTrimRow(currentTrimConfig, destinationTrimConfig, actionPossible) ⇒ undefined | boolean
Fired by TrimRows plugin before trimming rows. This hook is fired when Options#trimRows option is enabled.
| Param | Type | Description |
|---|---|---|
| currentTrimConfig | Array | Current trim configuration - a list of trimmed physical row indexes. |
| destinationTrimConfig | Array | Destination trim configuration - a list of trimmed physical row indexes. |
| actionPossible | boolean | true, if all of the row indexes are withing the bounds of the table, false otherwise. |
Returns: undefined | boolean - If the callback returns false, the trimming action will not be completed.
beforeUndo
beforeUndo(action) ⇒ * | boolean
Fired by UndoRedo plugin before the undo action. Contains information about the action that is being undone. This hook is fired when Options#undo option is enabled.
| Param | Type | Description |
|---|---|---|
| action | object | The action object. Contains information about the action being undone. The actionType property of the object specifies the type of the action in a String format. (e.g. 'remove_row'). |
Returns: * | boolean - If false is returned the action is canceled.
beforeUndoStackChange
beforeUndoStackChange(doneActions, [source]) ⇒ * | boolean
Fired by UndoRedo plugin before changing undo stack.
Since: 8.4.0
| Param | Type | Description |
|---|---|---|
| doneActions | Array | Stack of actions which may be undone. |
| [source] | string | optional String that identifies source of action (list of all available sources). |
Returns: * | boolean - If false is returned the action of changing undo stack is canceled.
beforeUnhideColumns
beforeUnhideColumns(currentHideConfig, destinationHideConfig, actionPossible) ⇒ undefined | boolean
Fired by HiddenColumns plugin before marking the columns as not hidden. Fired only if the Options#hiddenColumns option is enabled.
Returning false in the callback will prevent the column revealing action from completing.
| Param | Type | Description |
|---|---|---|
| currentHideConfig | Array | Current hide configuration - a list of hidden physical column indexes. |
| destinationHideConfig | Array | Destination hide configuration - a list of hidden physical column indexes. |
| actionPossible | boolean | true, if the provided column indexes are valid, false otherwise. |
Returns: undefined | boolean - If the callback returns false, the hiding action will not be completed.
beforeUnhideRows
beforeUnhideRows(currentHideConfig, destinationHideConfig, actionPossible) ⇒ undefined | boolean
Fired by HiddenRows plugin before marking the rows as not hidden. Fired only if the Options#hiddenRows option is enabled.
Returning false in the callback will prevent the row revealing action from completing.
| Param | Type | Description |
|---|---|---|
| currentHideConfig | Array | Current hide configuration - a list of hidden physical row indexes. |
| destinationHideConfig | Array | Destination hide configuration - a list of hidden physical row indexes. |
| actionPossible | boolean | true, if provided row indexes are valid, false otherwise. |
Returns: undefined | boolean - If the callback returns false, the revealing action will not be completed.
beforeUnmergeCells
beforeUnmergeCells(cellRange, [auto])
Fired by MergeCells plugin before unmerging the cells. This hook is fired when Options#mergeCells option is enabled.
| Param | Type | Default | Description |
|---|---|---|---|
| cellRange | CellRange | Selection cell range. | |
| [auto] | boolean | false | optional true if called automatically by the plugin. |
beforeUntrimRow
beforeUntrimRow(currentTrimConfig, destinationTrimConfig, actionPossible) ⇒ undefined | boolean
Fired by TrimRows plugin before untrimming rows. This hook is fired when Options#trimRows option is enabled.
| Param | Type | Description |
|---|---|---|
| currentTrimConfig | Array | Current trim configuration - a list of trimmed physical row indexes. |
| destinationTrimConfig | Array | Destination trim configuration - a list of trimmed physical row indexes. |
| actionPossible | boolean | true, if all of the row indexes are withing the bounds of the table, false otherwise. |
Returns: undefined | boolean - If the callback returns false, the untrimming action will not be completed.
beforeUpdateData
beforeUpdateData(sourceData, initialLoad, source) ⇒ Array
Fired before the updateData() method
modifies Handsontable’s data.
Read more:
Since: 11.1.0
| Param | Type | Description |
|---|---|---|
| sourceData | Array | An array of arrays, or an array of objects, that contains Handsontable’s data |
| initialLoad | boolean | A flag that indicates whether the data was loaded at Handsontable’s initialization (true) or later (false) |
| source | string | The source of the call |
Returns: Array - The returned array will be used as Handsontable’s new dataset.
beforeValidate
beforeValidate(value, row, prop, [source])
Fired before cell validation, only if validator function is defined. This can be used to manipulate the value of changed cell before it is applied to the validator function.
Note: this will not affect values of changes. This will change value ONLY for validation.
| Param | Type | Description |
|---|---|---|
| value | * | Value of the cell. |
| row | number | Visual row index. |
| prop | string number | Property name or column index. For array-based data, this is the physical column index. When columns[i].data is a function, this is the visual column index. |
| [source] | string | optional String that identifies source of hook call (list of all available sources). |
beforeValueRender
beforeValueRender(value, cellProperties)
Fired before cell value is rendered into the DOM (through renderer function). This can be used to manipulate the value which is passed to the renderer without modifying the renderer itself.
| Param | Type | Description |
|---|---|---|
| value | * | Cell value to render. |
| cellProperties | object | An object containing the cell properties. |
beforeViewportScroll
beforeViewportScroll
Fired before the vertical or horizontal viewport scroll. Triggered by the scrollViewportTo()
method or table internals.
Since: 14.0.0
beforeViewportScrollHorizontally
beforeViewportScrollHorizontally(visualColumn, [snapping]) ⇒ number | boolean
Fired before the horizontal viewport scroll. Triggered by the scrollViewportTo()
method or table internals.
Since: 14.0.0
| Param | Type | Default | Description |
|---|---|---|---|
| visualColumn | number | Visual column index. | |
| [snapping] | 'auto' 'start' 'end' | ’auto’ | optional If 'start', viewport is scrolled to show the cell on the left of the table. If 'end', viewport is scrolled to show the cell on the right of the table. When 'auto', the viewport is scrolled only when the column is outside of the viewport. |
Returns: number | boolean - Returns modified column index (or the same as passed in the method argument) to which
the viewport will be scrolled. If the returned value is false, the scrolling will be canceled.
beforeViewportScrollVertically
beforeViewportScrollVertically(visualRow, [snapping]) ⇒ number | boolean
Fired before the vertical viewport scroll. Triggered by the scrollViewportTo()
method or table internals.
Since: 14.0.0
| Param | Type | Default | Description |
|---|---|---|---|
| visualRow | number | Visual row index. | |
| [snapping] | 'auto' 'top' 'bottom' | ’auto’ | optional If 'top', viewport is scrolled to show the cell on the top of the table. If 'bottom', viewport is scrolled to show the cell on the bottom of the table. When 'auto', the viewport is scrolled only when the row is outside of the viewport. |
Returns: number | boolean - Returns modified row index (or the same as passed in the method argument) to which
the viewport will be scrolled. If the returned value is false, the scrolling will be canceled.
beforeViewRender
beforeViewRender(isForced, skipRender)
Fired before Handsontable’s view-rendering engine is rendered.
Note: In Handsontable 9.x and earlier, the beforeViewRender hook was named beforeRender.
Since: 10.0.0
| Param | Type | Description |
|---|---|---|
| isForced | boolean | If set to true, the rendering gets triggered by a change of settings, a change of data, or a logic that needs a full Handsontable render cycle. If set to false, the rendering gets triggered by scrolling or moving the selection. |
| skipRender | object | Object with skipRender property, if it is set to true the next rendering cycle will be skipped. |
beforeWidthChange
beforeWidthChange(width) ⇒ number | string
Fired before the width of the table is changed.
With side panels docked in the start and end layout slots and the width option set,
the hook runs again whenever a side panel mounts, unmounts, or changes its width.
Since: 16.1.0
| Param | Type | Description |
|---|---|---|
| width | number string | Table width. |
Returns: number | string - Modified table width.
construct
construct
Fired after Handsontable instance is constructed (using new operator).
This hook runs inside the constructor, before Handsontable reads the callbacks from the settings
object. A construct callback passed in the settings object is registered too late, so it never
runs. To listen to this hook, register it globally with
Handsontable.hooks.add('construct', callback). To run your code from the settings object as early
as possible, use beforeInit instead.
dialogFocusNextElement
dialogFocusNextElement
Fired by Dialog plugin when the user presses Tab while focus is inside the open dialog. This hook is fired when Options#dialog option is enabled.
The hook runs once per key press, after the browser handled the key. It receives no arguments.
To find out which element has the focus, read document.activeElement in the callback.
Since: 16.1.0
dialogFocusPreviousElement
dialogFocusPreviousElement
Fired by Dialog plugin when the user presses Shift+Tab while focus is inside the open dialog. This hook is fired when Options#dialog option is enabled.
The hook runs once per key press, after the browser handled the key. It receives no arguments.
To find out which element has the focus, read document.activeElement in the callback.
Since: 16.1.0
hasExternalDataSource
hasExternalDataSource ⇒ boolean | void
Queried to determine if the instance uses an external data source (complete Options#dataProvider configuration).
When the DataProvider plugin is enabled, it adds an instance handler in enablePlugin(). Callbacks may return
true, false, or undefined; the value propagates through the hook chain as in any other hook.
Since: 17.1.0
init
init
Fired after Handsontable instance is initiated but before table is rendered.
modifyAutoColumnSizeSeed
modifyAutoColumnSizeSeed(seed, cellProperties, cellValue)
Fired by AutoColumnSize plugin within SampleGenerator utility.
Since: 8.4.0
| Param | Type | Description |
|---|---|---|
| seed | string undefined | Seed ID, unique name to categorize samples. |
| cellProperties | object | Object containing the cell properties. |
| cellValue | * | Value of the cell. |
modifyAutofillRange
modifyAutofillRange(entireArea, startArea) ⇒ Array<number>
Fired by Autofill plugin to allow modifying the autofill range. This hook is fired when Options#fillHandle option is enabled.
| Param | Type | Description |
|---|---|---|
| entireArea | Array<number> | Visual coordinates of the entire area of the drag-down operation ([startRow, startColumn, endRow, endColumn]). |
| startArea | Array<number> | Visual coordinates of the starting point for the drag-down operation ([startRow, startColumn, endRow, endColumn]). |
Returns: Array<number> - The modified autofill range ([startRow, startColumn, endRow, endColumn]).
modifyColHeader
modifyColHeader(column)
Fired when a column header index is about to be modified by a callback function.
| Param | Type | Description |
|---|---|---|
| column | number | Visual column header index. |
modifyColumnHeaderHeight
modifyColumnHeaderHeight
Fired while retrieving the column header height.
modifyColumnHeaderValue
modifyColumnHeaderValue(value, visualColumnIndex, [headerLevel]) ⇒ string
Fired while retrieving a column header’s value.
Since: 12.3.0
| Param | Type | Default | Description |
|---|---|---|---|
| value | string | A column header value. | |
| visualColumnIndex | number | A visual column index. | |
| [headerLevel] | number | 0 | optional Header level index. Accepts positive (0 to n) and negative (-1 to -n) values. For positive values, 0 points to the topmost header. For negative values, -1 points to the bottom-most header (the header closest to the cells). |
Returns: string - The column header value to be updated.
modifyColWidth
modifyColWidth(width, column, [source])
Fired when a column width is about to be modified by a callback function.
See: Column width
Example
// Cap the Product column at 100px when content would exceed 150px.modifyColWidth(width, column) { if (column === 1 && width > 150) { return 100; }}| Param | Type | Description |
|---|---|---|
| width | number | Current column width. |
| column | number | Visual column index. |
| [source] | string | optional String that identifies source of hook call. |
modifyCopyableRange
modifyCopyableRange(copyableRanges) ⇒ Array<object> | undefined
Fired by CopyPaste plugin to allow modifying the range that is about to be copied or cut. It’s recalculated whenever the selection changes, and again right before the values are copied or cut to the clipboard. This hook is fired when Options#copyPaste option is enabled. It’s also fired by the Autofill plugin while a fill-handle drag is in progress, to determine the range that would be copied if the drag ended at the current position.
Example
<HotTable // Copy only the last column of each selected range, regardless of the selection width. modifyCopyableRange={(copyableRanges) => { return copyableRanges.map(({ startRow, endRow, endCol }) => ({ startRow, endRow, startCol: endCol, endCol, })); }}/>| Param | Type | Description |
|---|---|---|
| copyableRanges | Array<object> | An array of objects with ranges of the visual indexes (startRow, startCol, endRow, endCol) that are copyable. |
Returns: Array<object> | undefined - The modified array of copyable ranges. If nothing is returned, the ranges
passed to the callback are used unchanged.
modifyData
modifyData(row, column, valueHolder, ioMode)
Fired when a data was retrieved or modified.
Breaking change (19.0): a change that waited for its validator and landed on a record a filter or another
trimming feature took out of the visual space is written with row set to null (ioMode set).
| Param | Type | Description |
|---|---|---|
| row | number null | Visual row index, or null for a write to a record with no visual row. |
| column | number string function null | Visual column index. null when the property is a numeric index that names no column that exists and is visible. A property name the data set does not use, or a columns[].data accessor function, arrives unchanged. |
| valueHolder | object | Object which contains original value which can be modified by overwriting .value property. |
| ioMode | string | String which indicates for what operation hook is fired (get or set). |
modifyFiltersMatchedRows
modifyFiltersMatchedRows(matchedRows, blankMatchedRows) ⇒ Array<number> | undefined
Fired by the Filters plugin after it finds the rows that match every condition, before it trims the rows that did not match. It fires once per filter pass, never per column. It also fires when the “Filter by value” list of a column reads the rows the earlier columns’ conditions leave. A listener can return a replacement list of rows to keep, for example to keep the parents of a matching nested row. The plugin keeps only the integers within the source row range, in ascending order, without duplicates.
The second argument lists the matching rows whose every column that the conditions of this pass read holds an empty cell. Such a row matches only because a condition accepts empty cells, so a listener can keep the row without keeping the rows that depend on it - for example, the children of a nested parent. Several listeners run in a chain: each one gets the rows the previous one returned, and the same list of blank matches.
Since: 19.0.0
Example
// Hide the rows that match only through empty cells.modifyFiltersMatchedRows(matchedRows, blankMatchedRows) { const blank = new Set(blankMatchedRows);
return matchedRows.filter(row => !blank.has(row));}| Param | Type | Description |
|---|---|---|
| matchedRows | Array<number> | Physical indexes of the rows that match every condition, ascending. |
| blankMatchedRows | Array<number> | Physical indexes of the rows from matchedRows whose every column that the conditions of this pass read holds an empty cell, ascending. For a “Filter by value” list, those are the columns filtered before it. |
Returns: Array<number> | undefined - The physical rows to keep, or undefined to keep matchedRows.
modifyFiltersMultiSelectValue
modifyFiltersMultiSelectValue(item, meta)
Fired when rendering the list of values in the multiple-selection component of the Filters dropdown. The hook allows modifying the displayed values in that component.
Since: 14.2.0
| Param | Type | Description |
|---|---|---|
| item | object | The item in the list of values. |
| meta | object | The cell properties object. |
modifyFocusedElement
modifyFocusedElement(row, column, focusedElement)
Fired when focusing a cell or a header element. Allows replacing the element to be focused by returning a different HTML element.
Since: 14.0.0
| Param | Type | Description |
|---|---|---|
| row | number | Row index. |
| column | number | Column index. |
| focusedElement | HTMLElement undefined | The element to be focused. null for focusedElement is intended when focused cell is hidden. |
modifyFocusOnTabNavigation
modifyFocusOnTabNavigation(tabActivationDir, visualCoords) ⇒ undefined | boolean
Used to modify the cell coordinates when the table is activated (going into the listen mode).
Since: 14.0.0
| Param | Type | Description |
|---|---|---|
| tabActivationDir | 'from_above' 'from_below' | The browsers Tab navigation direction. Depending on whether the user activated the table from the element above or below, another cell can be selected. |
| visualCoords | CellCoords | The coords that will be used to select a cell. |
Returns: undefined | boolean - If false is returned, the table will not be focused.
modifyGetCellCoords
modifyGetCellCoords(row, column, topmost, source) ⇒ undefined | Array<number>
Used to modify the cell coordinates when using the getCell method, opening editor, getting value from the editor
and saving values from the closed editor.
Since: 0.36.0
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
| column | number | Visual column index. |
| topmost | boolean | If set to true, it returns the TD element from the topmost overlay. For example, if the wanted cell is in the range of fixed rows, it will return a TD element from the top overlay. |
| source | string | String that identifies how this coords change will be processed. Possible values: meta the change will affect the cell meta and data; render the change will affect the DOM element that will be returned by the getCell method. |
modifyGetCoordsElement
modifyGetCoordsElement(row, column) ⇒ undefined | Array<number>
Used to modify the returned cell coordinates of clicked cells (TD or TH elements).
Since: 14.6.0
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
| column | number | Visual column index. |
modifyRowData
modifyRowData(row)
Fired when a data was retrieved or modified.
| Param | Type | Description |
|---|---|---|
| row | number | Physical row index. |
modifyRowHeader
modifyRowHeader(row)
Fired when a row header index is about to be modified by a callback function.
| Param | Type | Description |
|---|---|---|
| row | number | Visual row header index. |
modifyRowHeaderValue
modifyRowHeaderValue(value, visualRowIndex) ⇒ string | number
Fired while retrieving a row header’s value.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| value | string number | A row header value. |
| visualRowIndex | number | A visual row index. |
Returns: string | number - The row header value to be used.
modifyRowHeaderWidth
modifyRowHeaderWidth(rowHeaderWidth)
Fired while retrieving the row header width.
A grid can render more than one row header. Return a single number to give every level the same width, or an array with one entry per level - starting at the grid’s edge - to size each on its own. The value passed in follows the same rule, so a handler that widens the incoming width should check for an array before doing arithmetic on it.
| Param | Type | Description |
|---|---|---|
| rowHeaderWidth | number Array<number> | Row header width, or one width per row header level. |
modifyRowHeight
modifyRowHeight(height, row, [source])
Fired when a row height is about to be modified by a callback function.
| Param | Type | Description |
|---|---|---|
| height | number | Row height. |
| row | number | Visual row index. |
| [source] | string | optional String that identifies source of hook call. |
modifyRowHeightByOverlayName
modifyRowHeightByOverlayName(height, row, overlayName)
Fired when a row height is about to be modified by a callback function. The hook allows to change the row height for the specified overlay type.
The first row of the frozen bottom rows is drawn one pixel taller than the height the hook returns for it, because that pixel is the freeze line above the row.
Since: 14.5.0
| Param | Type | Description |
|---|---|---|
| height | number | Row height. |
| row | number | Visual row index. |
| overlayName | 'inline_start' 'inline_end' 'top' 'top_inline_start_corner' 'top_inline_end_corner' 'bottom' 'bottom_inline_start_corner' 'bottom_inline_end_corner' 'master' | Overlay name. |
modifySinglePassLayout
modifySinglePassLayout(singlePassLayout) ⇒ boolean | void
Fired while resolving whether the table renders in a single pass.
Single-pass rendering predicts, from the row/column sizes and the container box, whether
scrollbars will appear and then renders once — instead of rendering, measuring the result, and
re-rendering. Return false to force the legacy measure-then-render path for the table. A feature
whose content size depends on the viewport that is being computed (for example, merged cells) opts
out this way; user code can also return false to disable single-pass rendering.
Since: 18.1.0
| Param | Type | Description |
|---|---|---|
| singlePassLayout | boolean | true when single-pass rendering is currently enabled. |
Returns: boolean | void - Return false to force the legacy measure-then-render path.
modifySourceData
modifySourceData(row, column, valueHolder, ioMode)
Fired when a data was retrieved or modified from the source data set.
Since: 8.0.0
| Param | Type | Description |
|---|---|---|
| row | number | Physical row index. |
| column | number string function | Physical column index, property name, or a columns[].data accessor function (see Options#data). |
| valueHolder | object | Object which contains original value which can be modified by overwriting .value property. |
| ioMode | string | String which indicates for what operation hook is fired (get or set). |
modifyTransformEnd
modifyTransformEnd(delta)
Fired when the end of the selection is being modified (e.g. Moving the selection with the arrow keys).
With merged cells, delta already moves the end past every merged cell it would stop inside.
| Param | Type | Description |
|---|---|---|
| delta | CellCoords | Cell coords object declaring the delta of the new selection relative to the previous one. |
modifyTransformFocus
modifyTransformFocus(delta)
Fired when the focus of the selection is being modified (e.g. Moving the focus with the enter/tab keys).
With merged cells, delta is the plain step. Handsontable then moves the focus in the direction the
step leaves, from one merged cell or cell to the next.
Since: 14.3.0
| Param | Type | Description |
|---|---|---|
| delta | CellCoords | Cell coords object declaring the delta of the new selection relative to the previous one. |
modifyTransformStart
modifyTransformStart(delta)
Fired when the start of the selection is being modified (e.g. Moving the selection with the arrow keys).
With merged cells, delta already steps past the merged cell the selection starts in.
| Param | Type | Description |
|---|---|---|
| delta | CellCoords | Cell coords object declaring the delta of the new selection relative to the previous one. |