Class: Hooks

Hooks

handsontable/src/pluginHooks.js, line 1630

Methods

handsontable/src/pluginHooks.js, line 1707

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 null 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]);
handsontable/src/pluginHooks.js, line 1652

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: [],
...
}
handsontable/src/pluginHooks.js, line 1928

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');
handsontable/src/pluginHooks.js, line 1895

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 null optional

A Handsontable instance.

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

// destroy the local listeners
Handsontable.hooks.destroy(hotInstance);
handsontable/src/pluginHooks.js, line 1667

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 null optional

A Handsontable instance.

Returns: {Object} Returns a global or Handsontable instance bucket.
handsontable/src/pluginHooks.js, line 1973

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',
...
]
handsontable/src/pluginHooks.js, line 1803

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 null optional

A Handsontable instance.

Returns: {Boolean} true for success, false otherwise.
handsontable/src/pluginHooks.js, line 1948

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
handsontable/src/pluginHooks.js, line 1757

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 null optional

A Handsontable instance.

See:
Example
Handsontable.hooks.once('beforeInit', myCallback, hotInstance);
handsontable/src/pluginHooks.js, line 1912

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

Parameters:
Name Type Description
key String

The hook name.

Example
Handsontable.hooks.register('myHook');
handsontable/src/pluginHooks.js, line 1781

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 null optional

Handsontable instance.

See:
Returns: {Boolean} Returns true if hook was removed, false otherwise.
Example
Handsontable.hooks.remove('beforeInit', myCallback);
handsontable/src/pluginHooks.js, line 1829

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

handsontable/src/pluginHooks.js, line 1528

afterAddChild

Fired after adding a children to the NestedRows structure.

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.

handsontable/src/pluginHooks.js, line 1559

afterBeginEditing

Fired after the editor is opened and rendered.

Parameters:
Name Type Description
row Number

Row index of the edited cell.

column Number

Column index of the edited cell.

handsontable/src/pluginHooks.js, line 53

afterCellMetaReset

Callback fired after resetting a cell's meta.

Since:
  • 0.11
handsontable/src/pluginHooks.js, line 61

afterChange

Callback fired after one or more cells has been changed. Its main use case is to save the input.

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

handsontable/src/pluginHooks.js, line 74

afterChangesObserved

Fired after observing changes.

handsontable/src/pluginHooks.js, line 1197

afterColumnMove

Fired after change order of the visual indexes.

Parameters:
Name Type Description
columns Array

Array of visual column indexes that were moved.

target Number

Visual column index being a target for moved columns.

handsontable/src/pluginHooks.js, line 1235

afterColumnResize

Fired after rendering the table with modified column sizes.

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.

handsontable/src/pluginHooks.js, line 1012

afterColumnSort

Fired after sorting the column.

Parameters:
Name Type Description
column Number

Sorted visual column index.

order Boolean

Soring order where:

  • true means ascending order
  • false means descending order
  • undefined means original order
handsontable/src/pluginHooks.js, line 82

afterContextMenuDefaultOptions

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

Parameters:
Name Type Description
predefinedItems Array

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

handsontable/src/pluginHooks.js, line 124

afterContextMenuHide

Fired after hiding the Context Menu.

Parameters:
Name Type Description
context Object

The Context menu instance.

handsontable/src/pluginHooks.js, line 142

afterContextMenuShow

Fired after opening the Context Menu.

Parameters:
Name Type Description
context Object

The Context Menu instance.

handsontable/src/pluginHooks.js, line 1130

afterCopy

Fired after data are pasted into table.

Parameters:
Name Type Description
data Array

An array of arrays which contains the copied data.

coords Array

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

Since:
  • 0.31.1
handsontable/src/pluginHooks.js, line 151

afterCopyLimit

Fired after reaching the copy limit while copying data.

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.

handsontable/src/pluginHooks.js, line 175

afterCreateCol

Callback is fired after a new column was created.

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

handsontable/src/pluginHooks.js, line 198

afterCreateRow

Callback is fired after a new row was created.

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

handsontable/src/pluginHooks.js, line 1083

afterCut

Fired after data are cutted out from the table.

Parameters:
Name Type Description
data Array

An array of arrays which contains the cutted out data.

coords Array

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

Since:
  • 0.31.1
handsontable/src/pluginHooks.js, line 209

afterDeselect

Fired after the current cell is deselected.

handsontable/src/pluginHooks.js, line 216

afterDestroy

Fired after destroying the Handsontable instance.

handsontable/src/pluginHooks.js, line 1549

afterDetachChild

Fired after detaching a child from its parent in the NestedRows plugin.

Parameters:
Name Type Description
parent Object

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

element Object

The detached element.

handsontable/src/pluginHooks.js, line 223

afterDocumentKeyDown

Fired on a keydown event on the document body.

Parameters:
Name Type Description
event Event

A keydown event.

handsontable/src/pluginHooks.js, line 231

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

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.
handsontable/src/pluginHooks.js, line 102

afterDropdownMenuDefaultOptions

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

Parameters:
Name Type Description
predefinedItems Array

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

handsontable/src/pluginHooks.js, line 1490

afterDropdownMenuHide

Fired after hiding the dropdown menu.

Parameters:
Name Type Description
instance DropdownMenu

The DropdownMenu instance.

handsontable/src/pluginHooks.js, line 1481

afterDropdownMenuShow

Fired after opening the dropdown menu.

Parameters:
Name Type Description
instance DropdownMenu

The DropdownMenu instance.

handsontable/src/pluginHooks.js, line 1302

afterFilter

Fired after applying filtering.

Parameters:
Name Type Description
conditionsStack Array

An array of objects with added formulas.

handsontable/src/pluginHooks.js, line 251

afterGetCellMeta

Callback fired after getting the cell settings.

Parameters:
Name Type Description
row Number

Visual row index.

col Number

Visual column index.

cellProperties Object

Object containing the cell properties.

handsontable/src/pluginHooks.js, line 261

afterGetColHeader

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

Parameters:
Name Type Description
col Number

Visual column index.

TH Element

Header's TH element.

handsontable/src/pluginHooks.js, line 1266

afterGetColumnHeaderRenderers

Fired after getting the column header renderers.

Parameters:
Name Type Description
array Array

Array of the column header renderers.

handsontable/src/pluginHooks.js, line 270

afterGetRowHeader

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

Parameters:
Name Type Description
row Number

Visual row index.

TH Element

Header's TH element.

handsontable/src/pluginHooks.js, line 1274

afterGetRowHeaderRenderers

Fired after getting the row header renderers.

Parameters:
Name Type Description
array Array

Array of the row header renderers.

handsontable/src/pluginHooks.js, line 279

afterInit

Callback fired after Handsontable instance is initiated.

handsontable/src/pluginHooks.js, line 579

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
handsontable/src/pluginHooks.js, line 1605

afterListen

Fired after the listening is turned on.

Since:
  • 0.34.5
handsontable/src/pluginHooks.js, line 286

afterLoadData

Callback fired after new data is loaded (by loadData method) into the data source array.

Parameters:
Name Type Description
firstTime Boolean

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

handsontable/src/pluginHooks.js, line 1577

afterMergeCells

Fired after cell merging.

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.

handsontable/src/pluginHooks.js, line 1405

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.

handsontable/src/pluginHooks.js, line 1395

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.

handsontable/src/pluginHooks.js, line 294

afterMomentumScroll

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

handsontable/src/pluginHooks.js, line 310

afterOnCellCornerDblClick

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

Parameters:
Name Type Description
event Object

dblclick event object.

Since:
  • 0.30.0
handsontable/src/pluginHooks.js, line 301

afterOnCellCornerMouseDown

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

Parameters:
Name Type Description
event Object

mousedown event object.

Since:
  • 0.11
handsontable/src/pluginHooks.js, line 319

afterOnCellMouseDown

Callback fired after clicking on a cell or row/column header.
In case the row/column header was clicked, the index is negative.
For example clicking on the row header of cell (0, 0) results with afterOnCellMouseDown called
with coords {row: 0, col: -1}.

Parameters:
Name Type Description
event Object

mousedown event object.

coords Object

Coordinates object containing the visual row and visual column indexes of the clicked cell.

TD Element

Cell's TD (or TH) element.

Since:
  • 0.11
handsontable/src/pluginHooks.js, line 347

afterOnCellMouseOut

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

Parameters:
Name Type Description
event Object

mouseout event object.

coords Object

Leaved cell's visual coordinate object.

TD Element

Cell's TD (or TH) element.

Since:
  • 0.31.1
handsontable/src/pluginHooks.js, line 333

afterOnCellMouseOver

Callback 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 Object

mouseover event object.

coords Object

Hovered cell's visual coordinate object.

TD Element

Cell's TD (or TH) element.

Since:
  • 0.11
handsontable/src/pluginHooks.js, line 1177

afterPaste

Fired after values are pasted into table.

Parameters:
Name Type Description
data Array

An array of arrays which contains the pasted data.

coords Array

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

Since:
  • 0.31.1
handsontable/src/pluginHooks.js, line 1431

afterPluginsInitialized

Fired after initializing all the plugins.

handsontable/src/pluginHooks.js, line 1350

afterRedo

Fired after the redo action. Contains information about the action that is being redone.

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

Since:
  • 0.26.2
handsontable/src/pluginHooks.js, line 510

afterRemoveCellMeta

Called after cell meta is removed.

Parameters:
Name Type Description
row Number

Visual row index.

col Number

Visual column index.

key String

The removed meta key.

value *

Value which was under removed key of cell meta.

Since:
  • 0.33.1
handsontable/src/pluginHooks.js, line 358

afterRemoveCol

Callback is fired when one or more columns are removed.

Parameters:
Name Type Description
index Number

Is an visual index of starter column.

amount Number

Is an amount of removed columns.

handsontable/src/pluginHooks.js, line 367

afterRemoveRow

Callback is fired when one or more rows are removed.

Parameters:
Name Type Description
index Number

Is an visual index of starter row.

amount Number

Is an amount of removed rows.

handsontable/src/pluginHooks.js, line 376

afterRender

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

handsontable/src/pluginHooks.js, line 399

afterRenderer

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

Parameters:
Name Type Description
TD Element

Currently rendered cell's TD element.

row Number

Visual row index.

col Number

Visual column index.

prop String | Number

Column property name or a column index, if datasource is an array of arrays.

value String

Value of the rendered cell.

cellProperties Object

Object containing the cell's properties.

Since:
  • 0.11.0
handsontable/src/pluginHooks.js, line 1215

afterRowMove

Fired after change order of the visual indexes.

Parameters:
Name Type Description
rows Array

Array of visual row indexes that were moved.

target Number

Visual row index being a target for moved rows.

handsontable/src/pluginHooks.js, line 1256

afterRowResize

Fired after rendering the table with modified row sizes.

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.

handsontable/src/pluginHooks.js, line 413

afterScrollHorizontally

Fired after the horizontal scroll event.

Since:
  • 0.11
handsontable/src/pluginHooks.js, line 421

afterScrollVertically

Fired after the vertical scroll event.

Since:
  • 0.11
handsontable/src/pluginHooks.js, line 429

afterSelection

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

Parameters:
Name Type Description
r Number

Selection start visual row index.

c Number

Selection start visual column index.

r2 Number

Selection end visual row index.

c2 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
handsontable({
  afterSelection: function (r, c, r2, c2, preventScrolling, selectionLayerLevel) {
    // setting if prevent scrolling after selection
    preventScrolling.value = true;
  }
})
handsontable/src/pluginHooks.js, line 451

afterSelectionByProp

Callback fired after one or more cells are selected. The p argument represents the source object property name instead of the column number.

Parameters:
Name Type Description
r Number

Selection start visual row index.

p String

Selection start data source object property name.

r2 Number

Selection end visual row index.

p2 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
handsontable({
  afterSelectionByProp: function (r, c, r2, c2, preventScrolling, selectionLayerLevel) {
    // setting if prevent scrolling after selection
    preventScrolling.value = true;
  }
})
handsontable/src/pluginHooks.js, line 473

afterSelectionEnd

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

Parameters:
Name Type Description
r Number

Selection start visual row index.

c Number

Selection start visual column index.

r2 Number

Selection end visual row index.

c2 Number

Selection end visual column index.

selectionLayerLevel Number

The number which indicates what selection layer is currently modified.

handsontable/src/pluginHooks.js, line 485

afterSelectionEndByProp

Callback fired after one or more cells are selected (e.g. on mouse up). The p argument represents the data source object
property name instead of the column number.

Parameters:
Name Type Description
r Number

Selection start visual row index.

p String

Selection start data source object property index.

r2 Number

Selection end visual row index.

p2 String

Selection end data source object property index.

selectionLayerLevel Number

The number which indicates what selection layer is currently modified.

handsontable/src/pluginHooks.js, line 498

afterSetCellMeta

Called after cell meta is changed.

Parameters:
Name Type Description
row Number

Visual row index.

col Number

Visual column index.

key String

The updated meta key.

value *

The updated meta value.

Since:
  • 0.11.0
handsontable/src/pluginHooks.js, line 522

afterSetDataAtCell

Called after cell data was changed.

Parameters:
Name Type Description
changes Array

An array of changes in format [[row, col, oldValue, value], ...].

source String optional

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

Since:
  • 0.28.0
handsontable/src/pluginHooks.js, line 533

afterSetDataAtRowProp

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

Since:
  • 0.28.0
handsontable/src/pluginHooks.js, line 1454

afterTrimRow

Fired after trimming rows in the TrimRows plugin.

Parameters:
Name Type Description
rows Array

Physical indexes of trimmed rows.

handsontable/src/pluginHooks.js, line 1330

afterUndo

Fired after the undo action. Contains information about the action that is being undone.

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

Since:
  • 0.26.2
handsontable/src/pluginHooks.js, line 1613

afterUnlisten

Fired after the listening is turned off.

Since:
  • 0.34.5
handsontable/src/pluginHooks.js, line 1463

afterUntrimRow

Fired after untrimming rows in the TrimRows plugin.

Parameters:
Name Type Description
rows Array

Physical indexes of untrimmed rows.

handsontable/src/pluginHooks.js, line 544

afterUpdateSettings

Fired after calling the updateSettings method.

Parameters:
Name Type Description
settings Object

New settings object.

handsontable/src/pluginHooks.js, line 552

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

Row index.

prop String | Number

Property name / column index.

source String optional

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

Since:
  • 0.9.5
handsontable/src/pluginHooks.js, line 1423

afterViewportColumnCalculatorOverride

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

Parameters:
Name Type Description
calc Object

The row calculator.

handsontable/src/pluginHooks.js, line 1415

afterViewportRowCalculatorOverride

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

Parameters:
Name Type Description
calc Object

The row calculator.

handsontable/src/pluginHooks.js, line 1517

beforeAddChild

Fired before adding a children to the NestedRows structure.

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.

handsontable/src/pluginHooks.js, line 588

beforeAutofill

Fired before populating the data in the autofill feature.

Parameters:
Name Type Description
start Object

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

end Object

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

data Array

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

baseRange Array

The coordinates of the base area for autofill.

handsontable/src/pluginHooks.js, line 1368

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 of arrays. Contains an array of rows with data being used in the autofill.

deltas Array

The deltas array passed to the populateFromArray method.

handsontable/src/pluginHooks.js, line 599

beforeCellAlignment

Fired before aligning the cell contents.

Parameters:
Name Type Description
stateBefore
range
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
    for horizontal alignment,
  • htTop,
  • htMiddle,
  • htBottom
    for vertical alignment.
handsontable/src/pluginHooks.js, line 622

beforeChange

Callback fired before one or more cells is changed. Its main purpose is to alter changes silently before input.

Parameters:
Name Type Description
changes 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(document.getElementById('example'), {
  beforeChange: function(changes, source) {
    // [[row, prop, oldVal, newVal], ...]
    changes[0] = null;
  }
});
...

// To alter a single change, overwrite the desired value to changes[i][3].
...
new Handsontable(document.getElementById('example'), {
  beforeChange: function(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(document.getElementById('example'), {
  beforeChange: function(changes, source) {
    // [[row, prop, oldVal, newVal], ...]
    return false;
  }
});
...
handsontable/src/pluginHooks.js, line 664

beforeChangeRender

Fired right before rendering the changes.

Parameters:
Name Type Description
changes Array

Array in form of [row, prop, oldValue, newValue].

source String optional

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

Since:
  • 0.11
handsontable/src/pluginHooks.js, line 1188

beforeColumnMove

Fired before change order of the visual indexes.

Parameters:
Name Type Description
columns Array

Array of visual column indexes to be moved.

target Number

Visual column index being a target for moved columns.

handsontable/src/pluginHooks.js, line 1224

beforeColumnResize

Fired before rendering the table with modified column sizes.

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.
handsontable/src/pluginHooks.js, line 999

beforeColumnSort

Fired before sorting the column. If you return false value then sorting will be not applied by
Handsontable (useful for server-side sorting).

Parameters:
Name Type Description
column Number

Sorted visual column index.

order Boolean

Soring order where:

  • true means ascending order,
  • false means descending order,
  • undefined means original order.
handsontable/src/pluginHooks.js, line 92

beforeContextMenuSetItems

Fired 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

Array of objects containing information about to generated Context Menu items.

handsontable/src/pluginHooks.js, line 133

beforeContextMenuShow

Fired before opening the Context Menu.

Parameters:
Name Type Description
context Object

The Context Menu instance.

handsontable/src/pluginHooks.js, line 1094

beforeCopy

Fired before values are copied into clipboard.

Parameters:
Name Type Description
data Array

An array of arrays which contains data to copied.

coords Array

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

Since:
  • 0.31.1
Returns: {*} If returns false then copying is cancelled.
Example
// To disregard a single row, remove it from array using data.splice(i, 1).
...
new Handsontable(document.getElementById('example'), {
  beforeCopy: 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 copying, return false from the callback.
...
new Handsontable(document.getElementById('example'), {
  beforeCopy: function(data, coords) {
    return false;
  }
});
...
handsontable/src/pluginHooks.js, line 163

beforeCreateCol

Callback is fired before a new column was created.

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

Since:
  • 0.28.0
handsontable/src/pluginHooks.js, line 186

beforeCreateRow

Callback is fired before a new row was created.

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

Since:
  • 0.28.0
handsontable/src/pluginHooks.js, line 1047

beforeCut

Called before copying the values into clipboard and before clearing values of the selected cells.

Parameters:
Name Type Description
data Array

An array of arrays which contains data to cut.

coords Array

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

Since:
  • 0.31.1
Returns: {*} If returns false then operation of the cutting out is cancelled.
Example
// To disregard a single row, remove it from array using data.splice(i, 1).
...
new Handsontable(document.getElementById('example'), {
  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 cutting out, return false from the callback.
...
new Handsontable(document.getElementById('example'), {
  beforeCut: function(data, coords) {
    return false;
  }
});
...
handsontable/src/pluginHooks.js, line 1539

beforeDetachChild

Fired before detaching a child from its parent in the NestedRows plugin.

Parameters:
Name Type Description
parent Object

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

element Object

The detached element.

handsontable/src/pluginHooks.js, line 675

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.

handsontable/src/pluginHooks.js, line 113

beforeDropdownMenuSetItems

Fired 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

Array of objects containing information about to generated Dropdown Menu items.

handsontable/src/pluginHooks.js, line 1472

beforeDropdownMenuShow

Fired before opening the dropdown menu.

Parameters:
Name Type Description
instance DropdownMenu

The DropdownMenu instance.

handsontable/src/pluginHooks.js, line 1292

beforeFilter

Fired before applying filtering.

Parameters:
Name Type Description
conditionsStack Array

An array of objects with added formulas.

Returns: {Boolean} If hook returns false value then filtering won't be applied on the UI side (server-side filtering).
handsontable/src/pluginHooks.js, line 684

beforeGetCellMeta

Callback fired before getting cell settings.

Parameters:
Name Type Description
row Number

Visual row index.

col Number

Visual column index.

cellProperties Object

Object containing the cell's properties.

handsontable/src/pluginHooks.js, line 706

beforeInit

Callback fired before Handsontable instance is initiated.

handsontable/src/pluginHooks.js, line 714

beforeInitWalkontable

Callback fired before Walkontable instance is initiated.

Parameters:
Name Type Description
walkontableConfig Object

Walkontable configuration object.

Since:
  • 0.11
handsontable/src/pluginHooks.js, line 723

beforeKeyDown

Callback fired before keydown event is handled. It can be used to overwrite default key bindings.
Caution - in your beforeKeyDown handler you need to call event.stopImmediatePropagation() to prevent default key behavior.

Parameters:
Name Type Description
event Event

Original DOM event.

Since:
  • 0.9.0
handsontable/src/pluginHooks.js, line 570

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
handsontable/src/pluginHooks.js, line 1568

beforeMergeCells

Fired before cell merging.

Parameters:
Name Type Default Description
cellRange CellRange

Selection cell range.

auto Boolean false optional

true if called automatically by the plugin.

handsontable/src/pluginHooks.js, line 733

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 Element

TD element.

handsontable/src/pluginHooks.js, line 754

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 WalkontableCellCoords

WalkontableCellCoords object containing the visual coordinates of the leaved cell.

TD Element

TD element.

Since:
  • 0.31.1
handsontable/src/pluginHooks.js, line 743

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 Element

TD element.

blockCalculations Object

Contain keys 'row' and 'column' with boolean value.

handsontable/src/pluginHooks.js, line 1141

beforePaste

Fired before values are pasted into table.

Parameters:
Name Type Description
data Array

An array of arrays which contains data to paste.

coords Array

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

Since:
  • 0.31.1
Returns: {*} If returns false then pasting is cancelled.
Example
// To disregard a single row, remove it from array using data.splice(i, 1).
...
new Handsontable(document.getElementById('example'), {
  beforePaste: 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 pasting, return false from the callback.
...
new Handsontable(document.getElementById('example'), {
  beforePaste: function(data, coords) {
    return false;
  }
});
...
handsontable/src/pluginHooks.js, line 1340

beforeRedo

Fired before the redo action. Contains information about the action that is being redone.

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

Since:
  • 0.26.2
handsontable/src/pluginHooks.js, line 243

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.|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.
handsontable/src/pluginHooks.js, line 694

beforeRemoveCellMeta

Called before cell meta is removed.

Parameters:
Name Type Description
row Number

Visual row index.

col Number

Visual column index.

key String

The removed meta key.

value *

Value which is under removed key of cell meta.

Since:
  • 0.33.1
handsontable/src/pluginHooks.js, line 765

beforeRemoveCol

Callback is fired when 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.

visualCols Array optional

Consists of visual indexes of processed columns.

handsontable/src/pluginHooks.js, line 775

beforeRemoveRow

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

visualRows Array optional

Consists of visual indexes of processed rows.

handsontable/src/pluginHooks.js, line 785

beforeRender

Callback fired before 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.

handsontable/src/pluginHooks.js, line 385

beforeRenderer

Fired before starting rendering the cell.

Parameters:
Name Type Description
TD Element

Currently rendered cell's TD element.

row Number

Visual row index.

col Number

Visual column index.

prop String | Number

Column property name or a column index, if datasource is an array of arrays.

value String

Value of the rendered cell.

cellProperties Object

Object containing the cell's properties.

Since:
  • 0.24.2
handsontable/src/pluginHooks.js, line 1206

beforeRowMove

Fired before change order of the visual indexes.

Parameters:
Name Type Description
rows Array

Array of visual row indexes to be moved.

target Number

Visual row index being a target for moved rows.

handsontable/src/pluginHooks.js, line 1245

beforeRowResize

Fired before rendering the table with modified row sizes.

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.
handsontable/src/pluginHooks.js, line 810

beforeSetRangeEnd

Callback fired before setting range is ended.

Parameters:
Name Type Description
coords CellCoords

CellCoords instance.

handsontable/src/pluginHooks.js, line 802

beforeSetRangeStart

Callback fired before setting range is started.

Parameters:
Name Type Description
coords CellCoords

CellCoords instance.

handsontable/src/pluginHooks.js, line 794

beforeSetRangeStartOnly

Callback fired before setting range is started but not finished yet.

Parameters:
Name Type Description
coords CellCoords

CellCoords instance.

handsontable/src/pluginHooks.js, line 1282

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.
handsontable/src/pluginHooks.js, line 818

beforeTouchScroll

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

handsontable/src/pluginHooks.js, line 1320

beforeUndo

Fired before the undo action. Contains information about the action that is being undone.

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

Since:
  • 0.26.2
handsontable/src/pluginHooks.js, line 1596

beforeUnmergeCells

Fired after unmerging the cells.

Parameters:
Name Type Default Description
cellRange CellRange

Selection cell range.

auto Boolean false optional

true if called automatically by the plugin.

handsontable/src/pluginHooks.js, line 1587

beforeUnmergeCells

Fired before unmerging the cells.

Parameters:
Name Type Default Description
cellRange CellRange

Selection cell range.

auto Boolean false optional

true if called automatically by the plugin.

handsontable/src/pluginHooks.js, line 825

beforeValidate

A plugin hook executed before validator function, 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.

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

Row index.

prop String | Number

Property name / column index.

source String optional

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

Since:
  • 0.9.5
handsontable/src/pluginHooks.js, line 842

beforeValueRender

Callback fired before cell value is rendered into the DOM (through renderer function).

Parameters:
Name Type Description
value *

Cell value to render.

Since:
  • 0.29.0
handsontable/src/pluginHooks.js, line 851

construct

Callback fired after Handsontable instance is constructed (via new operator).

Since:
  • 0.16.1
handsontable/src/pluginHooks.js, line 1508

hiddenColumn

Used to check whether the provided column index is hidden.

Parameters:
Name Type Description
column Number

The visual column index in question.

handsontable/src/pluginHooks.js, line 1499

hiddenRow

Used to check whether the provided row index is hidden.

Parameters:
Name Type Description
row Number

The visual row index in question.

handsontable/src/pluginHooks.js, line 859

init

Callback fired after Handsontable instance is initiated but before table is rendered.

Since:
  • 0.16.1
handsontable/src/pluginHooks.js, line 1438

manualRowHeights

Used when saving/loading the manual row heights state.

Parameters:
Name Type Description
state Array

The current manual row heights state.

handsontable/src/pluginHooks.js, line 1024

modifyAutofillRange

Fired after setting range of autofill.
Both arguments are provided in the following format:

[startRow, startColumn, endRow, endColumn]
Parameters:
Name Type Description
startArea Array

Array of visual coordinates of the starting point for the drag-down operation.

entireArea Array

Array of visual coordinates of the entire area of the drag-down operation.

handsontable/src/pluginHooks.js, line 867

modifyCol

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

Parameters:
Name Type Description
col Number

Visual column index.

Since:
  • 0.11
handsontable/src/pluginHooks.js, line 893

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.

Since:
  • 0.20.0
handsontable/src/pluginHooks.js, line 1311

modifyColumnHeaderHeight

Used to modify the column header height.

Parameters:
Name Type Description
col Number

Visual column index.

Since:
  • 0.25.0
handsontable/src/pluginHooks.js, line 902

modifyColWidth

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

Parameters:
Name Type Description
width Number

Current column width.

col Number

Column index.

Since:
  • 0.11
handsontable/src/pluginHooks.js, line 1038

modifyCopyableRange

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

Parameters:
Name Type Description
copyableRanges Array

Array of objects defining copyable cells.

Since:
  • 0.19.0
handsontable/src/pluginHooks.js, line 940

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

Since:
  • 0.28.0
handsontable/src/pluginHooks.js, line 961

modifyGetCellCoords

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

Parameters:
Name Type Description
row Number

Visual row index.

col 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
handsontable/src/pluginHooks.js, line 912

modifyRow

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

Parameters:
Name Type Description
row Number

Row index.

Since:
  • 0.11
handsontable/src/pluginHooks.js, line 952

modifyRowData

Fired when a data was retrieved or modified.

Parameters:
Name Type Description
row Number

Physical row index.

Since:
  • 0.28.0
handsontable/src/pluginHooks.js, line 921

modifyRowHeader

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

Parameters:
Name Type Description
row Number

Row header index.

Since:
  • 0.20.0
handsontable/src/pluginHooks.js, line 1360

modifyRowHeaderWidth

Used to modify the row header width.

Parameters:
Name Type Description
rowHeaderWidth Number

Row header width.

handsontable/src/pluginHooks.js, line 930

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

Row index.

Since:
  • 0.11.0
handsontable/src/pluginHooks.js, line 1387

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.

handsontable/src/pluginHooks.js, line 1379

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.

handsontable/src/pluginHooks.js, line 973

persistentStateLoad

Fired after loading data using the Persistent State plugin.

Parameters:
Name Type Description
key String

Key string.

valuePlaceholder Object

Object containing the loaded data.

handsontable/src/pluginHooks.js, line 982

persistentStateReset

Fired after resetting data using the Persistent State plugin.

Parameters:
Name Type Description
key String

Key string.

handsontable/src/pluginHooks.js, line 990

persistentStateSave

Fired after resetting data using the Persistent State plugin.

Parameters:
Name Type Description
key String

Key string.

value Mixed

Value to save.

handsontable/src/pluginHooks.js, line 1446

skipLengthCache

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

Parameters:
Name Type Description
delay Number

The delay in milliseconds.

handsontable/src/pluginHooks.js, line 876

unmodifyCol

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

Parameters:
Name Type Description
col Number

Physical column index.

Since:
  • 0.23.0
handsontable/src/pluginHooks.js, line 885

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.

Since:
  • 0.26.2