# Hooks

Table of contents

# Members

# afterAddChild

Source code (opens new window)

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.

# afterAutofill

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

afterCellMetaReset

Fired after resetting a cell's meta. This happens when the Core#updateSettings method is called.

# afterChange

Source code (opens new window)

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).

Note: For performance reasons, the changes array is null for "loadData" source.

Example

new Handsontable(element, {
  afterChange: (changes) => {
    changes.forEach(([row, prop, oldValue, newValue]) => {
      // Some logic...
    });
  }
})
Param Type Description
changes Array 2D array containing information about each of the edited cells [[row, prop, oldVal, newVal], ...].
[source] string optional String that identifies source of hook call (list of all available sources).

# afterColumnCollapse

Source code (opens new window)

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

Source code (opens new window)

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.

# afterColumnMove

Source code (opens new window)

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.

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

Source code (opens new window)

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.
column number Visual index of the resized column.
isDoubleClick boolean Flag that determines whether there was a double-click.

# afterColumnSort

Source code (opens new window)

afterColumnSort(currentSortConfig, destinationSortConfigs)

Fired by ColumnSorting and MultiColumnSorting plugins after sorting the column. This hook is fired when Options#columnSorting or Options#multiColumnSorting option is enabled.

Param Type Description
currentSortConfig Array Current sort configuration (for all sorted columns).
destinationSortConfigs Array Destination sort configuration (for all sorted columns).

# afterContextMenuDefaultOptions

Source code (opens new window)

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

Source code (opens new window)

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 Context Menu plugin instance.

# afterContextMenuShow

Source code (opens new window)

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 Context Menu plugin instance.

# afterCopy

Source code (opens new window)

afterCopy(data, coords)

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.

# afterCopyLimit

Source code (opens new window)

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

Source code (opens new window)

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).

# afterCreateRow

Source code (opens new window)

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).

# afterCut

Source code (opens new window)

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 which contains the cutted out data.
coords Array<object> An array of objects with ranges of the visual indexes (startRow, startCol, endRow, endCol) which was cut out.

# afterDeselect

Source code (opens new window)

afterDeselect

Fired after the current cell is deselected.

# afterDestroy

Source code (opens new window)

afterDestroy

Fired after destroying the Handsontable instance.

# afterDetachChild

Source code (opens new window)

afterDetachChild(parent, element)

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.

# afterDocumentKeyDown

Source code (opens new window)

afterDocumentKeyDown(event)

General hook which captures keydown events attached to the document body. These events are delegated to the hooks system and consumed by Core and internal modules (e.g plugins, editors).

Param Type Description
event Event A native keydown event object.

# afterDrawSelection

Source code (opens new window)

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

Source code (opens new window)

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 Context Menu items.

# afterDropdownMenuHide

Source code (opens new window)

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

Source code (opens new window)

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.

# afterFilter

Source code (opens new window)

afterFilter(conditionsStack)

Fired by Filters plugin after applying filtering. This hook is fired when Options#filters option is enabled.

Param Type Description
conditionsStack Array<object> An array of objects with added conditions. js // Example format of the conditionsStack argument: [ { column: 2, conditions: [ {name: 'begins_with', args: [['S']]} ], operation: 'conjunction' }, { column: 4, conditions: [ {name: 'not_empty', args: []} ], operation: 'conjunction' }, ]

# afterFormulasValuesUpdate

Source code (opens new window)

afterFormulasValuesUpdate(changes)

Called when a value is updated in the engine.

Since: 9.0.0

Param Type Description
changes Array The values and location of applied changes.

# afterGetCellMeta

Source code (opens new window)

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

Source code (opens new window)

afterGetColHeader(column, TH)

Fired after retrieving information about a column header and appending it to the table header.

Param Type Description
column number Visual column index.
TH HTMLTableCellElement Header's TH element.

# afterGetColumnHeaderRenderers

Source code (opens new window)

afterGetColumnHeaderRenderers(renderers)

Fired after getting the column header renderers.

Param Type Description
renderers Array<function()> An array of the column header renderers.

# afterGetRowHeader

Source code (opens new window)

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

Source code (opens new window)

afterGetRowHeaderRenderers(renderers)

Fired after getting the row header renderers.

Param Type Description
renderers Array<function()> An array of the row header renderers.

# afterHideColumns

Source code (opens new window)

afterHideColumns(currentHideConfig, destinationHideConfig, actionPossible, stateChanged)

Fired by HiddenColumns plugin after marking the columns as 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 non-hidden columns, false otherwise.

# afterHideRows

Source code (opens new window)

afterHideRows(currentHideConfig, destinationHideConfig, actionPossible, stateChanged)

Fired by HiddenRows plugin after marking the rows as 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 non-hidden rows, false otherwise.

# afterInit

Source code (opens new window)

afterInit

Fired after the Handsontable instance is initiated.

# afterLanguageChange

Source code (opens new window)

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

Source code (opens new window)

afterListen

Fired after the table was switched into listening mode. This allows Handsontable to capture keyboard events and respond in the right way.

# afterLoadData

Source code (opens new window)

afterLoadData(sourceData, initialLoad, source)

Fired after new data is loaded (by loadData or updateSettings method) into the data source array.

Param Type Description
sourceData Array Array of arrays or array of objects containing data.
initialLoad boolean Flag that determines whether the data has been loaded during the initialization.
source string Source of the call.

# afterMergeCells

Source code (opens new window)

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

Source code (opens new window)

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.

# afterModifyTransformStart

Source code (opens new window)

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

Source code (opens new window)

afterMomentumScroll

Fired after a scroll event, which is identified as a momentum scroll (e.g. On an iPad).

# afterNamedExpressionAdded

Source code (opens new window)

afterNamedExpressionAdded(namedExpressionName, changes)

Called when a named expression is added to the Formulas' engine instance.

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

Source code (opens new window)

afterNamedExpressionRemoved(namedExpressionName, changes)

Called when a named expression is removed from the Formulas' engine instance.

Since: 9.0.0

Param Type Description
namedExpressionName string The name of the removed expression.
changes Array The values and location of applied changes.

# afterOnCellContextMenu

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

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.

# afterOnCellMouseUp

Source code (opens new window)

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.

# afterPaste

Source code (opens new window)

afterPaste(data, coords)

Fired by CopyPaste plugin after values 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 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

Source code (opens new window)

afterPluginsInitialized

Fired after initializing all the plugins. This hook should be added before Handsontable is initialized.

Example

Handsontable.hooks.add('afterPluginsInitialized', myCallback);

# afterRedo

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

afterRefreshDimensions(previousDimensions, currentDimensions, stateChanged)

Fired after the window was resized.

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

Source code (opens new window)

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

Source code (opens new window)

afterRemoveCol(index, amount, physicalColumns, [source])

Fired after one or more columns are removed.

Param Type Description
index number Visual index of starter column.
amount number An amount of removed columns.
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

Source code (opens new window)

afterRemoveRow(index, amount, physicalRows, [source])

Fired after one or more rows are removed.

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

Source code (opens new window)

afterRender(isForced)

Fired after the Handsontable table is rendered.

Param Type Description
isForced boolean Is true if rendering was triggered by a change of settings or data; or false if rendering was triggered by scrolling or moving selection.

# afterRenderer

Source code (opens new window)

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.

# afterRowMove

Source code (opens new window)

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.

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

Source code (opens new window)

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.

# afterScrollHorizontally

Source code (opens new window)

afterScrollHorizontally

Fired after the horizontal scroll event.

# afterScrollVertically

Source code (opens new window)

afterScrollVertically

Fired after the vertical scroll event.

# afterSelection

Source code (opens new window)

afterSelection(row, column, row2, column2, preventScrolling, selectionLayerLevel)

Fired after one or more cells are selected (e.g. During mouse move).

Example

new Handsontable(element, {
  afterSelection: (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.
column number Selection start visual column index.
row2 number Selection end visual row index.
column2 number Selection end visual column index.
preventScrolling object Object with value property where its value change will be observed.
selectionLayerLevel number The number which indicates what selection layer is currently modified.

# afterSelectionByProp

Source code (opens new window)

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

new Handsontable(element, {
  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 Object with value property where its value change will be observed.
selectionLayerLevel number The number which indicates what selection layer is currently modified.

# afterSelectionEnd

Source code (opens new window)

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

Source code (opens new window)

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.

# afterSetCellMeta

Source code (opens new window)

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

Source code (opens new window)

afterSetDataAtCell(changes, [source])

Fired after cell data was changed.

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 (list of all available sources).

# afterSetDataAtRowProp

Source code (opens new window)

afterSetDataAtRowProp(changes, [source])

Fired after cell data was changed. Called only when setDataAtRowProp was executed.

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

Source code (opens new window)

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.

# afterSheetAdded

Source code (opens new window)

afterSheetAdded(addedSheetDisplayName)

Called when a new sheet is added to the Formulas' engine instance.

Since: 9.0.0

Param Type Description
addedSheetDisplayName string The name of the added sheet.

# afterSheetRemoved

Source code (opens new window)

afterSheetRemoved(removedSheetDisplayName, changes)

Called when a sheet is removed from the Formulas' engine instance.

Since: 9.0.0

Param Type Description
removedSheetDisplayName string The removed sheet name.
changes Array The values and location of applied changes.

# afterSheetRenamed

Source code (opens new window)

afterSheetRenamed(oldDisplayName, newDisplayName)

Called when a sheet in the Formulas' engine instance is renamed.

Since: 9.0.0

Param Type Description
oldDisplayName string The old name of the sheet.
newDisplayName string The new name of the sheet.

# afterTrimRow

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

afterUnlisten

Fired after the table was switched off from the listening mode. This makes the Handsontable inert for any keyboard events.

# afterUnmergeCells

Source code (opens new window)

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

Source code (opens new window)

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.

# afterUpdateSettings

Source code (opens new window)

afterUpdateSettings(newSettings)

Fired after calling the updateSettings method.

Param Type Description
newSettings object New settings object.

# afterValidate

Source code (opens new window)

afterValidate(isValid, value, row, prop, [source]) ⇒ void | 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 Visual row index.
prop string
number
Property name / visual column index.
[source] string optional String that identifies source of hook call (list of all available sources).

Returns: void | boolean - If false the cell will be marked as invalid, true otherwise.

# afterViewportColumnCalculatorOverride

Source code (opens new window)

afterViewportColumnCalculatorOverride(calc)

Fired inside the viewportColumnCalculatorOverride method. Allows modifying the row calculator parameters.

Param Type Description
calc object The row calculator.

# afterViewportRowCalculatorOverride

Source code (opens new window)

afterViewportRowCalculatorOverride(calc)

Fired inside the viewportRowCalculatorOverride method. Allows modifying the row calculator parameters.

Param Type Description
calc object The row calculator.

# beforeAddChild

Source code (opens new window)

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.

# beforeAutofill

Source code (opens new window)

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.

Param Type Description
selectionData Array<Array> Data the autofill operation will start from.
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 false, the operation is cancelled. If array of arrays, the returned data will be passed into populateFromArray instead of the default autofill algorithm's result.

# beforeAutofillInsidePopulate

Source code (opens new window)

beforeAutofillInsidePopulate(index, direction, input, deltas)

Deprecated

Fired from the populateFromArray method during the autofill process. Fired for each "autofilled" cell individually.

Param Type Description
index object Object containing row and col properties, defining the number of rows/columns from the initial cell of the autofill.
direction string Declares the direction of the autofill. Possible values: up, down, left, right.
input Array<Array> Contains an array of rows with data being used in the autofill.
deltas Array The deltas array passed to the populateFromArray method.

# beforeCellAlignment

Source code (opens new window)

beforeCellAlignment(stateBefore, range, type, alignmentClass)

Fired before aligning the cell contents.

Param Type Description
stateBefore object An object with class names defining the cell alignment.
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

Source code (opens new window)

beforeChange(changes, [source]) ⇒ void | boolean

Fired before one or more cells is changed. Its main purpose is to alter changes silently after input and before table rendering.

Example

// To disregard a single change, set changes[i] to null or remove it from array using changes.splice(i, 1).
new Handsontable(element, {
  beforeChange: (changes, source) => {
    // [[row, prop, oldVal, newVal], ...]
    changes[0] = null;
  }
});
// To alter a single change, overwrite the desired value to changes[i][3].
new Handsontable(element, {
  beforeChange: (changes, source) => {
    // [[row, prop, oldVal, newVal], ...]
    changes[0][3] = 10;
  }
});
// To cancel all edit, return false from the callback or set array length to 0 (changes.length = 0).
new Handsontable(element, {
  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.
[source] string optional String that identifies source of hook call (list of all available sources).

Returns: void | boolean - If false all changes were cancelled, true otherwise.

# beforeChangeRender

Source code (opens new window)

beforeChangeRender(changes, [source])

Fired right before rendering the changes.

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

Source code (opens new window)

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

Source code (opens new window)

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.

# beforeColumnMove

Source code (opens new window)

beforeColumnMove(movedColumns, finalIndex, dropIndex, movePossible) ⇒ void | boolean

Fired by ManualColumnMove plugin before change order of the visual indexes. This hook is fired when Options#manualColumnMove option is enabled.

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: void | boolean - If false the column will not be moved, true otherwise.

# beforeColumnResize

Source code (opens new window)

beforeColumnResize(newSize, column, isDoubleClick) ⇒ number

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.
column number Visual index of the resized column.
isDoubleClick boolean Flag that determines whether there was a double-click.

Returns: number - Returns a new column size or undefined, if column size should be calculated automatically.

# beforeColumnSort

Source code (opens new window)

beforeColumnSort(currentSortConfig, destinationSortConfigs) ⇒ boolean | void

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.

Param Type Description
currentSortConfig Array Current sort configuration (for all sorted columns).
destinationSortConfigs Array Destination sort configuration (for all sorted columns).

Returns: boolean | void - If false the column will not be sorted, true otherwise.

# beforeContextMenuSetItems

Source code (opens new window)

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

Source code (opens new window)

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 Context Menu instance.

# beforeCopy

Source code (opens new window)

beforeCopy(data, coords) ⇒ *

Fired before values are copied into clipboard.

Example

// To disregard a single row, remove it from array using data.splice(i, 1).
...
new Handsontable(document.getElementById('example'), {
  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.
...
new Handsontable(document.getElementById('example'), {
  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.

Returns: * - If returns false then copying is canceled.

# beforeCreateCol

Source code (opens new window)

beforeCreateCol(index, amount, [source]) ⇒ *

Fired before created a new column.

Example

// Return `false` to cancel column inserting.
new Handsontable(element, {
  beforeCreateCol: function(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).

Returns: * - If false then creating columns is cancelled.

# beforeCreateRow

Source code (opens new window)

beforeCreateRow(index, amount, [source]) ⇒ * | boolean

Fired before 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).

Returns: * | boolean - If false is returned the action is canceled.

# beforeCut

Source code (opens new window)

beforeCut(data, coords) ⇒ *

Fired by CopyPaste plugin before copying the values into clipboard and before clearing values of the selected cells. This hook is fired when Options#copyPaste option is enabled.

Example

// To disregard a single row, remove it from the array using data.splice(i, 1).
new Handsontable(element, {
  beforeCut: function(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`.
new Handsontable(element, {
  beforeCut: function(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.

# beforeDetachChild

Source code (opens new window)

beforeDetachChild(parent, element)

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.

# beforeDrawBorders

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

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.

# beforeFilter

Source code (opens new window)

beforeFilter(conditionsStack) ⇒ boolean

Fired by Filters plugin before applying filtering. This hook is fired when Options#filters option is enabled.

Param Type Description
conditionsStack Array<object> An array of objects with added formulas. js // Example format of the conditionsStack argument: [ { column: 2, conditions: [ {name: 'begins_with', args: [['S']]} ], operation: 'conjunction' }, { column: 4, conditions: [ {name: 'not_empty', args: []} ], operation: 'conjunction' }, ]

Returns: boolean - If hook returns false value then filtering won't be applied on the UI side (server-side filtering).

# beforeGetCellMeta

Source code (opens new window)

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.

# beforeHideColumns

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

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.

# beforeInit

Source code (opens new window)

beforeInit

Fired before the Handsontable instance is initiated.

# beforeInitWalkontable

Source code (opens new window)

beforeInitWalkontable(walkontableConfig)

Fired before the Walkontable instance is initiated.

Param Type Description
walkontableConfig object Walkontable configuration object.

# beforeKeyDown

Source code (opens new window)

beforeKeyDown(event)

Fired before keydown event is handled. It can be used to overwrite default key bindings.

Note: To prevent default behavior you need to call event.stopImmediatePropagation() in your beforeKeyDown handler.

Param Type Description
event Event Original DOM event.

# beforeLanguageChange

Source code (opens new window)

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

Source code (opens new window)

beforeLoadData(sourceData, initialLoad, source) ⇒ Array

Fired before new data is loaded (by loadData or updateSettings method) into the data source array.

Since: 8.0.0

Param Type Description
sourceData Array Array of arrays or array of objects containing data.
initialLoad boolean Flag that determines whether the data has been loaded during the initialization.
source string Source of the call.

Returns: Array - The returned array will be used as new dataset.

# beforeMergeCells

Source code (opens new window)

beforeMergeCells(cellRange, [auto])

Fired by MergeCells plugin before cell merging. 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.

# beforeOnCellContextMenu

Source code (opens new window)

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 TD element.

# beforeOnCellMouseDown

Source code (opens new window)

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 TD element.
controller object An object with keys row, column and cells which contains boolean values. This object allows or disallows changing the selection for the particular axies.

# beforeOnCellMouseOut

Source code (opens new window)

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 TD element.

# beforeOnCellMouseOver

Source code (opens new window)

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 TD element.
controller object An object with keys row, column and cells which contains boolean values. This object allows or disallows changing the selection for the particular axies.

# beforeOnCellMouseUp

Source code (opens new window)

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 TD element.

# beforePaste

Source code (opens new window)

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).
new Handsontable(example, {
  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.
new Handsontable(example, {
  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.

# beforeRedo

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

beforeRefreshDimensions(previousDimensions, currentDimensions, actionPossible) ⇒ undefined | boolean

Cancellable hook, called after resizing a window, but before redrawing a table.

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

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

beforeRemoveCol(index, amount, physicalColumns, [source]) ⇒ * | boolean

Fired before one or more columns are about to be 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

Source code (opens new window)

beforeRemoveRow(index, amount, physicalRows, [source]) ⇒ * | boolean

Fired when one or more rows are about to be 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

Source code (opens new window)

beforeRender(isForced, skipRender)

Fired before the Handsontable table is rendered.

Param Type Description
isForced boolean If true rendering was triggered by a change of settings or data; or false if rendering was triggered by scrolling or moving selection.
skipRender object Object with skipRender property, if it is set to true the next rendering cycle will be skipped.

# beforeRenderer

Source code (opens new window)

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.

# beforeRowMove

Source code (opens new window)

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.

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

Source code (opens new window)

beforeRowResize(newSize, row, isDoubleClick) ⇒ number

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 - Returns the new row size or undefined if row size should be calculated automatically.

# beforeSetCellMeta

Source code (opens new window)

beforeSetCellMeta(row, column, key, value) ⇒ * | boolean

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 - If false is returned the action is canceled.

# beforeSetRangeEnd

Source code (opens new window)

beforeSetRangeEnd(coords)

Fired before setting range is ended.

Param Type Description
coords CellCoords CellCoords instance.

# beforeSetRangeStart

Source code (opens new window)

beforeSetRangeStart(coords)

Fired before setting range is started.

Param Type Description
coords CellCoords CellCoords instance.

# beforeSetRangeStartOnly

Source code (opens new window)

beforeSetRangeStartOnly(coords)

Fired before setting range is started but not finished yet.

Param Type Description
coords CellCoords CellCoords instance.

# beforeStretchingColumnWidth

Source code (opens new window)

beforeStretchingColumnWidth(stretchedWidth, column) ⇒ number

Fired before applying stretched column width to column.

Param Type Description
stretchedWidth number Calculated width.
column number Visual column index.

Returns: number - Returns new width which will be applied to the column element.

# beforeTouchScroll

Source code (opens new window)

beforeTouchScroll

Fired before the logic of handling a touch scroll, when user started scrolling on a touch-enabled device.

# beforeTrimRow

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

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.

# beforeValidate

Source code (opens new window)

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 / column index.
[source] string optional String that identifies source of hook call (list of all available sources).

# beforeValueRender

Source code (opens new window)

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.

# construct

Source code (opens new window)

construct

Fired after Handsontable instance is constructed (using new operator).

# init

Source code (opens new window)

init

Fired after Handsontable instance is initiated but before table is rendered.

# modifyAutoColumnSizeSeed

Source code (opens new window)

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

Source code (opens new window)

modifyAutofillRange(startArea, entireArea)

Fired by Autofill plugin after setting range of autofill. This hook is fired when Options#fillHandle option is enabled.

Param Type Description
startArea Array Array of visual coordinates of the starting point for the drag-down operation ([startRow, startColumn, endRow, endColumn]).
entireArea Array Array of visual coordinates of the entire area of the drag-down operation ([startRow, startColumn, endRow, endColumn]).

# modifyColHeader

Source code (opens new window)

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

Source code (opens new window)

modifyColumnHeaderHeight

Fired while retrieving the column header height.

# modifyColWidth

Source code (opens new window)

modifyColWidth(width, column)

Fired when a column width is about to be modified by a callback function.

Param Type Description
width number Current column width.
column number Visual column index.

# modifyCopyableRange

Source code (opens new window)

modifyCopyableRange(copyableRanges)

Fired to allow modifying the copyable range with a callback function.

Param Type Description
copyableRanges Array<Array> Array of objects defining copyable cells.

# modifyData

Source code (opens new window)

modifyData(row, column, valueHolder, ioMode)

Fired when a data was retrieved or modified.

Param Type Description
row number Physical row height.
column number Physical column index.
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).

# modifyGetCellCoords

Source code (opens new window)

modifyGetCellCoords(row, column, topmost)

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.

# modifyRowData

Source code (opens new window)

modifyRowData(row)

Fired when a data was retrieved or modified.

Param Type Description
row number Physical row index.

# modifyRowHeader

Source code (opens new window)

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.

# modifyRowHeaderWidth

Source code (opens new window)

modifyRowHeaderWidth(rowHeaderWidth)

Fired while retrieving the row header width.

Param Type Description
rowHeaderWidth number Row header width.

# modifyRowHeight

Source code (opens new window)

modifyRowHeight(height, row)

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.

# modifySourceData

Source code (opens new window)

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 Physical column index.
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

Source code (opens new window)

modifyTransformEnd(delta)

Fired when the end of the selection is being modified (e.g. Moving the selection with the arrow keys).

Param Type Description
delta CellCoords Cell coords object declaring the delta of the new selection relative to the previous one.

# modifyTransformStart

Source code (opens new window)

modifyTransformStart(delta)

Fired when the start of the selection is being modified (e.g. Moving the selection with the arrow keys).

Param Type Description
delta CellCoords Cell coords object declaring the delta of the new selection relative to the previous one.

# persistentStateLoad

Source code (opens new window)

persistentStateLoad(key, valuePlaceholder)

Fired by PersistentState plugin, after loading value, saved under given key, from browser local storage. This hook is fired when Options#persistentState option is enabled.

Param Type Description
key string Key.
valuePlaceholder object Object containing the loaded value under valuePlaceholder.value (if no value have been saved, value key will be undefined).

# persistentStateReset

Source code (opens new window)

persistentStateReset([key])

Fired by PersistentState plugin after resetting data from local storage. If no key is given, all values associated with table will be cleared. This hook is fired when Options#persistentState option is enabled.

Param Type Description
[key] string optional Key.

# persistentStateSave

Source code (opens new window)

persistentStateSave(key, value)

Fired by PersistentState plugin, after saving value under given key in browser local storage. This hook is fired when Options#persistentState option is enabled.

Param Type Description
key string Key.
value Mixed Value to save.

# Methods

# add

Source code (opens new window)

hooks.add(key, callback, [context]) ⇒ Hooks

Adds a listener (globally or locally) to a specified hook name. If the context parameter is provided, the hook will be added only to the instance it references. Otherwise, the callback will be used everytime the hook fires on any Handsontable instance. You can provide an array of callback functions as the callback argument, this way they will all be fired once the hook is triggered.

See: Core#addHook
Example

// single callback, added locally
Handsontable.hooks.add('beforeInit', myCallback, hotInstance);

// single callback, added globally
Handsontable.hooks.add('beforeInit', myCallback);

// multiple callbacks, added locally
Handsontable.hooks.add('beforeInit', [myCallback, anotherCallback], hotInstance);

// multiple callbacks, added globally
Handsontable.hooks.add('beforeInit', [myCallback, anotherCallback]);
Param Type Default Description
key string Hook name.
callback function
Array
Callback function or an array of functions.
[context] object null optional The context for the hook callback to be added - a Handsontable instance or leave empty.

Returns: Hooks - Instance of Hooks.

# createEmptyBucket

Source code (opens new window)

hooks.createEmptyBucket() ⇒ object

Returns a new object with empty handlers related to every registered hook name.

Example

Handsontable.hooks.createEmptyBucket();
// Results:
{
...
afterCreateCol: [],
afterCreateRow: [],
beforeInit: [],
...
}

Returns: object - The empty bucket object.

# deregister

Source code (opens new window)

hooks.deregister(key)

Deregisters a hook name (removes it from the list of known hook names).

Example

Handsontable.hooks.deregister('myHook');
Param Type Description
key string The hook name.

# destroy

Source code (opens new window)

hooks.destroy([context])

Destroy all listeners connected to the context. If no context is provided, the global listeners will be destroyed.

Example

// destroy the global listeners
Handsontable.hooks.destroy();

// destroy the local listeners
Handsontable.hooks.destroy(hotInstance);
Param Type Default Description
[context] object null optional A Handsontable instance.

# getBucket

Source code (opens new window)

hooks.getBucket([context]) ⇒ object

Get hook bucket based on the context of the object or if argument is undefined, get the global hook bucket.

Param Type Default Description
[context] object null optional A Handsontable instance.

Returns: object - Returns a global or Handsontable instance bucket.

# getRegistered

Source code (opens new window)

hooks.getRegistered() ⇒ Array

Returns an array of registered hooks.

Example

Handsontable.hooks.getRegistered();

// Results:
[
...
  'beforeInit',
  'beforeRender',
  'beforeSetRangeEnd',
  'beforeDrawBorders',
  'beforeChange',
...
]

Returns: Array - An array of registered hooks.

# has

Source code (opens new window)

hooks.has(key, [context]) ⇒ boolean

Checks whether there are any registered listeners for the provided hook name. If the context parameter is provided, it only checks for listeners assigned to the given Handsontable instance.

Param Type Default Description
key string Hook name.
[context] object null optional A Handsontable instance.

Returns: boolean - true for success, false otherwise.

# isDeprecated

Source code (opens new window)

hooks.isDeprecated(hookName) ⇒ boolean

Returns a boolean value depending on if a hook by such name has been removed or deprecated.

Example

Handsontable.hooks.isDeprecated('skipLengthCache');

// Results:
true
Param Type Description
hookName string The hook name to check.

Returns: boolean - Returns true if the provided hook name was marked as deprecated or removed from API, false otherwise.

# isRegistered

Source code (opens new window)

hooks.isRegistered(hookName) ⇒ boolean

Returns a boolean depending on if a hook by such name has been registered.

Example

Handsontable.hooks.isRegistered('beforeInit');

// Results:
true
Param Type Description
hookName string The hook name to check.

Returns: boolean - true for success, false otherwise.

# once

Source code (opens new window)

hooks.once(key, callback, [context])

Adds a listener to a specified hook. After the hook runs this listener will be automatically removed from the bucket.

See: Core#addHookOnce
Example

Handsontable.hooks.once('beforeInit', myCallback, hotInstance);
Param Type Default Description
key string Hook/Event name.
callback function
Array
Callback function.
[context] object null optional A Handsontable instance.

# register

Source code (opens new window)

hooks.register(key)

Registers a hook name (adds it to the list of the known hook names). Used by plugins. It is not necessary to call register, but if you use it, your plugin hook will be used returned by the getRegistered method. (which itself is used in the demo).

Example

Handsontable.hooks.register('myHook');
Param Type Description
key string The hook name.

# remove

Source code (opens new window)

hooks.remove(key, callback, [context]) ⇒ boolean

Removes a listener from a hook with a given name. If the context argument is provided, it removes a listener from a local hook assigned to the given Handsontable instance.

See: Core#removeHook
Example

Handsontable.hooks.remove('beforeInit', myCallback);
Param Type Default Description
key string Hook/Event name.
callback function Callback function (needs the be the function that was previously added to the hook).
[context] object null optional Handsontable instance.

Returns: boolean - Returns true if hook was removed, false otherwise.

# run

Source code (opens new window)

hooks.run(context, key, [p1], [p2], [p3], [p4], [p5], [p6]) ⇒ *

Runs all local and global callbacks assigned to the hook identified by the key parameter. It returns either a return value from the last called callback or the first parameter (p1) passed to the run function.

See: Core#runHooks
Example

Handsontable.hooks.run(hot, 'beforeInit');
Param Type Description
context object Handsontable instance.
key string Hook/Event name.
[p1] * optional Parameter to be passed as an argument to the callback function.
[p2] * optional Parameter to be passed as an argument to the callback function.
[p3] * optional Parameter to be passed as an argument to the callback function.
[p4] * optional Parameter to be passed as an argument to the callback function.
[p5] * optional Parameter to be passed as an argument to the callback function.
[p6] * optional Parameter to be passed as an argument to the callback function.

Returns: * - Either a return value from the last called callback or p1.

Last Updated: Jul 8, 2021