JavaScript Data GridHooks

On this page

• Members
  • afterAddChild
  • afterAutofill
  • afterBeginEditing
  • afterCellMetaReset
  • afterChange
  • afterColumnCollapse
  • afterColumnExpand
  • afterColumnFreeze
  • afterColumnMove
  • afterColumnResize
  • afterColumnSequenceChange
  • afterColumnSort
  • afterColumnUnfreeze
  • afterContextMenuDefaultOptions
  • afterContextMenuHide
  • afterContextMenuShow
  • afterCopy
  • afterCopyLimit
  • afterCreateCol
  • afterCreateRow
  • afterCut
  • afterDeselect
  • afterDestroy
  • afterDetachChild
  • afterDocumentKeyDown
  • afterDrawSelection
  • afterDropdownMenuDefaultOptions
  • afterDropdownMenuHide
  • afterDropdownMenuShow
  • afterFilter
  • afterFormulasValuesUpdate
  • afterGetCellMeta
  • afterGetColHeader
  • afterGetColumnHeaderRenderers
  • afterGetRowHeader
  • afterGetRowHeaderRenderers
  • afterHideColumns
  • afterHideRows
  • afterInit
  • afterLanguageChange
  • afterListen
  • afterLoadData
  • afterMergeCells
  • afterModifyTransformEnd
  • afterModifyTransformFocus
  • afterModifyTransformStart
  • afterMomentumScroll
  • afterNamedExpressionAdded
  • afterNamedExpressionRemoved
  • afterOnCellContextMenu
  • afterOnCellCornerDblClick
  • afterOnCellCornerMouseDown
  • afterOnCellMouseDown
  • afterOnCellMouseOut
  • afterOnCellMouseOver
  • afterOnCellMouseUp
  • afterPaste
  • afterPluginsInitialized
  • afterRedo
  • afterRedoStackChange
  • afterRefreshDimensions
  • afterRemoveCellMeta
  • afterRemoveCol
  • afterRemoveRow
  • afterRender
  • afterRenderer
  • afterRowMove
  • afterRowResize
  • afterRowSequenceChange
  • afterScroll
  • afterScrollHorizontally
  • afterScrollVertically
  • afterSelectColumns
  • afterSelection
  • afterSelectionByProp
  • afterSelectionEnd
  • afterSelectionEndByProp
  • afterSelectionFocusSet
  • afterSelectRows
  • afterSetCellMeta
  • afterSetDataAtCell
  • afterSetDataAtRowProp
  • afterSetSourceDataAtCell
  • afterSheetAdded
  • afterSheetRemoved
  • afterSheetRenamed
  • afterTrimRow
  • afterUndo
  • afterUndoStackChange
  • afterUnhideColumns
  • afterUnhideRows
  • afterUnlisten
  • afterUnmergeCells
  • afterUntrimRow
  • afterUpdateData
  • afterUpdateSettings
  • afterValidate
  • afterViewportColumnCalculatorOverride
  • afterViewportRowCalculatorOverride
  • afterViewRender
  • beforeAddChild
  • beforeAutofill
  • beforeBeginEditing
  • beforeCellAlignment
  • beforeChange
  • beforeChangeRender
  • beforeColumnCollapse
  • beforeColumnExpand
  • beforeColumnFreeze
  • beforeColumnMove
  • beforeColumnResize
  • beforeColumnSort
  • beforeColumnUnfreeze
  • beforeColumnWrap
  • beforeContextMenuSetItems
  • beforeContextMenuShow
  • beforeCopy
  • beforeCreateCol
  • beforeCreateRow
  • beforeCut
  • beforeDetachChild
  • beforeDrawBorders
  • beforeDropdownMenuSetItems
  • beforeDropdownMenuShow
  • beforeFilter
  • beforeGetCellMeta
  • beforeHideColumns
  • beforeHideRows
  • beforeHighlightingColumnHeader
  • beforeHighlightingRowHeader
  • beforeInit
  • beforeInitWalkontable
  • beforeKeyDown
  • beforeLanguageChange
  • beforeLoadData
  • beforeMergeCells
  • beforeOnCellContextMenu
  • beforeOnCellMouseDown
  • beforeOnCellMouseOut
  • beforeOnCellMouseOver
  • beforeOnCellMouseUp
  • beforePaste
  • beforeRedo
  • beforeRedoStackChange
  • beforeRefreshDimensions
  • beforeRemoveCellClassNames
  • beforeRemoveCellMeta
  • beforeRemoveCol
  • beforeRemoveRow
  • beforeRender
  • beforeRenderer
  • beforeRowMove
  • beforeRowResize
  • beforeRowWrap
  • beforeSelectColumns
  • beforeSelectionFocusSet
  • beforeSelectionHighlightSet
  • beforeSelectRows
  • beforeSetCellMeta
  • beforeSetRangeEnd
  • beforeSetRangeStart
  • beforeSetRangeStartOnly
  • beforeStretchingColumnWidth
  • beforeTouchScroll
  • beforeTrimRow
  • beforeUndo
  • beforeUndoStackChange
  • beforeUnhideColumns
  • beforeUnhideRows
  • beforeUnmergeCells
  • beforeUntrimRow
  • beforeUpdateData
  • beforeValidate
  • beforeValueRender
  • beforeViewportScroll
  • beforeViewportScrollHorizontally
  • beforeViewportScrollVertically
  • beforeViewRender
  • construct
  • globalBucket
  • init
  • modifyAutoColumnSizeSeed
  • modifyAutofillRange
  • modifyColHeader
  • modifyColumnHeaderHeight
  • modifyColumnHeaderValue
  • modifyColWidth
  • modifyCopyableRange
  • modifyData
  • modifyFiltersMultiSelectValue
  • modifyFocusedElement
  • modifyFocusOnTabNavigation
  • modifyGetCellCoords
  • modifyRowData
  • modifyRowHeader
  • modifyRowHeaderWidth
  • modifyRowHeight
  • modifyRowHeightByOverlayName
  • modifySourceData
  • modifyTransformEnd
  • modifyTransformFocus
  • modifyTransformStart
  • persistentStateLoad
  • persistentStateReset
  • persistentStateSave
• Methods
  • add
  • createEmptyBucket
  • deregister
  • destroy
  • getBucket
  • getRegistered
  • has
  • isDeprecated
  • isRegistered
  • once
  • register
  • remove
  • run

Members

afterAddChild

Source code

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

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

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

afterCellMetaReset

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

afterChange

Source code

afterChange(changes, [source])

Fired after one or more cells has been changed. The changes are triggered in any situation when the value is entered using an editor or changed using API (e.q setDataAtCell method).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

afterDeselect

Fired after all selected cells are deselected.

afterDestroy

Source code

afterDestroy

Fired after destroying the Handsontable instance.

afterDetachChild

Source code

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

afterDocumentKeyDown(event)

Hook fired after keydown event is handled.

Param	Type	Description
event	Event	A native keydown event object.

afterDrawSelection

Source code

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

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

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

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

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:

• Guides: Column filter
• Hooks: beforeFilter
• Options: filters
• Plugins: Filters – Plugin methods: addCondition()

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

afterFormulasValuesUpdate

Source code

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:

• Guides: Formula calculation
• HyperFormula documentation: valuesUpdated (opens new window)

Since: 9.0.0

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

afterGetCellMeta

Source code

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

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

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

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

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

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

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

afterInit

Fired after the Handsontable instance is initiated.

afterLanguageChange

Source code

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

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

afterLoadData(sourceData, initialLoad, source)

Fired after Handsontable's data gets modified by the loadData() method or the updateSettings() method.

Read more:

• Binding to data
• Saving data

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

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

afterModifyTransformEnd(coords, rowTransformDir, colTransformDir)

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

Param	Type	Description
coords	CellCoords	Visual coords of the freshly selected cell.
rowTransformDir	number	-1 if trying to select a cell with a negative row index. 0 otherwise.
colTransformDir	number	-1 if trying to select a cell with a negative column index. 0 otherwise.

afterModifyTransformFocus

Source code

afterModifyTransformFocus(coords, rowTransformDir, colTransformDir)

Fired after the focus of the selection is being modified (e.g. Moving the focus with the enter/tab keys).

Since: 14.3.0

Param	Type	Description
coords	CellCoords	Coords of the freshly focused cell.
rowTransformDir	number	-1 if trying to focus a cell with a negative row index. 0 otherwise.
colTransformDir	number	-1 if trying to focus a cell with a negative column index. 0 otherwise.

afterModifyTransformStart

Source code

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

afterMomentumScroll

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

afterNamedExpressionAdded

Source code

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

afterScroll

Fired after the vertical or horizontal scroll event.

Since: 14.0.0

afterScrollHorizontally

Source code

afterScrollHorizontally

Fired after the horizontal scroll event.

afterScrollVertically

Source code

afterScrollVertically

Fired after the vertical scroll event.

afterSelectColumns

Source code

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

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

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

Example

new Handsontable(element, {
  afterSelection: (row, column, row2, column2, preventScrolling, selectionLayerLevel) => {
    // If set to `false` (default): when cell selection is outside the viewport,
    // Handsontable scrolls the viewport to cell selection's end corner.
    // If set to `true`: when cell selection is outside the viewport,
    // Handsontable doesn't scroll to cell selection's end corner.
    preventScrolling.value = true;
  }
})

Param	Type	Description
row	number	Selection start visual row index.
column	number	Selection start visual column index.
row2	number	Selection end visual row index.
column2	number	Selection end visual column index.
preventScrolling	object	A reference to the observable object with the value property. Property preventScrolling.value expects a boolean value that Handsontable uses to control scroll behavior after selection.
selectionLayerLevel	number	The number which indicates what selection layer is currently modified.

afterSelectionByProp

Source code

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	A reference to the observable object with the value property. Property preventScrolling.value expects a boolean value that Handsontable uses to control scroll behavior after selection.
selectionLayerLevel	number	The number which indicates what selection layer is currently modified.

afterSelectionEnd

Source code

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

afterSelectionEndByProp(row, prop, row2, prop2, selectionLayerLevel)

Fired after one or more cells are selected (e.g. on mouse up).

The prop and prop2 arguments represent the source object property name instead of the column number.

Param	Type	Description
row	number	Selection start visual row index.
prop	string	Selection start data source object property index.
row2	number	Selection end visual row index.
prop2	string	Selection end data source object property index.
selectionLayerLevel	number	The number which indicates what selection layer is currently modified.

afterSelectionFocusSet

Source code

afterSelectionFocusSet(row, column, preventScrolling)

Fired after the focus position within a selected range is changed.

Since: 14.3.0
Example

new Handsontable(element, {
  afterSelectionFocusSet: (row, column, preventScrolling) => {
    // If set to `false` (default): when focused cell selection is outside the viewport,
    // Handsontable scrolls the viewport to that cell.
    // If set to `true`: when focused cell selection is outside the viewport,
    // Handsontable doesn't scroll the viewport.
    preventScrolling.value = true;
  }
})

Param	Type	Description
row	number	The focus visual row index position.
column	number	The focus visual column index position.
preventScrolling	object	A reference to the observable object with the value property. Property preventScrolling.value expects a boolean value that Handsontable uses to control scroll behavior after selection.

afterSelectRows

Source code

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

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

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

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

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

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

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

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

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

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

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

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

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

afterUnlisten

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

afterUnmergeCells

Source code

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

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

afterUpdateData(sourceData, initialLoad, source)

Fired after the updateData() method modifies Handsontable's data.

Read more:

• Binding to data
• Saving data

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

afterUpdateSettings(newSettings)

Fired after calling the updateSettings method.

Param	Type	Description
newSettings	object	New settings object.

afterValidate

Source code

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

afterViewportColumnCalculatorOverride(calc)

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

Param	Type	Description
calc	object	The row calculator.

afterViewportRowCalculatorOverride

Source code

afterViewportRowCalculatorOverride(calc)

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

Param	Type	Description
calc	object	The row calculator.

afterViewRender

Source code

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

beforeFilter(conditionsStack, previousConditionsStack) ⇒ boolean

Fired by the Filters plugin, before a column filter gets applied.

beforeFilter takes two arguments: conditionsStack and previousConditionsStack, both are arrays of objects.

Each object represents one of your column filters, and consists of the following properties:

Property	Possible values	Description
column	Number	A 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:

• Guides: Column filter
• Hooks: afterFilter
• Options: filters
• Plugins: Filters – Plugin methods: addCondition()

Param	Type	Description
conditionsStack	Array<object>	An array of objects with your column filters.
previousConditionsStack	Array<object> null	An array of objects with your previous column filters. It can also be null if there was no previous filters applied or the conditions did not change between performing the filter action.

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

beforeGetCellMeta

Source code

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

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

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

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

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

beforeInit

Fired before the Handsontable instance is initiated.

beforeInitWalkontable

Source code

beforeInitWalkontable(walkontableConfig)

Fired before the Walkontable instance is initiated.

Param	Type	Description
walkontableConfig	object	Walkontable configuration object.

beforeKeyDown

Source code

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

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

beforeLoadData(sourceData, initialLoad, source) ⇒ Array

Fired before Handsontable's data gets modified by the loadData() method or the updateSettings() method.

Read more:

• Binding to data
• Saving data

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

beforeSelectionFocusSet

Source code

beforeSelectionFocusSet(coords)

Fired before setting focus selection.

Since: 14.3.0

Param	Type	Description
coords	CellCoords	CellCoords instance.

beforeSelectionHighlightSet

Source code

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

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

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

beforeSetRangeEnd(coords)

Fired before setting range is ended.

Param	Type	Description
coords	CellCoords	CellCoords instance.

beforeSetRangeStart

Source code

beforeSetRangeStart(coords)

Fired before setting range is started.

Param	Type	Description
coords	CellCoords	CellCoords instance.

beforeSetRangeStartOnly

Source code

beforeSetRangeStartOnly(coords)

Fired before setting range is started but not finished yet.

Param	Type	Description
coords	CellCoords	CellCoords instance.

beforeStretchingColumnWidth

Source code

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

beforeTouchScroll

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

beforeTrimRow

Source code

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

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

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

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

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

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

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

beforeUpdateData(sourceData, initialLoad, source) ⇒ Array

Fired before the updateData() method modifies Handsontable's data.

Read more:

• Binding to data
• Saving data

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

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

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

beforeViewportScroll

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

Since: 14.0.0

beforeViewportScrollHorizontally

Source code

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

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

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

construct

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

globalBucket

Source code

hooks.globalBucket : object

init

Source code

init

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

modifyAutoColumnSizeSeed

Source code

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

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

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

modifyColumnHeaderHeight

Fired while retrieving the column header height.

modifyColumnHeaderValue

Source code

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

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

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

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

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

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

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

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

modifyRowData(row)

Fired when a data was retrieved or modified.

Param	Type	Description
row	number	Physical row index.

modifyRowHeader

Source code

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

modifyRowHeaderWidth(rowHeaderWidth)

Fired while retrieving the row header width.

Param	Type	Description
rowHeaderWidth	number	Row header width.

modifyRowHeight

Source code

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.

modifyRowHeightByOverlayName

Source code

modifyRowHeightByOverlayName(height, row, overlayName)

Fired when a row height is about to be modified by a callback function. The hook allows to change the row height for the specified overlay type.

Since: 14.5.0

Param	Type	Description
height	number	Row height.
row	number	Visual row index.
overlayName	'inline_start' 'top' 'top_inline_start_corner' 'bottom' 'bottom_inline_start_corner' 'master'	Overlay name.

modifySourceData

Source code

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

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.

modifyTransformFocus

Source code

modifyTransformFocus(delta)

Fired when the focus of the selection is being modified (e.g. Moving the focus with the enter/tab keys).

Since: 14.3.0

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

modifyTransformStart

Source code

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

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

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

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

hooks.add(key, callback, [context], [orderIndex]) ⇒ 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.
[orderIndex]	number		optional Order index of the callback. If > 0, the callback will be added after the others, for example, with an index of 1, the callback will be added before the ones with an index of 2, 3, etc., but after the ones with an index of 0 and lower. If < 0, the callback will be added before the others, for example, with an index of -1, the callback will be added after the ones with an index of -2, -3, etc., but before the ones with an index of 0 and higher. If 0 or no order index is provided, the callback will be added between the "negative" and "positive" indexes.

Returns: Hooks - Instance of Hooks.

createEmptyBucket

Source code

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

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

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

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

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

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

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

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

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

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.
[orderIndex]	number		optional Order index of the callback. If > 0, the callback will be added after the others, for example, with an index of 1, the callback will be added before the ones with an index of 2, 3, etc., but after the ones with an index of 0 and lower. If < 0, the callback will be added before the others, for example, with an index of -1, the callback will be added after the ones with an index of -2, -3, etc., but before the ones with an index of 0 and higher. If 0 or no order index is provided, the callback will be added between the "negative" and "positive" indexes.

register

Source code

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

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

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.