/ S

JavaScript Data Grid Hooks

In this article

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<Array> 2D array containing information about each of the edited cells [[row, prop, oldVal, newVal], ...]. row is a visual row index.
[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.

afterColumnFreeze

Source code (opens new window)

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

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.

afterColumnSequenceChange

Source code (opens new window)

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

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

afterColumnUnfreeze

Source code (opens new window)

afterColumnUnfreeze(column, unfreezePerformed)

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.

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, 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

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

afterDeselect

Source code (opens new window)

afterDeselect

Fired after all selected cells are deselected.

afterDestroy

Source code (opens new window)

afterDestroy

Fired after destroying the Handsontable instance.

afterDetachChild

Source code (opens new window)

afterDetachChild(parent, element, finalElementPosition)

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.

afterDocumentKeyDown

Source code (opens new window)

afterDocumentKeyDown(event)

Hook fired after keydown event is handled.

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 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 visual 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:

Param Type Description
conditionsStack Array<object> An array of objects with your column filters.

afterFormulasValuesUpdate

Source code (opens new window)

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.

Read more:

Since: 9.0.0

Param Type Description
changes Array The addresses and new values of all the changed and recalculated cells.

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, [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.
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

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 Handsontable's data gets modified by the loadData() method or the updateSettings() method.

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

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)

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

Fired 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 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

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 or the size of the Handsontable root element was changed.

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 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 scrolling or moving the 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.

afterRowSequenceChange

Source code (opens new window)

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.

afterScroll

Source code (opens new window)

afterScroll

Fired after the vertical or horizontal scroll event.

Since: 14.0.0

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.

afterSelectColumns

Source code (opens new window)

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

Source code (opens new window)

afterSelection(row, column, row2, column2, preventScrolling, 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) => {
    // 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.
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.

afterSelectRows

Source code (opens new window)

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

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)

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

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

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

afterUpdateData

Source code (opens new window)

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

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]) ⇒ 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 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: undefined | 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.

afterViewRender

Source code (opens new window)

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

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.

beforeBeginEditing

Source code (opens new window)

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

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

Example

// to alter a single change, overwrite the value with `changes[i][3]`
new Handsontable(element, {
  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)`
new Handsontable(element, {
  beforeChange: (changes, source) => {
    // [[row, prop, oldVal, newVal], ...]
    changes[0] = null;
  }
});

// to ignore all changes, return `false`
// or set the array's length to 0, by using `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 [[row, prop, oldVal, newVal], ...]. row is a visual row index.
[source] string optional String that identifies source of hook call (list of all available sources).

Returns: undefined | 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.

beforeColumnFreeze

Source code (opens new window)

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

Source code (opens new window)

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.

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

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

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

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

beforeColumnUnfreeze

Source code (opens new window)

beforeColumnUnfreeze(column, unfreezePerformed) ⇒ 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).

Returns: boolean | undefined - If false: the column is not going to unfreeze, and the afterColumnUnfreeze hook won't fire.

beforeColumnWrap

Source code (opens new window)

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.

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, copiedHeadersCount) ⇒ *

Fired before values are copied to the 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.
copiedHeadersCount Object (Since 12.3.0) The number of copied column headers.

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 to the 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 the Filters plugin, before a column filter gets applied.

beforeFilter 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 visual 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:

Param Type Description
conditionsStack Array<object> An array of objects with your column filters.

Returns: boolean - To perform server-side filtering (i.e., to not apply filtering to Handsontable's UI), return false.

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)

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

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

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 properties row, column and cell. Each property contains a boolean value that allows or disallows changing the selection for that particular area.

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 properties row, column and cell. Each property contains a boolean value that allows or disallows changing the selection for that particular area.

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 or after detecting size change of the Handsontable root element, 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)

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 scrolling or moving the selection.

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

beforeRowWrap

Source code (opens new window)

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.

beforeSelectColumns

Source code (opens new window)

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

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

beforeSelectionHighlightSet

Source code (opens new window)

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 Arrow Left when there's no further movement possible.

Since: 14.0.0

beforeSelectRows

Source code (opens new window)

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

new Handsontable(element, {
  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

Source code (opens new window)

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

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

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.

beforeUpdateData

Source code (opens new window)

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

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.

beforeViewportScroll

Source code (opens new window)

beforeViewportScroll

Fired before the vertical or horizontal viewport scroll. Triggered by the scrollViewportTo() method or table internals.

Since: 14.0.0

beforeViewportScrollHorizontally

Source code (opens new window)

beforeViewportScrollHorizontally(visualColumn) ⇒ number | boolean

Fired before the horizontal viewport scroll. Triggered by the scrollViewportTo() method or table internals.

Since: 14.0.0

Param Type Description
visualColumn number Visual column index.

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

Source code (opens new window)

beforeViewportScrollVertically(visualRow) ⇒ number | boolean

Fired before the vertical viewport scroll. Triggered by the scrollViewportTo() method or table internals.

Since: 14.0.0

Param Type Description
visualRow number Visual row index.

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

Source code (opens new window)

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.

construct

Source code (opens new window)

construct

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

globalBucket

Source code (opens new window)

hooks.globalBucket : object

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.

modifyColumnHeaderValue

Source code (opens new window)

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

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 index.
column number Visual 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).

modifyFiltersMultiSelectValue

Source code (opens new window)

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

Source code (opens new window)

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

Source code (opens new window)

modifyFocusOnTabNavigation(tabActivationDir, visualCoords)

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.

modifyGetCellCoords

Source code (opens new window)

modifyGetCellCoords(row, column, topmost) ⇒ 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.

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 or property name.
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.

The persistentStateLoad hook is fired even when the Options#persistentState option is disabled.

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.

The persistentStateSave hook is fired even when the Options#persistentState option is disabled.

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 update: Nov 20, 2024

← Configuration options →