/ S

This page covers a next version of Handsontable, and is not published yet.

This page covers a non-latest version of Handsontable.

# Core

Table of contents

# Description

The Handsontable class to which we refer as to Core, allows you to modify the grid's behavior by using one of the available public methods.

# How to call a method

// First, let's contruct Handsontable
const hot = new Handsontable(document.getElementById('example'), options);

// Then, let's use the setDataAtCell method
hot.setDataAtCell(0, 0, 'new value');

# Members

# columnIndexMapper

Source code (opens new window)

core.columnIndexMapper : IndexMapper

Instance of index mapper which is responsible for managing the column indexes.

# isDestroyed

Source code (opens new window)

core.isDestroyed : boolean

A boolean to tell if the Handsontable has been fully destroyed. This is set to true after afterDestroy hook is called.

# rowIndexMapper

Source code (opens new window)

core.rowIndexMapper : IndexMapper

Instance of index mapper which is responsible for managing the row indexes.

# Methods

# addHook

Source code (opens new window)

core.addHook(key, callback)

Adds listener to the specified hook name (only for this Handsontable instance).

See: Hooks#add Example

hot.addHook('beforeInit', myCallback);
Param Type Description
key string Hook name (see Hooks).
callback function
Array		 Function or array of functions.

# addHookOnce

Source code (opens new window)

core.addHookOnce(key, callback)

Adds listener to specified hook name (only for this Handsontable instance). After the listener is triggered, it will be automatically removed.

See: Hooks#once Example

hot.addHookOnce('beforeInit', myCallback);
Param Type Description
key string Hook name (see Hooks).
callback function
Array		 Function or array of functions.

# alter

Source code (opens new window)

core.alter(action, index, [amount], [source], [keepEmptyRows])

Allows altering the table structure by either inserting/removing rows or columns. This method works with an array data structure only.

Example

// Insert new row above the row at given visual index.
hot.alter('insert_row', 10);
// Insert 3 new columns before 10th column.
hot.alter('insert_col', 10, 3);
// Remove 2 rows starting from 10th row.
hot.alter('remove_row', 10, 2);
// Remove 5 non-contiquous rows (it removes 3 rows from visual index 1 and 2 rows from visual index 5).
hot.alter('remove_row', [[1, 3], [5, 2]]);
Param Type Default Description
action string Possible alter operations:
  • 'insert_row'
  • 'insert_col'
  • 'remove_row'
  • 'remove_col'
index number
Array<number>		 Visual index of the row/column before which the new row/column will be inserted/removed or an array of arrays in format [[index, amount],...].
[amount] number 1 optional Amount of rows/columns to be inserted or removed.
[source] string optional Source indicator.
[keepEmptyRows] boolean optional Flag for preventing deletion of empty rows.

# batch

Source code (opens new window)

core.batch(wrappedOperations) ⇒ *

It batches the rendering process and index recalculations. The method aggregates multi-line API calls into a callback and postpones the table rendering process as well aggregates the table logic changes such as index changes into one call after which the cache is updated. After the execution of the operations, the table is rendered, and the cache is updated once. As a result, it improves the performance of wrapped operations.

Since: 8.3.0 Example

hot.batch(() => {
  hot.alter('insert_row', 5, 45);
  hot.alter('insert_col', 10, 40);
  hot.setDataAtCell(1, 1, 'x');
  hot.setDataAtCell(2, 2, 'c');
  hot.setDataAtCell(3, 3, 'v');
  hot.setDataAtCell(4, 4, 'b');
  hot.setDataAtCell(5, 5, 'n');
  hot.selectCell(0, 0);

  const filters = hot.getPlugin('filters');

  filters.addCondition(2, 'contains', ['3']);
  filters.filter();
  hot.getPlugin('columnSorting').sort({ column: 1, sortOrder: 'desc' });
  // The table will be re-rendered and cache will be recalculated once after executing the callback
});
Param Type Description
wrappedOperations function Batched operations wrapped in a function.

Returns: * - Returns result from the wrappedOperations callback.

# batchExecution

Source code (opens new window)

core.batchExecution(wrappedOperations, [forceFlushChanges]) ⇒ *

The method aggregates multi-line API calls into a callback and postpones the table execution process. After the execution of the operations, the internal table cache is recalculated once. As a result, it improves the performance of wrapped operations. Without batching, a similar case could trigger multiple table cache rebuilds.

Since: 8.3.0 Example

hot.batchExecution(() => {
  const filters = hot.getPlugin('filters');

  filters.addCondition(2, 'contains', ['3']);
  filters.filter();
  hot.getPlugin('columnSorting').sort({ column: 1, sortOrder: 'desc' });
  // The table cache will be recalculated once after executing the callback
});
Param Type Default Description
wrappedOperations function Batched operations wrapped in a function.
[forceFlushChanges] boolean false optional If true, the table internal data cache is recalculated after the execution of the batched operations. For nested calls, it can be a desire to recalculate the table after each batch.

Returns: * - Returns result from the wrappedOperations callback.

# batchRender

Source code (opens new window)

core.batchRender(wrappedOperations) ⇒ *

The method aggregates multi-line API calls into a callback and postpones the table rendering process. After the execution of the operations, the table is rendered once. As a result, it improves the performance of wrapped operations. Without batching, a similar case could trigger multiple table render calls.

Since: 8.3.0 Example

hot.batchRender(() => {
  hot.alter('insert_row', 5, 45);
  hot.alter('insert_col', 10, 40);
  hot.setDataAtCell(1, 1, 'John');
  hot.setDataAtCell(2, 2, 'Mark');
  hot.setDataAtCell(3, 3, 'Ann');
  hot.setDataAtCell(4, 4, 'Sophia');
  hot.setDataAtCell(5, 5, 'Mia');
  hot.selectCell(0, 0);
  // The table will be rendered once after executing the callback
});
Param Type Description
wrappedOperations function Batched operations wrapped in a function.

Returns: * - Returns result from the wrappedOperations callback.

# clear

Source code (opens new window)

core.clear()

Clears the data from the table (the table settings remain intact).

# clearUndo

Source code (opens new window)

core.clearUndo() ⇒ boolean

UndoRedo#clear.

# colToProp

Source code (opens new window)

core.colToProp(column) ⇒ string | number

Returns the property name that corresponds with the given column index. If the data source is an array of arrays, it returns the columns index.

Param Type Description
column number Visual column index.

Returns: string | number - Column property or physical column index.

# countCols

Source code (opens new window)

core.countCols() ⇒ number

Returns the total number of visible columns in the table.

Returns: number - Total number of columns.

# countEmptyCols

Source code (opens new window)

core.countEmptyCols([ending]) ⇒ number

Returns the number of empty columns. If the optional ending parameter is true, returns the number of empty columns at right hand edge of the table.

Param Type Default Description
[ending] boolean false optional If true, will only count empty columns at the end of the data source row.

Returns: number - Count empty cols.

# countEmptyRows

Source code (opens new window)

core.countEmptyRows([ending]) ⇒ number

Returns the number of empty rows. If the optional ending parameter is true, returns the number of empty rows at the bottom of the table.

Param Type Default Description
[ending] boolean false optional If true, will only count empty rows at the end of the data source.

Returns: number - Count empty rows.

# countRenderedCols

Source code (opens new window)

core.countRenderedCols() ⇒ number

Returns the number of rendered columns (including columns partially or fully rendered outside viewport).

Returns: number - Returns -1 if table is not visible.

# countRenderedRows

Source code (opens new window)

core.countRenderedRows() ⇒ number

Returns the number of rendered rows (including rows partially or fully rendered outside viewport).

Returns: number - Returns -1 if table is not visible.

# countRows

Source code (opens new window)

core.countRows() ⇒ number

Returns the total number of visual rows in the table.

Returns: number - Total number of rows.

# countSourceCols

Source code (opens new window)

core.countSourceCols() ⇒ number

Returns the total number of columns in the data source.

Returns: number - Total number of columns.

# countSourceRows

Source code (opens new window)

core.countSourceRows() ⇒ number

Returns the total number of rows in the data source.

Returns: number - Total number of rows.

# countVisibleCols

Source code (opens new window)

core.countVisibleCols() ⇒ number

Returns the number of visible columns. Returns -1 if table is not visible.

Returns: number - Number of visible columns or -1.

# countVisibleRows

Source code (opens new window)

core.countVisibleRows() ⇒ number

Returns the number of visible rows (rendered rows that fully fit inside viewport).

Returns: number - Number of visible rows or -1.

# deselectCell

Source code (opens new window)

core.deselectCell()

Deselects the current cell selection on the table.

# destroy

Source code (opens new window)

core.destroy()

Removes the table from the DOM and destroys the instance of the Handsontable.

Emits: Hooks#event:afterDestroy

# destroyEditor

Source code (opens new window)

core.destroyEditor([revertOriginal], [prepareEditorIfNeeded])

Destroys the current editor, render the table and prepares the editor of the newly selected cell.

Param Type Default Description
[revertOriginal] boolean false optional If true, the previous value will be restored. Otherwise, the edited value will be saved.
[prepareEditorIfNeeded] boolean true optional If true the editor under the selected cell will be prepared to open.

# emptySelectedCells

Source code (opens new window)

core.emptySelectedCells([source])

Erases content from cells that have been selected in the table.

Since: 0.36.0

Param Type Description
[source] string optional String that identifies how this change will be described in the changes array (useful in afterChange or beforeChange callback). Set to 'edit' if left empty.

# getActiveEditor

Source code (opens new window)

core.getActiveEditor() ⇒ BaseEditor

Returns the active editor class instance.

Returns: BaseEditor - The active editor instance.

# getCell

Source code (opens new window)

core.getCell(row, column, [topmost]) ⇒ HTMLTableCellElement | null

Returns a TD element for the given row and column arguments, if it is rendered on screen. Returns null if the TD is not rendered on screen (probably because that part of the table is not visible).

Param Type Default Description
row number Visual row index.
column number Visual column index.
[topmost] boolean false optional 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.

Returns: HTMLTableCellElement | null - The cell's TD element.

# getCellEditor

Source code (opens new window)

core.getCellEditor(row, column) ⇒ function

Returns the cell editor class by the provided row and column arguments.

Example

// Get cell editor class using `row` and `column` coordinates.
hot.getCellEditor(1, 1);
// Get cell editor class using cell meta object.
hot.getCellEditor(hot.getCellMeta(1, 1));
Param Type Description
row number Visual row index or cell meta object (see Core#getCellMeta).
column number Visual column index.

Returns: function - The editor class.

# getCellMeta

Source code (opens new window)

core.getCellMeta(row, column) ⇒ object

Returns the cell properties object for the given row and column coordinates.

Emits: Hooks#event:beforeGetCellMeta, Hooks#event:afterGetCellMeta

Param Type Description
row number Visual row index.
column number Visual column index.

Returns: object - The cell properties object.

# getCellMetaAtRow

Source code (opens new window)

core.getCellMetaAtRow(row) ⇒ Array

Returns an array of cell meta objects for specified physical row index.

Param Type Description
row number Physical row index.

# getCellRenderer

Source code (opens new window)

core.getCellRenderer(row, column) ⇒ function

Returns the cell renderer function by given row and column arguments.

Example

// Get cell renderer using `row` and `column` coordinates.
hot.getCellRenderer(1, 1);
// Get cell renderer using cell meta object.
hot.getCellRenderer(hot.getCellMeta(1, 1));
Param Type Description
row number
object		 Visual row index or cell meta object (see Core#getCellMeta).
column number Visual column index.

Returns: function - The renderer function.

# getCellsMeta

Source code (opens new window)

core.getCellsMeta() ⇒ Array

Get all the cells meta settings at least once generated in the table (in order of cell initialization).

Returns: Array - Returns an array of ColumnSettings object instances.

# getCellValidator

Source code (opens new window)

core.getCellValidator(row, column) ⇒ function | RegExp | undefined

Returns the cell validator by row and column.

Example

// Get cell valiator using `row` and `column` coordinates.
hot.getCellValidator(1, 1);
// Get cell valiator using cell meta object.
hot.getCellValidator(hot.getCellMeta(1, 1));
Param Type Description
row number
object		 Visual row index or cell meta object (see Core#getCellMeta).
column number Visual column index.

Returns: function | RegExp | undefined - The validator function.

# getColHeader

Source code (opens new window)

core.getColHeader([column]) ⇒ Array | string | number

Returns an array of column headers (in string format, if they are enabled). If param column is given, it returns the header at the given column.

Emits: Hooks#event:modifyColHeader

Param Type Description
[column] number optional Visual column index.

Returns: Array | string | number - The column header(s).

# getColWidth

Source code (opens new window)

core.getColWidth(column) ⇒ number

Returns the width of the requested column.

Emits: Hooks#event:modifyColWidth

Param Type Description
column number Visual column index.

Returns: number - Column width.

# getCoords

Source code (opens new window)

core.getCoords(element) ⇒ CellCoords | null

Returns the coordinates of the cell, provided as a HTML table cell element.

Example

hot.getCoords(hot.getCell(1, 1));
// it returns CellCoords object instance with props row: 1 and col: 1.
Param Type Description
element HTMLTableCellElement The HTML Element representing the cell.

Returns: CellCoords | null - Visual coordinates object.

# getCopyableData

Source code (opens new window)

core.getCopyableData(row, column) ⇒ string

Returns the data's copyable value at specified row and column index.

Param Type Description
row number Visual row index.
column number Visual column index.

# getCopyableText

Source code (opens new window)

core.getCopyableText(startRow, startCol, endRow, endCol) ⇒ string

Returns a string value of the selected range. Each column is separated by tab, each row is separated by a new line character.

Param Type Description
startRow number From visual row index.
startCol number From visual column index.
endRow number To visual row index.
endCol number To visual column index.

# getData

Source code (opens new window)

core.getData([row], [column], [row2], [column2]) ⇒ Array<Array>

Returns the current data object (the same one that was passed by data configuration option or loadData method, unless some modifications have been applied (i.e. Sequence of rows/columns was changed, some row/column was skipped). If that's the case - use the Core#getSourceData method.).

Optionally you can provide cell range by defining row, column, row2, column2 to get only a fragment of table data.

Example

// Get all data (in order how it is rendered in the table).
hot.getData();
// Get data fragment (from top-left 0, 0 to bottom-right 3, 3).
hot.getData(3, 3);
// Get data fragment (from top-left 2, 1 to bottom-right 3, 3).
hot.getData(2, 1, 3, 3);
Param Type Description
[row] number optional From visual row index.
[column] number optional From visual column index.
[row2] number optional To visual row index.
[column2] number optional To visual column index.

Returns: Array<Array> - Array with the data.

# getDataAtCell

Source code (opens new window)

core.getDataAtCell(row, column) ⇒ *

Returns the cell value at row, column.

Note: If data is reordered, sorted or trimmed, the currently visible order will be used.

Param Type Description
row number Visual row index.
column number Visual column index.

Returns: * - Data at cell.

# getDataAtCol

Source code (opens new window)

core.getDataAtCol(column) ⇒ Array

Returns array of column values from the data source.

Note: If columns were reordered or sorted, the currently visible order will be used.

Param Type Description
column number Visual column index.

Returns: Array - Array of cell values.

# getDataAtProp

Source code (opens new window)

core.getDataAtProp(prop) ⇒ Array

Given the object property name (e.g. 'first.name' or '0'), returns an array of column's values from the table data. You can also provide a column index as the first argument.

Param Type Description
prop string
number		 Property name or physical column index.

Returns: Array - Array of cell values.

# getDataAtRow

Source code (opens new window)

core.getDataAtRow(row) ⇒ Array

Returns a single row of the data.

Note: If rows were reordered, sorted or trimmed, the currently visible order will be used.

Param Type Description
row number Visual row index.

Returns: Array - Array of row's cell data.

# getDataAtRowProp

Source code (opens new window)

core.getDataAtRowProp(row, prop) ⇒ *

Returns value at visual row and prop indexes.

Note: If data is reordered, sorted or trimmed, the currently visible order will be used.

Param Type Description
row number Visual row index.
prop string Property name.

Returns: * - Cell value.

# getDataType

Source code (opens new window)

core.getDataType(rowFrom, columnFrom, rowTo, columnTo) ⇒ string

Returns a data type defined in the Handsontable settings under the type key (Options#type). If there are cells with different types in the selected range, it returns 'mixed'.

Note: If data is reordered, sorted or trimmed, the currently visible order will be used.

Param Type Description
rowFrom number From visual row index.
columnFrom number From visual column index.
rowTo number To visual row index.
columnTo number To visual column index.

Returns: string - Cell type (e.q: 'mixed', 'text', 'numeric', 'autocomplete').

# getInstance

Source code (opens new window)

core.getInstance() ⇒ Handsontable

Returns the Handsontable instance.

Returns: Handsontable - The Handsontable instance.

# getPlugin

Source code (opens new window)

core.getPlugin(pluginName) ⇒ BasePlugin | undefined

Returns plugin instance by provided its name.

Param Type Description
pluginName string The plugin name.

Returns: BasePlugin | undefined - The plugin instance or undefined if there is no plugin.

# getRowHeader

Source code (opens new window)

core.getRowHeader([row]) ⇒ Array | string | number

Returns an array of row headers' values (if they are enabled). If param row was given, it returns the header of the given row as a string.

Emits: Hooks#event:modifyRowHeader

Param Type Description
[row] number optional Visual row index.

Returns: Array | string | number - Array of header values / single header value.

# getRowHeight

Source code (opens new window)

core.getRowHeight(row) ⇒ number

Returns the row height.

Mind that this method is different from the AutoRowSize plugin's getRowHeight() method.

Emits: Hooks#event:modifyRowHeight

Param Type Description
row number Visual row index.

Returns: number - The given row's height.

# getSchema

Source code (opens new window)

core.getSchema() ⇒ object

Returns schema provided by constructor settings. If it doesn't exist then it returns the schema based on the data structure in the first row.

Returns: object - Schema object.

# getSelected

Source code (opens new window)

core.getSelected() ⇒ Array<Array> | undefined

Returns indexes of the currently selected cells as an array of arrays [[startRow, startCol, endRow, endCol],...].

Start row and start column are the coordinates of the active cell (where the selection was started).

The version 0.36.0 adds a non-consecutive selection feature. Since this version, the method returns an array of arrays. Additionally to collect the coordinates of the currently selected area (as it was previously done by the method) you need to use getSelectedLast method.

Returns: Array<Array> | undefined - An array of arrays of the selection's coordinates.

# getSelectedLast

Source code (opens new window)

core.getSelectedLast() ⇒ Array | undefined

Returns the last coordinates applied to the table as a an array [startRow, startCol, endRow, endCol].

Since: 0.36.0

Returns: Array | undefined - An array of the selection's coordinates.

# getSelectedRange

Source code (opens new window)

core.getSelectedRange() ⇒ Array<CellRange> | undefined

Returns the current selection as an array of CellRange objects.

The version 0.36.0 adds a non-consecutive selection feature. Since this version, the method returns an array of arrays. Additionally to collect the coordinates of the currently selected area (as it was previously done by the method) you need to use getSelectedRangeLast method.

Returns: Array<[CellRange](/api/cell-range/)> | undefined - Selected range object or undefined if there is no selection.

# getSelectedRangeLast

Source code (opens new window)

core.getSelectedRangeLast() ⇒ CellRange | undefined

Returns the last coordinates applied to the table as a CellRange object.

Since: 0.36.0

Returns: CellRange | undefined - Selected range object or undefined` if there is no selection.

# getSettings

Source code (opens new window)

core.getSettings() ⇒ object

Returns the object settings.

Returns: object - Object containing the current table settings.

# getSourceData

Source code (opens new window)

core.getSourceData([row], [column], [row2], [column2]) ⇒ Array<Array> | Array<object>

Returns a clone of the source data object. Optionally you can provide a cell range by using the row, column, row2, column2 arguments, to get only a fragment of the table data.

Note: This method does not participate in data transformation. If the visual data of the table is reordered, sorted or trimmed only physical indexes are correct.

Param Type Description
[row] number optional From physical row index.
[column] number optional From physical column index (or visual index, if data type is an array of objects).
[row2] number optional To physical row index.
[column2] number optional To physical column index (or visual index, if data type is an array of objects).

Returns: Array<Array> | Array<object> - The table data.

# getSourceDataArray

Source code (opens new window)

core.getSourceDataArray([row], [column], [row2], [column2]) ⇒ Array

Returns the source data object as an arrays of arrays format even when source data was provided in another format. Optionally you can provide a cell range by using the row, column, row2, column2 arguments, to get only a fragment of the table data.

Note: This method does not participate in data transformation. If the visual data of the table is reordered, sorted or trimmed only physical indexes are correct.

Param Type Description
[row] number optional From physical row index.
[column] number optional From physical column index (or visual index, if data type is an array of objects).
[row2] number optional To physical row index.
[column2] number optional To physical column index (or visual index, if data type is an array of objects).

Returns: Array - An array of arrays.

# getSourceDataAtCell

Source code (opens new window)

core.getSourceDataAtCell(row, column) ⇒ *

Returns a single value from the data source.

Param Type Description
row number Physical row index.
column number Visual column index.

Returns: * - Cell data.

# getSourceDataAtCol

Source code (opens new window)

core.getSourceDataAtCol(column) ⇒ Array

Returns an array of column values from the data source.

Param Type Description
column number Visual column index.

Returns: Array - Array of the column's cell values.

# getSourceDataAtRow

Source code (opens new window)

core.getSourceDataAtRow(row) ⇒ Array | object

Returns a single row of the data (array or object, depending on what data format you use).

Note: This method does not participate in data transformation. If the visual data of the table is reordered, sorted or trimmed only physical indexes are correct.

Param Type Description
row number Physical row index.

Returns: Array | object - Single row of data.

# getTranslatedPhrase

Source code (opens new window)

core.getTranslatedPhrase(dictionaryKey, extraArguments) ⇒ string

Get language phrase for specified dictionary key.

Since: 0.35.0

Param Type Description
dictionaryKey string Constant which is dictionary key.
extraArguments * Arguments which will be handled by formatters.

# getValue

Source code (opens new window)

core.getValue() ⇒ *

Get value from the selected cell.

Returns: * - Value of selected cell.

# hasColHeaders

Source code (opens new window)

core.hasColHeaders() ⇒ boolean

Returns information about if this table is configured to display column headers.

Returns: boolean - true if the instance has the column headers enabled, false otherwise.

# hasHook

Source code (opens new window)

core.hasHook(key) ⇒ boolean

Check if for a specified hook name there are added listeners (only for this Handsontable instance). All available hooks you will find Hooks.

See: Hooks#has Example

const hasBeforeInitListeners = hot.hasHook('beforeInit');
Param Type Description
key string Hook name.

# hasRowHeaders

Source code (opens new window)

core.hasRowHeaders() ⇒ boolean

Returns information about if this table is configured to display row headers.

Returns: boolean - true if the instance has the row headers enabled, false otherwise.

# isColumnModificationAllowed

Source code (opens new window)

core.isColumnModificationAllowed() ⇒ boolean

Checks if the data format and config allows user to modify the column structure.

# isEmptyCol

Source code (opens new window)

core.isEmptyCol(column) ⇒ boolean

Check if all cells in the the column declared by the column argument are empty.

Param Type Description
column number Column index.

Returns: boolean - true if the column at the given col is empty, false otherwise.

# isEmptyRow

Source code (opens new window)

core.isEmptyRow(row) ⇒ boolean

Check if all cells in the row declared by the row argument are empty.

Param Type Description
row number Visual row index.

Returns: boolean - true if the row at the given row is empty, false otherwise.

# isExecutionSuspended

Source code (opens new window)

core.isExecutionSuspended() ⇒ boolean

Checks if the table indexes recalculation process was suspended. See explanation in Core#suspendExecution.

Since: 8.3.0

# isListening

Source code (opens new window)

core.isListening() ⇒ boolean

Returns true if the current Handsontable instance is listening to keyboard input on document body.

Returns: boolean - true if the instance is listening, false otherwise.

# isRedoAvailable

Source code (opens new window)

core.isRedoAvailable() ⇒ boolean

UndoRedo#isRedoAvailable.

# isRenderSuspended

Source code (opens new window)

core.isRenderSuspended() ⇒ boolean

Checks if the table rendering process was suspended. See explanation in Core#suspendRender.

Since: 8.3.0

# isUndoAvailable

Source code (opens new window)

core.isUndoAvailable() ⇒ boolean

UndoRedo#isUndoAvailable.

# listen

Source code (opens new window)

core.listen()

Listen to the keyboard input on document body. This allows Handsontable to capture keyboard events and respond in the right way.

Emits: Hooks#event:afterListen

# loadData

Source code (opens new window)

core.loadData(data, [source])

Loads new data to Handsontable. Loading new data resets the cell meta. Since 8.0.0 loading new data also resets states corresponding to rows and columns (for example, row/column sequence, column width, row height, frozen columns etc.).

Emits: Hooks#event:beforeLoadData, Hooks#event:afterLoadData, Hooks#event:afterChange

Param Type Description
data Array Array of arrays or array of objects containing data.
[source] string optional Source of the loadData call.

# populateFromArray

Source code (opens new window)

core.populateFromArray(row, column, input, [endRow], [endCol], [source], [method], direction, deltas) ⇒ object | undefined

Populate cells at position with 2D input array (e.g. [[1, 2], [3, 4]]). Use endRow, endCol when you want to cut input when a certain row is reached.

Optional method argument has the same effect as pasteMode option (see Options#pasteMode).

Param Type Default Description
row number Start visual row index.
column number Start visual column index.
input Array 2d array.
[endRow] number optional End visual row index (use when you want to cut input when certain row is reached).
[endCol] number optional End visual column index (use when you want to cut input when certain column is reached).
[source] string "populateFromArray" optional Used to identify this call in the resulting events (beforeChange, afterChange).
[method] string "overwrite" optional Populate method, possible values: 'shift_down', 'shift_right', 'overwrite'.
direction string Populate direction, possible values: 'left', 'right', 'up', 'down'.
deltas Array The deltas array. A difference between values of adjacent cells. Useful only when the type of handled cells is numeric.

Returns: object | undefined - Ending td in pasted area (only if any cell was changed).

# propToCol

Source code (opens new window)

core.propToCol(prop) ⇒ number

Returns column index that corresponds with the given property.

Param Type Description
prop string
number		 Property name or physical column index.

Returns: number - Visual column index.

# redo

Source code (opens new window)

core.redo() ⇒ boolean

UndoRedo#redo.

# refreshDimensions

Source code (opens new window)

core.refreshDimensions()

Updates dimensions of the table. The method compares previous dimensions with the current ones and updates accordingly.

Emits: Hooks#event:beforeRefreshDimensions, Hooks#event:afterRefreshDimensions

# removeCellMeta

Source code (opens new window)

core.removeCellMeta(row, column, key)

Remove a property defined by the key argument from the cell meta object for the provided row and column coordinates.

Emits: Hooks#event:beforeRemoveCellMeta, Hooks#event:afterRemoveCellMeta

Param Type Description
row number Visual row index.
column number Visual column index.
key string Property name.

# removeHook

Source code (opens new window)

core.removeHook(key, callback)

Removes the hook listener previously registered with Core#addHook.

See: Hooks#remove Example

hot.removeHook('beforeInit', myCallback);
Param Type Description
key string Hook name.
callback function Reference to the function which has been registered using Core#addHook.

# render

Source code (opens new window)

core.render()

Rerender the table. Calling this method starts the process of recalculating, redrawing and applying the changes to the DOM. While rendering the table all cell renderers are recalled.

Calling this method manually is not recommended. Handsontable tries to render itself by choosing the most optimal moments in its lifecycle.

# resumeExecution

Source code (opens new window)

core.resumeExecution([forceFlushChanges])

Resumes the execution process. In combination with the Core#suspendExecution method it allows aggregating the table logic changes after which the cache is updated. Resuming the state automatically invokes the table cache updating process.

The method is intended to be used by advanced users. Suspending the execution process could cause visual glitches caused by not updated the internal table cache.

Since: 8.3.0 Example

hot.suspendExecution();
const filters = hot.getPlugin('filters');

filters.addCondition(2, 'contains', ['3']);
filters.filter();
hot.getPlugin('columnSorting').sort({ column: 1, sortOrder: 'desc' });
hot.resumeExecution(); // It updates the cache internally
Param Type Default Description
[forceFlushChanges] boolean false optional If true, the table internal data cache is recalculated after the execution of the batched operations. For nested Core#batchExecution calls, it can be desire to recalculate the table after each batch.

# resumeRender

Source code (opens new window)

core.resumeRender()

Resumes the rendering process. In combination with the Core#suspendRender method it allows aggregating the table render cycles triggered by API calls or UI actions (or both) and calls the "render" once in the end. When the table is in the suspend state, most operations will have no visual effect until the rendering state is resumed. Resuming the state automatically invokes the table rendering.

The method is intended to be used by advanced users. Suspending the rendering process could cause visual glitches when wrongly implemented.

Since: 8.3.0 Example

hot.suspendRender();
hot.alter('insert_row', 5, 45);
hot.alter('insert_col', 10, 40);
hot.setDataAtCell(1, 1, 'John');
hot.setDataAtCell(2, 2, 'Mark');
hot.setDataAtCell(3, 3, 'Ann');
hot.setDataAtCell(4, 4, 'Sophia');
hot.setDataAtCell(5, 5, 'Mia');
hot.selectCell(0, 0);
hot.resumeRender(); // It re-renders the table internally

# runHooks

Source code (opens new window)

core.runHooks(key, [p1], [p2], [p3], [p4], [p5], [p6]) ⇒ *

Run the callbacks for the hook provided in the key argument using the parameters given in the other arguments.

See: Hooks#run Example

// Run built-in hook
hot.runHooks('beforeInit');
// Run custom hook
hot.runHooks('customAction', 10, 'foo');
Param Type Description
key string Hook name.
[p1] * optional Argument passed to the callback.
[p2] * optional Argument passed to the callback.
[p3] * optional Argument passed to the callback.
[p4] * optional Argument passed to the callback.
[p5] * optional Argument passed to the callback.
[p6] * optional Argument passed to the callback.

# scrollViewportTo

Source code (opens new window)

core.scrollViewportTo([row], [column], [snapToBottom], [snapToRight], [considerHiddenIndexes]) ⇒ boolean

Scroll viewport to coordinates specified by the row and column arguments.

Param Type Default Description
[row] number optional Row index. If the last argument isn't defined we treat the index as a visual row index. Otherwise, we are using the index for numbering only this rows which may be rendered (we don't consider hidden rows).
[column] number optional Column index. If the last argument isn't defined we treat the index as a visual column index. Otherwise, we are using the index for numbering only this columns which may be rendered (we don't consider hidden columns).
[snapToBottom] boolean false optional If true, viewport is scrolled to show the cell on the bottom of the table.
[snapToRight] boolean false optional If true, viewport is scrolled to show the cell on the right side of the table.
[considerHiddenIndexes] boolean true optional If true, we handle visual indexes, otherwise we handle only indexes which may be rendered when they are in the viewport (we don't consider hidden indexes as they aren't rendered).

Returns: boolean - true if scroll was successful, false otherwise.

# selectAll

Source code (opens new window)

core.selectAll([includeHeaders])

Select the whole table. The previous selection will be overwritten.

Since: 0.38.2

Param Type Default Description
[includeHeaders] boolean true optional true If the selection should include the row, column and corner headers, false otherwise.

# selectCell

Source code (opens new window)

core.selectCell(row, column, [endRow], [endColumn], [scrollToCell], [changeListener]) ⇒ boolean

Select cell specified by row and column values or a range of cells finishing at endRow, endCol. If the table was configured to support data column properties that properties can be used to making a selection.

By default, viewport will be scrolled to the selection. After the selectCell method had finished, the instance will be listening to keyboard input on the document.

Example

// select a single cell
hot.selectCell(2, 4);
// select a single cell using column property
hot.selectCell(2, 'address');
// select a range of cells
hot.selectCell(2, 4, 3, 5);
// select a range of cells using column properties
hot.selectCell(2, 'address', 3, 'phone_number');
// select a range of cells without scrolling to them
hot.selectCell(2, 'address', 3, 'phone_number', false);
Param Type Default Description
row number Visual row index.
column number
string		 Visual column index or column property.
[endRow] number optional Visual end row index (if selecting a range).
[endColumn] number
string		 optional Visual end column index or column property (if selecting a range).
[scrollToCell] boolean true optional If true, the viewport will be scrolled to the selection.
[changeListener] boolean true optional If false, Handsontable will not change keyboard events listener to himself.

Returns: boolean - true if selection was successful, false otherwise.

# selectCells

Source code (opens new window)

core.selectCells(coords, [scrollToCell], [changeListener]) ⇒ boolean

Make multiple, non-contiguous selection specified by row and column values or a range of cells finishing at endRow, endColumn. The method supports two input formats which are the same as that produces by getSelected and getSelectedRange methods.

By default, viewport will be scrolled to selection. After the selectCells method had finished, the instance will be listening to keyboard input on the document.

Since: 0.38.0 Example

// Using an array of arrays.
hot.selectCells([[1, 1, 2, 2], [3, 3], [6, 2, 0, 2]]);
// Using an array of arrays with defined columns as props.
hot.selectCells([[1, 'id', 2, 'first_name'], [3, 'full_name'], [6, 'last_name', 0, 'first_name']]);
// Using an array of CellRange objects (produced by `.getSelectedRange()` method).
const selected = hot.getSelectedRange();

selected[0].from.row = 0;
selected[0].from.col = 0;

hot.selectCells(selected);
Param Type Default Description
coords Array<Array>
Array<CellRange>		 Visual coords passed as an array of array ([[rowStart, columnStart, rowEnd, columnEnd], ...]) the same format as getSelected method returns or as an CellRange objects which is the same format what getSelectedRange method returns.
[scrollToCell] boolean true optional If true, the viewport will be scrolled to the selection.
[changeListener] boolean true optional If false, Handsontable will not change keyboard events listener to himself.

Returns: boolean - true if selection was successful, false otherwise.

# selectColumns

Source code (opens new window)

core.selectColumns(startColumn, [endColumn]) ⇒ boolean

Select column specified by startColumn visual index, column property or a range of columns finishing at endColumn.

Since: 0.38.0 Example

// Select column using visual index.
hot.selectColumns(1);
// Select column using column property.
hot.selectColumns('id');
// Select range of columns using visual indexes.
hot.selectColumns(1, 4);
// Select range of columns using column properties.
hot.selectColumns('id', 'last_name');
Param Type Default Description
startColumn number The visual column index from which the selection starts.
[endColumn] number startColumn optional The visual column index to which the selection finishes. If endColumn is not defined the column defined by startColumn will be selected.

Returns: boolean - true if selection was successful, false otherwise.

# selectRows

Source code (opens new window)

core.selectRows(startRow, [endRow]) ⇒ boolean

Select row specified by startRow visual index or a range of rows finishing at endRow.

Since: 0.38.0 Example

// Select row using visual index.
hot.selectRows(1);
// Select range of rows using visual indexes.
hot.selectRows(1, 4);
Param Type Default Description
startRow number The visual row index from which the selection starts.
[endRow] number startRow optional The visual row index to which the selection finishes. If endRow is not defined the row defined by startRow will be selected.

Returns: boolean - true if selection was successful, false otherwise.

# setCellMeta

Source code (opens new window)

core.setCellMeta(row, column, key, value)

Sets a property defined by the key property to the meta object of a cell corresponding to params row and column.

Emits: Hooks#event:beforeSetCellMeta, Hooks#event:afterSetCellMeta

Param Type Description
row number Visual row index.
column number Visual column index.
key string Property name.
value string Property value.

# setCellMetaObject

Source code (opens new window)

core.setCellMetaObject(row, column, prop)

Set cell meta data object defined by prop to the corresponding params row and column.

Param Type Description
row number Visual row index.
column number Visual column index.
prop object Meta object.

# setDataAtCell

Source code (opens new window)

core.setDataAtCell(row, [column], [value], [source])

Set new value to a cell. To change many cells at once (recommended way), pass an array of changes in format [[row, col, value],...] as the first argument.

Param Type Description
row number
Array		 Visual row index or array of changes in format [[row, col, value],...].
[column] number optional Visual column index.
[value] string optional New value.
[source] string optional String that identifies how this change will be described in the changes array (useful in afterChange or beforeChange callback). Set to 'edit' if left empty.

# setDataAtRowProp

Source code (opens new window)

core.setDataAtRowProp(row, prop, value, [source])

Set new value to a cell. To change many cells at once (recommended way), pass an array of changes in format [[row, prop, value],...] as the first argument.

Param Type Description
row number
Array		 Visual row index or array of changes in format [[row, prop, value], ...].
prop string Property name or the source string (e.g. 'first.name' or '0').
value string Value to be set.
[source] string optional String that identifies how this change will be described in changes array (useful in onChange callback).

# setSourceDataAtCell

Source code (opens new window)

core.setSourceDataAtCell(row, column, value, [source])

Set the provided value in the source data set at the provided coordinates.

Param Type Description
row number
Array		 Physical row index or array of changes in format [[row, prop, value], ...].
column number
string		 Physical column index / prop name.
value * The value to be set at the provided coordinates.
[source] string optional Source of the change as a string.

# spliceCellsMeta

Source code (opens new window)

core.spliceCellsMeta(visualIndex, [deleteAmount], [...cellMetaRows])

Removes or adds one or more rows of the cell meta objects to the cell meta collections.

Since: 0.30.0

Param Type Default Description
visualIndex number A visual index that specifies at what position to add/remove items.
[deleteAmount] number 0 optional The number of items to be removed. If set to 0, no cell meta objects will be removed.
[...cellMetaRows] object optional The new cell meta row objects to be added to the cell meta collection.

# spliceCol

Source code (opens new window)

core.spliceCol(column, index, amount, [...elements]) ⇒ Array

Adds/removes data from the column. This method works the same as Array.splice for arrays.

Param Type Description
column number Index of the column in which do you want to do splice.
index number Index at which to start changing the array. If negative, will begin that many elements from the end.
amount number An integer indicating the number of old array elements to remove. If amount is 0, no elements are removed.
[...elements] number optional The elements to add to the array. If you don't specify any elements, spliceCol simply removes elements from the array.

Returns: Array - Returns removed portion of columns.

# spliceRow

Source code (opens new window)

core.spliceRow(row, index, amount, [...elements]) ⇒ Array

Adds/removes data from the row. This method works the same as Array.splice for arrays.

Param Type Description
row number Index of column in which do you want to do splice.
index number Index at which to start changing the array. If negative, will begin that many elements from the end.
amount number An integer indicating the number of old array elements to remove. If amount is 0, no elements are removed.
[...elements] number optional The elements to add to the array. If you don't specify any elements, spliceCol simply removes elements from the array.

Returns: Array - Returns removed portion of rows.

# suspendExecution

Source code (opens new window)

core.suspendExecution()

Suspends the execution process. It's helpful to wrap the table logic changes such as index changes into one call after which the cache is updated. As a result, it improves the performance of wrapped operations.

The method is intended to be used by advanced users. Suspending the execution process could cause visual glitches caused by not updated the internal table cache.

Since: 8.3.0 Example

hot.suspendExecution();
const filters = hot.getPlugin('filters');

filters.addCondition(2, 'contains', ['3']);
filters.filter();
hot.getPlugin('columnSorting').sort({ column: 1, sortOrder: 'desc' });
hot.resumeExecution(); // It updates the cache internally

# suspendRender

Source code (opens new window)

core.suspendRender()

Suspends the rendering process. It's helpful to wrap the table render cycles triggered by API calls or UI actions (or both) and call the "render" once in the end. As a result, it improves the performance of wrapped operations. When the table is in the suspend state, most operations will have no visual effect until the rendering state is resumed. Resuming the state automatically invokes the table rendering. To make sure that after executing all operations, the table will be rendered, it's highly recommended to use the Core#batchRender method or Core#batch, which additionally aggregates the logic execution that happens behind the table.

The method is intended to be used by advanced users. Suspending the rendering process could cause visual glitches when wrongly implemented.

Since: 8.3.0 Example

hot.suspendRender();
hot.alter('insert_row', 5, 45);
hot.alter('insert_col', 10, 40);
hot.setDataAtCell(1, 1, 'John');
hot.setDataAtCell(2, 2, 'Mark');
hot.setDataAtCell(3, 3, 'Ann');
hot.setDataAtCell(4, 4, 'Sophia');
hot.setDataAtCell(5, 5, 'Mia');
hot.selectCell(0, 0);
hot.resumeRender(); // It re-renders the table internally

# toHTML

Source code (opens new window)

core.toHTML() ⇒ string

Converts instance into outerHTML of HTMLTableElement.

Since: 7.1.0

# toPhysicalColumn

Source code (opens new window)

core.toPhysicalColumn(column) ⇒ number

Translate visual column index into physical.

This method is useful when you want to retrieve physical column index based on a visual index which can be reordered, moved or trimmed.

Param Type Description
column number Visual column index.

Returns: number - Returns physical column index.

# toPhysicalRow

Source code (opens new window)

core.toPhysicalRow(row) ⇒ number

Translate visual row index into physical.

This method is useful when you want to retrieve physical row index based on a visual index which can be reordered, moved or trimmed.

Param Type Description
row number Visual row index.

Returns: number - Returns physical row index.

# toTableElement

Source code (opens new window)

core.toTableElement() ⇒ HTMLTableElement

Converts instance into HTMLTableElement.

Since: 7.1.0

# toVisualColumn

Source code (opens new window)

core.toVisualColumn(column) ⇒ number

Translate physical column index into visual.

This method is useful when you want to retrieve visual column index which can be reordered, moved or trimmed based on a physical index.

Param Type Description
column number Physical column index.

Returns: number - Returns visual column index.

# toVisualRow

Source code (opens new window)

core.toVisualRow(row) ⇒ number

Translate physical row index into visual.

This method is useful when you want to retrieve visual row index which can be reordered, moved or trimmed based on a physical index.

Param Type Description
row number Physical row index.

Returns: number - Returns visual row index.

# undo

Source code (opens new window)

core.undo() ⇒ boolean

UndoRedo#undo.

# unlisten

Source code (opens new window)

core.unlisten()

Stop listening to keyboard input on the document body. Calling this method makes the Handsontable inactive for any keyboard events.

# updateSettings

Source code (opens new window)

core.updateSettings(settings, [init])

Use it if you need to change configuration after initialization. The settings argument is an object containing the new settings, declared the same way as in the initial settings object.

Note, that although the updateSettings method doesn't overwrite the previously declared settings, it might reset the settings made post-initialization. (for example - ignore changes made using the columnResize feature).

Since 8.0.0 passing columns or data inside settings objects will result in resetting states corresponding to rows and columns (for example, row/column sequence, column width, row height, frozen columns etc.).

Emits: Hooks#event:afterCellMetaReset, Hooks#event:afterUpdateSettings Example

hot.updateSettings({
   contextMenu: true,
   colHeaders: true,
   fixedRowsTop: 2
});
Param Type Default Description
settings object New settings object (see Options).
[init] boolean false optional Internally used for in initialization mode.

# validateCell

Source code (opens new window)

core.validateCell(value, cellProperties, callback, source)

Validate a single cell.

Param Type Description
value string
number		 The value to validate.
cellProperties object The cell meta which corresponds with the value.
callback function The callback function.
source string The string that identifies source of the validation.

# validateCells

Source code (opens new window)

core.validateCells([callback])

Validates all cells using their validator functions and calls callback when finished.

If one of the cells is invalid, the callback will be fired with 'valid' arguments as false - otherwise it would equal true.

Example

hot.validateCells((valid) => {
  if (valid) {
    // ... code for validated cells
  }
})
Param Type Description
[callback] function optional The callback function.

# validateColumns

Source code (opens new window)

core.validateColumns([columns], [callback])

Validates columns using their validator functions and calls callback when finished.

If one of the cells is invalid, the callback will be fired with 'valid' arguments as false - otherwise it would equal true.

Example

hot.validateColumns([3, 4, 5], (valid) => {
  if (valid) {
    // ... code for validated columns
  }
})
Param Type Description
[columns] Array optional Array of validation target visual columns indexes.
[callback] function optional The callback function.

# validateRows

Source code (opens new window)

core.validateRows([rows], [callback])

Validates rows using their validator functions and calls callback when finished.

If one of the cells is invalid, the callback will be fired with 'valid' arguments as false - otherwise it would equal true.

Example

hot.validateRows([3, 4, 5], (valid) => {
  if (valid) {
    // ... code for validated rows
  }
})
Param Type Description
[rows] Array optional Array of validation target visual row indexes.
[callback] function optional The callback function.
Last Updated: Apr 12, 2024

← Hooks →