Class: Hooks

Hooks

Methods

add(key, callback, context){Hooks}

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

Parameters:
Name Type Default Description
key String

Hook name.

callback function | Array

Callback function or an array of functions.

context Object optional

The context for the hook callback to be added - a Handsontable instance or leave empty.

See:
Returns: {Hooks} Instance of Hooks.
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]);

createEmptyBucket(){Object}

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

Returns: {Object} The empty bucket object.
Example
Handsontable.hooks.createEmptyBucket();
// Results:
{
...
afterCreateCol: [],
afterCreateRow: [],
beforeInit: [],
...
}

deregister(key)

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

Parameters:
Name Type Description
key String

Hook name.

Example
Handsontable.hooks.deregister('myHook');

destroy(context)

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

Parameters:
Name Type Default Description
context Object optional

A Handsontable instance.

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

// destroy the local listeners
Handsontable.hooks.destroy(hotInstance);

getBucket(context){Object}

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

Parameters:
Name Type Default Description
context Object optional

A Handsontable instance.

Returns: {Object} Returns a global or Handsontable instance bucket.

getRegistered(){Array}

Returns an array of registered hooks.

Returns: {Array} An array of registered hooks.
Example
Handsontable.hooks.getRegistered();

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

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.

Parameters:
Name Type Default Description
key String

Hook name.

context Object optional

A Handsontable instance.

Returns: {Boolean} true for success, false otherwise.

isRegistered(key){Boolean}

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

Parameters:
Name Type Description
key String

Hook name.

Returns: {Boolean} true for success, false otherwise.
Example
Handsontable.hooks.isRegistered('beforeInit');

// Results:
true

once(key, callback, context)

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

Parameters:
Name Type Default Description
key String

Hook/Event name.

callback function | Array

Callback function.

context Object optional

A Handsontable instance.

See:
Example
Handsontable.hooks.once('beforeInit', myCallback, hotInstance);

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 https://handsontable.com/docs/tutorial-callbacks.html).

Parameters:
Name Type Description
key String

The hook name.

Example
Handsontable.hooks.register('myHook');

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.

Parameters:
Name 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 optional

Handsontable instance.

See:
Returns: {Boolean} Returns true if hook was removed, false otherwise.
Example
Handsontable.hooks.remove('beforeInit', myCallback);

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.

Parameters:
Name 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.

See:
Returns: {*} Either a return value from the last called callback or p1.
Example
Handsontable.hooks.run(hot, 'beforeInit');

Events

afterAddChild

Fired by NestedRows plugin after adding a children to the NestedRows structure. This hook is fired when
Options#nestedRows option is enabled.

Parameters:
Name 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.

afterBeginEditing

Fired after the editor is opened and rendered.

Parameters:
Name Type Description
row Number

Visual row index of the edited cell.

column Number

Visual column index of the edited cell.

afterCellMetaReset

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

afterChange

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

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

Parameters:
Name Type Description
changes Array

2D array containing information about each of the edited cells [[row, prop, oldVal, newVal], ...].

source String optional

String that identifies source of hook call (list of all available sources).

Example
new Handsontable(element, {
  afterChange: (changes) => {
    changes.forEach(([row, prop, oldValue, newValue]) => {
      // Some logic...
    });
  }
})

afterChangesObserved

Fired by ObserveChanges plugin after detecting changes in the data source. This hook is fired when
Options#observeChanges option is enabled.

afterColumnMove

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

Parameters:
Name Type Description
columns Array.<Number>

Array of visual column indexes that were moved.

target Number

Visual column index being a target for moved columns.

afterColumnResize

Fired by ManualColumnResize plugin after rendering the table with modified column sizes. This hook is
fired when Options#manualColumnResize option is enabled.

Parameters:
Name Type Description
currentColumn Number

Visual index of the resized column.

newSize Number

Calculated new column width.

isDoubleClick Boolean

Flag that determines whether there was a double-click.

afterColumnSort

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

Parameters:
Name Type Description
currentSortConfig Array

Current sort configuration (for all sorted columns).

destinationSortConfigs Array

Destination sort configuration (for all sorted columns).

afterContextMenuDefaultOptions

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

Parameters:
Name Type Description
predefinedItems Array

An array of objects containing information about the pre-defined Context Menu items.

afterContextMenuHide

Fired by ContextMenu plugin after hiding the Context Menu. This hook is fired when Options#contextMenu
option is enabled.

Parameters:
Name Type Description
context Object

The Context Menu plugin instance.

afterContextMenuShow

Fired by ContextMenu plugin after opening the Context Menu. This hook is fired when Options#contextMenu
option is enabled.

Parameters:
Name Type Description
context Object

The Context Menu plugin instance.

afterCopy

Fired by CopyPaste plugin after data are pasted into table. This hook is fired when Options#copyPaste
option is enabled.

Parameters:
Name Type Description
data Array.<Array>

An array of arrays which contains the copied data.

coords Array.<Object>

An array of objects with ranges of the visual indexes (startRow, startCol, endRow, endCol)
which was copied.

afterCopyLimit

Fired by CopyPaste plugin after reaching the copy limit while copying data. This hook is fired when
Options#copyPaste option is enabled.

Parameters:
Name 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

Fired after created a new column.

Parameters:
Name 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

Fired after created a new row.

Parameters:
Name 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

Fired by CopyPaste plugin after data was cut out from the table. This hook is fired when
Options#copyPaste option is enabled.

Parameters:
Name Type Description
data Array.<Array>

An array of arrays which contains the cutted out data.

coords Array.<Object>

An array of objects with ranges of the visual indexes (startRow, startCol, endRow, endCol)
which was cut out.

afterDeselect

Fired after the current cell is deselected.

afterDestroy

Fired after destroying the Handsontable instance.

afterDetachChild

Fired by NestedRows plugin after detaching a child from its parent. This hook is fired when
Options#nestedRows option is enabled.

Parameters:
Name Type Description
parent Object

An object representing the parent from which the element was detached.

element Object

The detached element.

afterDocumentKeyDown

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

Parameters:
Name Type Description
event Event

A native keydown event object.

afterDrawSelection

Fired inside the Walkontable's selection draw method. Can be used to add additional class names to cells, depending on the current selection.

Parameters:
Name 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.

Since: 0.38.1
Returns: {String|undefined} Can return a String, which will act as an additional className to be added to the currently processed cell.

afterDropdownMenuDefaultOptions

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.

Parameters:
Name Type Description
predefinedItems Array.<Object>

An array of objects containing information about the pre-defined Context Menu items.

afterDropdownMenuHide

Fired by DropdownMenu plugin after hiding the Dropdown Menu. This hook is fired when Options#dropdownMenu
option is enabled.

Parameters:
Name Type Description
instance DropdownMenu

The DropdownMenu instance.

afterDropdownMenuShow

Fired by DropdownMenu plugin after opening the Dropdown Menu. This hook is fired when Options#dropdownMenu
option is enabled.

Parameters:
Name Type Description
dropdownMenu DropdownMenu

The DropdownMenu instance.

afterFilter

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

Parameters:
Name Type Description
conditionsStack Array.<Object>

An array of objects with added conditions.

// Example format of the conditionsStack argument:
[
  {
    column: 2,
    conditions: [
      {name: 'begins_with', args: [['S']]}
    ],
    operation: 'conjunction'
  },
  {
    column: 4,
    conditions: [
      {name: 'not_empty', args: []}
    ],
    operation: 'conjunction'
  },
]

afterGetCellMeta

Fired after getting the cell settings.

Parameters:
Name Type Description
row Number

Visual row index.

column Number

Visual column index.

cellProperties Object

Object containing the cell properties.

afterGetColHeader

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

Parameters:
Name Type Description
column Number

Visual column index.

TH HTMLTableCellElement

Header's TH element.

afterGetColumnHeaderRenderers

Fired after getting the column header renderers.

Parameters:
Name Type Description
renderers Array.<function()>

An array of the column header renderers.

afterGetRowHeader

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

Parameters:
Name Type Description
row Number

Visual row index.

TH HTMLTableCellElement

Header's TH element.

afterGetRowHeaderRenderers

Fired after getting the row header renderers.

Parameters:
Name Type Description
renderers Array.<function()>

An array of the row header renderers.

afterInit

Fired after the Handsontable instance is initiated.

afterLanguageChange

Fired after successful change of language (when proper language code was set).

Parameters:
Name Type Description
languageCode String

New language code.

Since: 0.35.0

afterListen

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

afterLoadData

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

Parameters:
Name Type Description
initialLoad Boolean

flag that determines whether the data has been loaded during the initialization.

afterMergeCells

Fired by MergeCells plugin after cell merging. This hook is fired when Options#mergeCells
option is enabled.

Parameters:
Name 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

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

Parameters:
Name Type Description
coords CellCoords

Visual coords of the freshly selected cell.

rowTransformDir Number

-1 if trying to select a cell with a negative row index. 0 otherwise.

colTransformDir Number

-1 if trying to select a cell with a negative column index. 0 otherwise.

afterModifyTransformStart

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

Parameters:
Name 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

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

afterOnCellContextMenu

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

Parameters:
Name 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.

Since: 4.1.0

afterOnCellCornerDblClick

Fired after a dblclick event is triggered on the cell corner (the drag handle).

Parameters:
Name Type Description
event Event

dblclick event object.

afterOnCellCornerMouseDown

Fired after a mousedown event is triggered on the cell corner (the drag handle).

Parameters:
Name Type Description
event Event

mousedown event object.

afterOnCellMouseDown

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

Parameters:
Name 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

Fired after leaving a cell or row/column header with the mouse cursor.

Parameters:
Name Type Description
event Event

mouseout event object.

coords CellCoords

Leaved cell's visual coordinate object.

TD HTMLTableCellElement

Cell's TD (or TH) element.

afterOnCellMouseOver

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

Parameters:
Name Type Description
event Event

mouseover event object.

coords CellCoords

Hovered cell's visual coordinate object.

TD HTMLTableCellElement

Cell's TD (or TH) element.

afterPaste

Fired by CopyPaste plugin after values are pasted into table. This hook is fired when
Options#copyPaste option is enabled.

Parameters:
Name Type Description
data Array.<Array>

An array of arrays which contains the pasted data.

coords Array.<Object>

An array of objects with ranges of the visual indexes (startRow, startCol, endRow, endCol)
that correspond to the previously selected area.

afterPluginsInitialized

Fired after initializing all the plugins.

afterRedo

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.

Parameters:
Name 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').

afterRemoveCellMeta

Fired after cell meta is removed.

Parameters:
Name 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

Fired after one or more columns are removed.

Parameters:
Name 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

Fired after one or more rows are removed.

Parameters:
Name 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

Fired after the Handsontable table is rendered.

Parameters:
Name Type Description
isForced Boolean

Is true if rendering was triggered by a change of settings or data; or false if
rendering was triggered by scrolling or moving selection.

afterRenderer

Fired after finishing rendering the cell (after the renderer finishes).

Parameters:
Name 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

Fired by ManualRowMove plugin after change order of the visual indexes. This hook is fired when
Options#manualRowMove option is enabled.

Parameters:
Name Type Description
rows Array.<Number>

An array of visual row indexes that were moved.

target Number

Visual row index being a target for moved rows.

afterRowResize

Fired by ManualRowResize plugin after rendering the table with modified row sizes. This hook is
fired when Options#manualRowResize option is enabled.

Parameters:
Name Type Description
currentRow Number

Visual index of the resized row.

newSize Number

Calculated new row height.

isDoubleClick Boolean

Flag that determines whether there was a double-click.

afterScrollHorizontally

Fired after the horizontal scroll event.

afterScrollVertically

Fired after the vertical scroll event.

afterSelection

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

Parameters:
Name Type Description
row Number

Selection start visual row index.

column Number

Selection start visual column index.

row2 Number

Selection end visual row index.

column2 Number

Selection end visual column index.

preventScrolling Object

Object with value property where its value change will be observed.

selectionLayerLevel Number

The number which indicates what selection layer is currently modified.

Example
new Handsontable(element, {
  afterSelection: (row, column, row2, column2, preventScrolling, selectionLayerLevel) => {
    // setting if prevent scrolling after selection
    preventScrolling.value = true;
  }
})

afterSelectionByProp

Fired after one or more cells are selected.

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

Parameters:
Name Type Description
row Number

Selection start visual row index.

prop String

Selection start data source object property name.

row2 Number

Selection end visual row index.

prop2 String

Selection end data source object property name.

preventScrolling Object

Object with value property where its value change will be observed.

selectionLayerLevel Number

The number which indicates what selection layer is currently modified.

Example
new Handsontable(element, {
  afterSelectionByProp: (row, column, row2, column2, preventScrolling, selectionLayerLevel) => {
    // setting if prevent scrolling after selection
    preventScrolling.value = true;
  }
})

afterSelectionEnd

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

Parameters:
Name 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

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.

Parameters:
Name Type Description
row Number

Selection start visual row index.

prop String

Selection start data source object property index.

row2 Number

Selection end visual row index.

prop2 String

Selection end data source object property index.

selectionLayerLevel Number

The number which indicates what selection layer is currently modified.

afterSetCellMeta

Fired after cell meta is changed.

Parameters:
Name Type Description
row Number

Visual row index.

column Number

Visual column index.

key String

The updated meta key.

value *

The updated meta value.

afterSetDataAtCell

Fired after cell data was changed.

Parameters:
Name 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

Fired after cell data was changed.

Parameters:
Name 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).

afterTrimRow

Fired by TrimRows plugin after trimming rows. This hook is fired when Options#trimRows option is enabled.

Parameters:
Name Type Description
rows Array.<Number>

Physical indexes of trimmed rows.

afterUndo

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.

Parameters:
Name 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').

afterUnlisten

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

afterUnmergeCells

Fired by MergeCells plugin after unmerging the cells. This hook is fired when Options#mergeCells
option is enabled.

Parameters:
Name Type Default Description
cellRange CellRange

Selection cell range.

auto Boolean false optional

true if called automatically by the plugin.

afterUntrimRow

Fired by TrimRows plugin after untrimming rows. This hook is fired when Options#trimRows option is enabled.

Parameters:
Name Type Description
rows Array.<Number>

Physical indexes of untrimmed rows.

afterUpdateSettings

Fired after calling the updateSettings method.

Parameters:
Name Type Description
newSettings Object

New settings object.

afterValidate

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.

Parameters:
Name 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).

afterViewportColumnCalculatorOverride

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

Parameters:
Name Type Description
calc Object

The row calculator.

afterViewportRowCalculatorOverride

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

Parameters:
Name Type Description
calc Object

The row calculator.

beforeAddChild

Fired by NestedRows plugin before adding a children to the NestedRows structure. This hook is fired when
Options#nestedRows option is enabled.

Parameters:
Name 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

Fired by Autofill plugin before populating the data in the autofill feature. This hook is fired when
Options#fillHandle option is enabled.

Parameters:
Name Type Description
start CellCoords

Object containing information about first filled cell: {row: 2, col: 0}.

end CellCoords

Object containing information about last filled cell: {row: 4, col: 1}.

data Array.<Array>

2D array containing information about fill pattern: [["1", "Ted"], ["1", "John"]].

beforeAutofillInsidePopulate

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

Parameters:
Name Type Description
index Object

Object containing row and col properties, defining the number of rows/columns from the initial cell of the autofill.

direction String

Declares the direction of the autofill. Possible values: up, down, left, right.

input Array.<Array>

Contains an array of rows with data being used in the autofill.

deltas Array

The deltas array passed to the populateFromArray method.

beforeCellAlignment

Fired before aligning the cell contents.

Parameters:
Name 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

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

Parameters:
Name Type Description
changes Array.<Array>

2D array containing information about each of the edited cells.

source String optional

String that identifies source of hook call
(list of all available sources).

Example
// To disregard a single change, set changes[i] to null or remove it from array using changes.splice(i, 1).
new Handsontable(element, {
  beforeChange: (changes, source) => {
    // [[row, prop, oldVal, newVal], ...]
    changes[0] = null;
  }
});
// To alter a single change, overwrite the desired value to changes[i][3].
new Handsontable(element, {
  beforeChange: (changes, source) => {
    // [[row, prop, oldVal, newVal], ...]
    changes[0][3] = 10;
  }
});
// To cancel all edit, return false from the callback or set array length to 0 (changes.length = 0).
new Handsontable(element, {
  beforeChange: (changes, source) => {
    // [[row, prop, oldVal, newVal], ...]
    return false;
  }
});

beforeChangeRender

Fired right before rendering the changes.

Parameters:
Name 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).

beforeColumnMove

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

Parameters:
Name Type Description
columns Array.<Number>

Array of visual column indexes to be moved.

target Number

Visual column index being a target for moved columns.

beforeColumnResize

Fired by ManualColumnResize plugin before rendering the table with modified column sizes. This hook is
fired when Options#manualColumnResize option is enabled.

Parameters:
Name Type Description
currentColumn Number

Visual index of the resized column.

newSize Number

Calculated new column width.

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

Fired by ColumnSorting and MultiColumnSorting plugin before sorting the column. If you return false value 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.

Parameters:
Name Type Description
currentSortConfig Array

Current sort configuration (for all sorted columns).

destinationSortConfigs Array

Destination sort configuration (for all sorted columns).

beforeContextMenuSetItems

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

Parameters:
Name Type Description
menuItems Array.<Object>

An array of objects containing information about to generated Context Menu items.

beforeContextMenuShow

Fired by ContextMenu plugin before opening the Context Menu. This hook is fired when Options#contextMenu
option is enabled.

Parameters:
Name Type Description
context Object

The Context Menu instance.

beforeCopy

Fired before values are copied into clipboard.

Parameters:
Name Type Description
data Array.<Array>

An array of arrays which contains data to copied.

coords Array.<Object>

An array of objects with ranges of the visual indexes (startRow, startCol, endRow, endCol)
which will copied.

Returns: {*} If returns false then copying is canceled.
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;
  }
});
...

beforeCreateCol

Fired before created a new column.

Parameters:
Name 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).

beforeCreateRow

Fired before created a new row.

Parameters:
Name 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).

beforeCut

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

Parameters:
Name 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.
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;
  }
});

beforeDetachChild

Fired by NestedRows plugin before detaching a child from its parent. This hook is fired when
Options#nestedRows option is enabled.

Parameters:
Name Type Description
parent Object

An object representing the parent from which the element is to be detached.

element Object

The detached element.

beforeDrawBorders

Fired before drawing the borders.

Parameters:
Name Type Description
corners Array

Array specifying the current selection borders.

borderClassName String

Specifies the border class name.

beforeDropdownMenuSetItems

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.

Parameters:
Name Type Description
menuItems Array.<Object>

An array of objects containing information about to generated Dropdown Menu items.

beforeDropdownMenuShow

Fired by DropdownMenu plugin before opening the dropdown menu. This hook is fired when Options#dropdownMenu
option is enabled.

Parameters:
Name Type Description
dropdownMenu DropdownMenu

The DropdownMenu instance.

beforeFilter

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

Parameters:
Name Type Description
conditionsStack Array.<Object>

An array of objects with added formulas.

// Example format of the conditionsStack argument:
[
  {
    column: 2,
    conditions: [
      {name: 'begins_with', args: [['S']]}
    ],
    operation: 'conjunction'
  },
  {
    column: 4,
    conditions: [
      {name: 'not_empty', args: []}
    ],
    operation: 'conjunction'
  },
]
Returns: {Boolean} If hook returns false value then filtering won't be applied on the UI side (server-side filtering).

beforeGetCellMeta

Fired before getting cell settings.

Parameters:
Name Type Description
row Number

Visual row index.

column Number

Visual column index.

cellProperties Object

Object containing the cell's properties.

beforeInit

Fired before the Handsontable instance is initiated.

beforeInitWalkontable

Fired before the Walkontable instance is initiated.

Parameters:
Name Type Description
walkontableConfig Object

Walkontable configuration object.

beforeKeyDown

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

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

Parameters:
Name Type Description
event Event

Original DOM event.

beforeLanguageChange

Fired before successful change of language (when proper language code was set)

Parameters:
Name Type Description
languageCode String

New language code.

Since: 0.35.0

beforeMergeCells

Fired by MergeCells plugin before cell merging. This hook is fired when Options#mergeCells
option is enabled.

Parameters:
Name Type Default Description
cellRange CellRange

Selection cell range.

auto Boolean false optional

true if called automatically by the plugin.

beforeOnCellContextMenu

Fired after the user clicked a cell, but before all the calculations related with it.

Parameters:
Name 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.

Since: 4.1.0

beforeOnCellMouseDown

Fired after the user clicked a cell, but before all the calculations related with it.

Parameters:
Name Type Description
event Event

The mousedown event object.

coords CellCoords

Cell coords object containing the visual coordinates of the clicked cell.

TD HTMLTableCellElement

TD element.

controller Object

An object with keys row, column and cells which contains boolean values. This
object allows or disallows changing the selection for the particular axies.

beforeOnCellMouseOut

Fired after the user moved cursor out from a cell, but before all the calculations related with it.

Parameters:
Name 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

Fired after the user moved cursor over a cell, but before all the calculations related with it.

Parameters:
Name Type Description
event Event

The mouseover event object.

coords CellCoords

CellCoords object containing the visual coordinates of the clicked cell.

TD HTMLTableCellElement

TD element.

controller Object

An object with keys row, column and cells which contains boolean values. This
object allows or disallows changing the selection for the particular axies.

beforePaste

Fired by CopyPaste plugin before values are pasted into table. This hook is fired when
Options#copyPaste option is enabled.

Parameters:
Name 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.
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;
  }
});

beforeRedo

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.

Parameters:
Name 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').

beforeRemoveCellClassNames

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

Fired before cell meta is removed.

Parameters:
Name 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.

beforeRemoveCol

Fired before one or more columns are about to be removed.

Parameters:
Name 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).

beforeRemoveRow

Fired when one or more rows are about to be removed.

Parameters:
Name Type Description
index Number

Visual index of starter column.

amount Number

Amount of columns 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).

beforeRender

Fired before the Handsontable table is rendered.

Parameters:
Name Type Description
isForced Boolean

If true rendering was triggered by a change of settings or data; or false if
rendering was triggered by scrolling or moving selection.

beforeRenderer

Fired before starting rendering the cell.

Parameters:
Name 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

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

Parameters:
Name Type Description
rows Array.<Number>

An array of visual row indexes to be moved.

target Number

Visual row index being a target for moved rows.

beforeRowResize

Fired by ManualRowResize plugin before rendering the table with modified row sizes. This hook is
fired when Options#manualRowResize option is enabled.

Parameters:
Name Type Description
currentRow Number

Visual index of the resized row.

newSize Number

Calculated new row height.

isDoubleClick Boolean

Flag that determines whether there was a double-click.

Returns: {Number} Returns the new row size or undefined if row size should be calculated automatically.

beforeSetRangeEnd

Fired before setting range is ended.

Parameters:
Name Type Description
coords CellCoords

CellCoords instance.

beforeSetRangeStart

Fired before setting range is started.

Parameters:
Name Type Description
coords CellCoords

CellCoords instance.

beforeSetRangeStartOnly

Fired before setting range is started but not finished yet.

Parameters:
Name Type Description
coords CellCoords

CellCoords instance.

beforeStretchingColumnWidth

Fired before applying stretched column width to column.

Parameters:
Name Type Description
stretchedWidth Number

Calculated width.

column Number

Visual column index.

Returns: {Number} Returns new width which will be applied to the column element.

beforeTouchScroll

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

beforeUndo

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.

Parameters:
Name 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').

beforeUnmergeCells

Fired by MergeCells plugin before unmerging the cells. This hook is fired when Options#mergeCells
option is enabled.

Parameters:
Name Type Default Description
cellRange CellRange

Selection cell range.

auto Boolean false optional

true if called automatically by the plugin.

beforeValidate

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

Parameters:
Name 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

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.

Parameters:
Name Type Description
value *

Cell value to render.

cellProperties Object

An object containing the cell properties.

construct

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

hiddenColumn

Fired by HiddenColumns plugin to check whether the provided column index is hidden. This hook is fired when
Options#hiddenColumns option is enabled.

Parameters:
Name Type Description
column Number

The visual column index in question.

hiddenRow

Fired by HiddenRows plugin to check whether the provided row index is hidden. This hook is fired when
Options#hiddenRows option is enabled.

Parameters:
Name Type Description
row Number

The visual row index in question.

init

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

modifyAutofillRange

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

Parameters:
Name 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]).

modifyCol

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

Parameters:
Name Type Description
column Number

Visual column index.

modifyColHeader

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

Parameters:
Name Type Description
column Number

Visual column header index.

modifyColumnHeaderHeight

Fired while retrieving the column header height.

modifyColWidth

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

Parameters:
Name Type Description
width Number

Current column width.

column Number

Visual column index.

modifyCopyableRange

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

Parameters:
Name Type Description
copyableRanges Array.<Array>

Array of objects defining copyable cells.

modifyData

Fired when a data was retrieved or modified.

Parameters:
Name Type Description
row Number

Row height.

column Number

Column index.

valueHolder Object

Object which contains original value which can be modified by overwriting .value property.

ioMode String

String which indicates for what operation hook is fired (get or set).

modifyGetCellCoords

Used to modify the cell coordinates when using the getCell method.

Parameters:
Name 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.

Since: 0.36.0

modifyRow

Fired when a row index is about to be modified by a callback function.

Parameters:
Name Type Description
row Number

Visual row index.

modifyRowData

Fired when a data was retrieved or modified.

Parameters:
Name Type Description
row Number

Physical row index.

modifyRowHeader

Fired when a row header index is about to be modified by a callback function.

Parameters:
Name Type Description
row Number

Visual row header index.

modifyRowHeaderWidth

Fired while retrieving the row header width.

Parameters:
Name Type Description
rowHeaderWidth Number

Row header width.

modifyRowHeight

Fired when a row height is about to be modified by a callback function.

Parameters:
Name Type Description
height Number

Row height.

row Number

Visual row index.

modifyTransformEnd

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

Parameters:
Name Type Description
delta CellCoords

Cell coords object declaring the delta of the new selection relative to the previous one.

modifyTransformStart

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

Parameters:
Name Type Description
delta CellCoords

Cell coords object declaring the delta of the new selection relative to the previous one.

persistentStateLoad

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

Parameters:
Name 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

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.

Parameters:
Name Type Description
key String optional

Key.

persistentStateSave

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

Parameters:
Name Type Description
key String

Key.

value Mixed

Value to save.

skipLengthCache

Used to skip the length cache calculation for a defined period of time.

Parameters:
Name Type Description
delay Number

The delay in milliseconds.

unmodifyCol

Fired when a column index is about to be de-modified by a callback function.

Parameters:
Name Type Description
column Number

Physical column index.

unmodifyRow

Fired when a physical row index is about to be de-modified by a callback function.

Parameters:
Name Type Description
row Number

Physical row index.