JavaScript Data GridCore

Description

The Handsontable class (known as the Core) lets you modify the grid's behavior by using Handsontable's public API methods.

How to call a method

// create a Handsontable instance
const hot = new Handsontable(document.getElementById('example'), options);

// call a method
hot.setDataAtCell(0, 0, 'new value');

Members

columnIndexMapper

core.columnIndexMapper : IndexMapper

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

isDestroyed

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

core.rowIndexMapper : IndexMapper

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

Methods

addHook

core.addHook(key, callback, [orderIndex])

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

See: Hooks#add
Example

hot.addHook('beforeInit', myCallback);

addHookOnce

core.addHookOnce(key, callback, [orderIndex])

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

alter

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

The alter() method lets you alter the grid's structure by adding or removing rows and columns at specified positions.

// above row 10 (by visual index), insert 1 new row
hot.alter('insert_row_above', 10);

Additional information about 'insert_col_start' and 'insert_col_end':

• Their behavior depends on your layoutDirection.
• If the provided index is higher than the actual number of columns, Handsontable doesn't generate the columns missing in between. Instead, the new columns are inserted next to the last column.

Example

// above row 10 (by visual index), insert 1 new row
hot.alter('insert_row_above', 10);

// below row 10 (by visual index), insert 3 new rows
hot.alter('insert_row_below', 10, 3);

// in the LTR layout direction: to the left of column 10 (by visual index), insert 3 new columns
// in the RTL layout direction: to the right of column 10 (by visual index), insert 3 new columns
hot.alter('insert_col_start', 10, 3);

// in the LTR layout direction: to the right of column 10 (by visual index), insert 1 new column
// in the RTL layout direction: to the left of column 10 (by visual index), insert 1 new column
hot.alter('insert_col_end', 10);

// remove 2 rows, starting from row 10 (by visual index)
hot.alter('remove_row', 10, 2);

// remove 3 rows, starting from row 1 (by visual index)
// remove 2 rows, starting from row 5 (by visual index)
hot.alter('remove_row', [[1, 3], [5, 2]]);

batch

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_above', 5, 45);
  hot.alter('insert_col_start', 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
});

Returns: * - Returns result from the wrappedOperations callback.

batchExecution

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
});

Returns: * - Returns result from the wrappedOperations callback.

batchRender

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_above', 5, 45);
  hot.alter('insert_col_start', 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
});

Returns: * - Returns result from the wrappedOperations callback.

clear

core.clear()

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

clearUndo

core.clearUndo()

UndoRedo#clear.

colToProp

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.

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

countColHeaders

core.countColHeaders() ⇒ number

Returns the number of rendered column headers.

Since: 14.0.0

Returns: number - Number of column headers.

countCols

core.countCols() ⇒ number

Returns the total number of visible columns in the table.

Returns: number - Total number of columns.

countEmptyCols

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.

Returns: number - Count empty cols.

countEmptyRows

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.

Returns: number - Count empty rows.

countRenderedCols

core.countRenderedCols() ⇒ number

Returns the number of rendered rows including columns that are partially or fully rendered outside the table viewport.

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

countRenderedRows

core.countRenderedRows() ⇒ number

Returns the number of rendered rows including rows that are partially or fully rendered outside the table viewport.

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

countRowHeaders

core.countRowHeaders() ⇒ number

Returns the number of rendered row headers.

Since: 14.0.0

Returns: number - Number of row headers.

countRows

core.countRows() ⇒ number

Returns the total number of visual rows in the table.

Returns: number - Total number of rows.

countSourceCols

core.countSourceCols() ⇒ number

Returns the total number of columns in the data source.

Returns: number - Total number of columns.

countSourceRows

core.countSourceRows() ⇒ number

Returns the total number of rows in the data source.

Returns: number - Total number of rows.

countVisibleCols

core.countVisibleCols() ⇒ number

Returns the number of rendered columns that are only visible in the table viewport. The columns that are partially visible are not counted.

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

countVisibleRows

core.countVisibleRows() ⇒ number

Returns the number of rendered rows that are only visible in the table viewport. The rows that are partially visible are not counted.

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

deselectCell

core.deselectCell()

Deselects the current cell selection on the table.

destroy

core.destroy()

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

Emits: Hooks#event:afterDestroy

destroyEditor

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

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

emptySelectedCells

core.emptySelectedCells([source])

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

Since: 0.36.0

getActiveEditor

core.getActiveEditor() ⇒ BaseEditor

Returns the active editor class instance.

Returns: BaseEditor - The active editor instance.

getCell

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

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

getCellEditor

core.getCellEditor(rowOrMeta, column) ⇒ function | boolean

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

Returns: function | boolean - Returns the editor class or false is cell editor is disabled.

getCellMeta

core.getCellMeta(row, column, options) ⇒ object

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

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

Returns: object - The cell properties object.

getCellMetaAtRow

core.getCellMetaAtRow(row) ⇒ Array

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

getCellRenderer

core.getCellRenderer(rowOrMeta, 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));

Returns: function - Returns the renderer function.

getCellsMeta

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

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

Returns the cell validator by row and column.

Example

// Get cell validator using `row` and `column` coordinates.
hot.getCellValidator(1, 1);
// Get cell validator using cell meta object.
hot.getCellValidator(hot.getCellMeta(1, 1));

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

getColHeader

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

Gets the values of column headers (if column headers are enabled).

To get an array with the values of all bottom-most column headers, call getColHeader() with no arguments.

To get the value of the bottom-most header of a specific column, use the column parameter.

To get the value of a specific-level header of a specific column, use the column and headerLevel parameters.

Read more:

• Guides: Column groups
• Options: colHeaders
• Guides: Copy with headers

// get the contents of all bottom-most column headers
hot.getColHeader();

// get the contents of the bottom-most header of a specific column
hot.getColHeader(5);

// get the contents of a specific column header at a specific level
hot.getColHeader(5, -2);

Emits: Hooks#event:modifyColHeader, Hooks#event:modifyColumnHeaderValue

Returns: Array | string | number - Column header values.

getColumnMeta

core.getColumnMeta(column) ⇒ object

Returns the meta information for the provided column.

Since: 14.5.0

getColWidth

core.getColWidth(column, [source]) ⇒ number

Returns the width of the requested column.

Emits: Hooks#event:modifyColWidth

Returns: number - Column width.

getCoords

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.

Returns: CellCoords | null - Visual coordinates object.

getCopyableData

core.getCopyableData(row, column) ⇒ string

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

getCopyableText

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.

getCurrentThemeName

core.getCurrentThemeName() ⇒ string | undefined

Gets the name of the currently used theme.

Since: 15.0.0

Returns: string | undefined - The name of the currently used theme.

getData

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

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

getDataAtCell

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.

Returns: * - Data at cell.

getDataAtCol

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.

Returns: Array - Array of cell values.

getDataAtProp

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.

Returns: Array - Array of cell values.

getDataAtRow

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.

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

getDataAtRowProp

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.

Returns: * - Cell value.

getDataType

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.

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

getDirectionFactor

core.getDirectionFactor() ⇒ number

Returns 1 for LTR; -1 for RTL. Useful for calculations.

Since: 12.0.0

Returns: number - Returns 1 for LTR; -1 for RTL.

getFirstFullyVisibleColumn

core.getFirstFullyVisibleColumn() ⇒ number | null

Returns the first fully visible column in the table viewport. When the table has overlays the method returns the first row of the main table that is not overlapped by overlay.

Since: 14.6.0

getFirstFullyVisibleRow

core.getFirstFullyVisibleRow() ⇒ number | null

Returns the first fully visible row in the table viewport. When the table has overlays the method returns the first row of the main table that is not overlapped by overlay.

Since: 14.6.0

getFirstPartiallyVisibleColumn

core.getFirstPartiallyVisibleColumn() ⇒ number | null

Returns the first partially visible column in the table viewport. When the table has overlays the method returns the first row of the main table that is not overlapped by overlay.

Since: 14.6.0

getFirstPartiallyVisibleRow

core.getFirstPartiallyVisibleRow() ⇒ number | null

Returns the first partially visible row in the table viewport. When the table has overlays the method returns the first row of the main table that is not overlapped by overlay.

Since: 14.6.0

getFirstRenderedVisibleColumn

core.getFirstRenderedVisibleColumn() ⇒ number | null

Returns the first rendered column in the DOM (usually, it is not visible in the table's viewport).

Since: 14.6.0

getFirstRenderedVisibleRow

core.getFirstRenderedVisibleRow() ⇒ number | null

Returns the first rendered row in the DOM (usually, it is not visible in the table's viewport).

Since: 14.6.0

getFocusManager

core.getFocusManager() ⇒ FocusManager

Return the Focus Manager responsible for managing the browser's focus in the table.

Since: 14.0.0

getInstance

core.getInstance() ⇒ Handsontable

Returns the Handsontable instance.

Returns: Handsontable - The Handsontable instance.

getLastFullyVisibleColumn

core.getLastFullyVisibleColumn() ⇒ number | null

Returns the last fully visible column in the table viewport. When the table has overlays the method returns the first row of the main table that is not overlapped by overlay.

Since: 14.6.0

getLastFullyVisibleRow

core.getLastFullyVisibleRow() ⇒ number | null

Returns the last fully visible row in the table viewport. When the table has overlays the method returns the first row of the main table that is not overlapped by overlay.

Since: 14.6.0

getLastPartiallyVisibleColumn

core.getLastPartiallyVisibleColumn() ⇒ number | null

Returns the last partially visible column in the table viewport. When the table has overlays the method returns the first row of the main table that is not overlapped by overlay.

Since: 14.6.0

getLastPartiallyVisibleRow

core.getLastPartiallyVisibleRow() ⇒ number | null

Returns the last partially visible row in the table viewport. When the table has overlays the method returns the first row of the main table that is not overlapped by overlay.

Since: 14.6.0

getLastRenderedVisibleColumn

core.getLastRenderedVisibleColumn() ⇒ number | null

Returns the last rendered column in the DOM (usually, it is not visible in the table's viewport).

Since: 14.6.0

getLastRenderedVisibleRow

core.getLastRenderedVisibleRow() ⇒ number | null

Returns the last rendered row in the DOM (usually, it is not visible in the table's viewport).

Since: 14.6.0

getPlugin

core.getPlugin(pluginName) ⇒ BasePlugin | undefined

Returns plugin instance by provided its name.

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

getRowHeader

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

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

getRowHeight

core.getRowHeight(row, [source]) ⇒ number | undefined

Returns a row's height, as recognized by Handsontable.

Depending on your configuration, the method returns (in order of priority):

1. The row height set by the ManualRowResize plugin (if the plugin is enabled).
2. The row height set by the rowHeights configuration option (if the option is set).
3. The row height as measured in the DOM by the AutoRowSize plugin (if the plugin is enabled).
4. undefined, if neither ManualRowResize, nor rowHeights, nor AutoRowSize is used.

The height returned includes 1 px of the row's bottom border.

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

Emits: Hooks#event:modifyRowHeight

Returns: number | undefined - The height of the specified row, in pixels.

getSchema

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

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

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

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> | undefined - Selected range object or undefined if there is no selection.

getSelectedRangeLast

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

core.getSettings() ⇒ TableMeta

Returns the object settings.

Returns: TableMeta - Object containing the current table settings.

getShortcutManager

core.getShortcutManager() ⇒ ShortcutManager

Returns instance of a manager responsible for handling shortcuts stored in some contexts. It run actions after pressing key combination in active Handsontable instance.

Since: 12.0.0

Returns: ShortcutManager - Instance of ShortcutManager

getSourceData

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.

Note: This method may return incorrect values for cells that contain formulas. This is because getSourceData() operates on source data (physical indexes), whereas formulas operate on visual data (visual indexes).

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

getSourceDataArray

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.

Returns: Array - An array of arrays.

getSourceDataAtCell

core.getSourceDataAtCell(row, column) ⇒ *

Returns a single value from the data source.

Returns: * - Cell data.

getSourceDataAtCol

core.getSourceDataAtCol(column) ⇒ Array

Returns an array of column values from the data source.

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

getSourceDataAtRow

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.

Returns: Array | object - Single row of data.

getTranslatedPhrase

core.getTranslatedPhrase(dictionaryKey, extraArguments) ⇒ string

Get language phrase for specified dictionary key.

Since: 0.35.0

getValue

core.getValue() ⇒ *

Gets the value of the currently focused cell.

For column headers and row headers, returns null.

Returns: * - The value of the focused cell.

hasColHeaders

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

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

hasRowHeaders

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

core.isColumnModificationAllowed() ⇒ boolean

Checks if your data format and configuration options allow for changing the number of columns.

Returns false when your data is an array of objects, or when you use the columns option. Otherwise, returns true.

isEmptyCol

core.isEmptyCol(column) ⇒ boolean

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

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

isEmptyRow

core.isEmptyRow(row) ⇒ boolean

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

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

isExecutionSuspended

core.isExecutionSuspended() ⇒ boolean

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

Since: 8.3.0

isListening

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.

isLtr

core.isLtr() ⇒ boolean

Checks if the grid is rendered using the left-to-right layout direction.

Since: 12.0.0

Returns: boolean - True if LTR.

isRedoAvailable

core.isRedoAvailable() ⇒ boolean

UndoRedo#isRedoAvailable.

isRenderSuspended

core.isRenderSuspended() ⇒ boolean

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

Since: 8.3.0

isRtl

core.isRtl() ⇒ boolean

Checks if the grid is rendered using the right-to-left layout direction.

Since: 12.0.0

Returns: boolean - True if RTL.

isUndoAvailable

core.isUndoAvailable() ⇒ boolean

UndoRedo#isUndoAvailable.

listen

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

core.loadData(data, [source])

The loadData() method replaces Handsontable's data with a new dataset.

Additionally, the loadData() method:

• Resets cells' states (e.g. cells' formatting and cells' readOnly states)
• Resets rows' states (e.g. row order)
• Resets columns' states (e.g. column order)

To replace Handsontable's data without resetting states, use the updateData() method.

Read more:

• Binding to data
• Saving data

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

populateFromArray

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

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

The populateFromArray() method can't change readOnly cells.

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

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

propToCol

core.propToCol(prop) ⇒ number

Returns column index that corresponds with the given property.

Returns: number - Visual column index.

redo

core.redo()

UndoRedo#redo.

refreshDimensions

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

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

removeHook

core.removeHook(key, callback)

Removes the hook listener previously registered with Core#addHook.

See: Hooks#remove
Example

hot.removeHook('beforeInit', myCallback);

render

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

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

resumeRender

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.

Every suspendRender() call needs to correspond with one resumeRender() call. For example, if you call suspendRender() 5 times, you need to call resumeRender() 5 times as well.

Since: 8.3.0
Example

hot.suspendRender();
hot.alter('insert_row_above', 5, 45);
hot.alter('insert_col_start', 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

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

scrollToFocusedCell

core.scrollToFocusedCell([callback]) ⇒ boolean

Scrolls the viewport to coordinates specified by the currently focused cell.

Emits: Hooks#event:afterScroll
Since: 14.0.0

Returns: boolean - true if the viewport was scrolled, false otherwise.

scrollViewportTo

core.scrollViewportTo(options, [callback]) ⇒ boolean

Scroll viewport to coordinates specified by the row and/or col object properties.

// scroll the viewport to the visual row index (leave the horizontal scroll untouched)
hot.scrollViewportTo({ row: 50 });

// scroll the viewport to the passed coordinates so that the cell at 50, 50 will be snapped to
// the bottom-end table's edge.
hot.scrollViewportTo({
  row: 50,
  col: 50,
  verticalSnap: 'bottom',
  horizontalSnap: 'end',
}, () => {
  // callback function executed after the viewport is scrolled
});

Returns: boolean - true if viewport was scrolled, false otherwise.

selectAll

core.selectAll([includeRowHeaders], [includeColumnHeaders], [options])

Select all cells in the table excluding headers and corner elements.

The previous selection is overwritten.

// Select all cells in the table along with row headers, including all headers and the corner cell.
// Doesn't select column headers and corner elements.
hot.selectAll();

// Select all cells in the table, including row headers but excluding the corner cell and column headers.
hot.selectAll(true, false);

// Select all cells in the table, including all headers and the corner cell, but move the focus.
// highlight to position 2, 1
hot.selectAll(-2, -1, {
   focusPosition: { row: 2, col: 1 }
});

// Select all cells in the table, without headers and corner elements.
hot.selectAll(false);

Since: 0.38.2

selectCell

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

Select a single cell, or a single range of adjacent cells.

To select a cell, pass its visual row and column indexes, for example: selectCell(2, 4).

To select a range, pass the visual indexes of the first and last cell in the range, for example: selectCell(2, 4, 3, 5).

If your columns have properties, you can pass those properties' values instead of column indexes, for example: selectCell(2, 'first_name').

By default, selectCell() also:

• Scrolls the viewport to the newly-selected cells.
• Switches the keyboard focus to Handsontable (by calling Handsontable's listen() method).

Example

// select a single cell
hot.selectCell(2, 4);

// select a range of cells
hot.selectCell(2, 4, 3, 5);

// select a single cell, using a column property
hot.selectCell(2, 'first_name');

// select a range of cells, using column properties
hot.selectCell(2, 'first_name', 3, 'last_name');

// select a range of cells, without scrolling to them
hot.selectCell(2, 4, 3, 5, false);

// select a range of cells, without switching the keyboard focus to Handsontable
hot.selectCell(2, 4, 3, 5, null, false);

Returns: boolean - true: the selection was successful, false: the selection failed.

selectCells

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

Select multiple cells or ranges of cells, adjacent or non-adjacent.

You can pass one of the below:

• An array of arrays (which matches the output of Handsontable's getSelected() method).
• An array of CellRange objects (which matches the output of Handsontable's getSelectedRange() method).

To select multiple cells, pass the visual row and column indexes of each cell, for example: hot.selectCells([[1, 1], [5, 5]]).

To select multiple ranges, pass the visual indexes of the first and last cell in each range, for example: hot.selectCells([[1, 1, 2, 2], [6, 2, 0, 2]]).

If your columns have properties, you can pass those properties' values instead of column indexes, for example: hot.selectCells([[1, 'first_name'], [5, 'last_name']]).

By default, selectCell() also:

• Scrolls the viewport to the newly-selected cells.
• Switches the keyboard focus to Handsontable (by calling Handsontable's listen() method).

Since: 0.38.0
Example

// select non-adjacent cells
hot.selectCells([[1, 1], [5, 5], [10, 10]]);

// select non-adjacent ranges of cells
hot.selectCells([[1, 1, 2, 2], [10, 10, 20, 20]]);

// select cells and ranges of cells
hot.selectCells([[1, 1, 2, 2], [3, 3], [6, 2, 0, 2]]);

// select cells, using column properties
hot.selectCells([[1, 'id', 2, 'first_name'], [3, 'full_name'], [6, 'last_name', 0, 'first_name']]);

// select multiple ranges, using an array of `CellRange` objects
const selected = hot.getSelectedRange();

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

selected[1].from.row = 10;
selected[1].from.col = 10;
selected[1].to.row = 20;
selected[1].to.col = 20;

hot.selectCells(selected);

Returns: boolean - true: the selection was successful, false: the selection failed.

selectColumns

core.selectColumns(startColumn, [endColumn], [focusPosition]) ⇒ 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 visual indexes and mark the first header as highlighted.
hot.selectColumns(1, 2, -1);
// Select range of columns using visual indexes and mark the second cell as highlighted.
hot.selectColumns(2, 1, 1);
// Select range of columns using visual indexes and move the focus position somewhere in the middle of the range.
hot.selectColumns(2, 5, { row: 2, col: 3 });
// Select range of columns using column properties.
hot.selectColumns('id', 'last_name');

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

selectRows

core.selectRows(startRow, [endRow], [focusPosition]) ⇒ 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 a range of rows, using visual indexes.
hot.selectRows(1, 4);
// select a range of rows, using visual indexes, and mark the header as highlighted.
hot.selectRows(1, 2, -1);
// Select range of rows using visual indexes and mark the second cell as highlighted.
hot.selectRows(2, 1, 1);
// Select range of rows using visual indexes and move the focus position somewhere in the middle of the range.
hot.selectRows(2, 5, { row: 2, col: 3 });

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

setCellMeta

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

setCellMetaObject

core.setCellMetaObject(row, column, prop)

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

setDataAtCell

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.

setDataAtRowProp

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.

setSourceDataAtCell

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

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

spliceCellsMeta

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

spliceCol

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

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

Returns: Array - Returns removed portion of columns.

spliceRow

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

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

Returns: Array - Returns removed portion of rows.

suspendExecution

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

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.

Every suspendRender() call needs to correspond with one resumeRender() call. For example, if you call suspendRender() 5 times, you need to call resumeRender() 5 times as well.

Since: 8.3.0
Example

hot.suspendRender();
hot.alter('insert_row_above', 5, 45);
hot.alter('insert_col_start', 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

core.toHTML() ⇒ string

Converts instance into outerHTML of HTMLTableElement.

Since: 7.1.0

toPhysicalColumn

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.

Returns: number - Returns physical column index.

toPhysicalRow

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.

Returns: number - Returns physical row index.

toTableElement

core.toTableElement() ⇒ HTMLTableElement

Converts instance into HTMLTableElement.

Since: 7.1.0

toVisualColumn

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.

Returns: number - Returns visual column index.

toVisualRow

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.

Returns: number - Returns visual row index.

undo

core.undo()

UndoRedo#undo.

unlisten

core.unlisten()

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

updateData

core.updateData(data, [source])

The updateData() method replaces Handsontable's data with a new dataset.

The updateData() method:

• Keeps cells' states (e.g. cells' formatting and cells' readOnly states)
• Keeps rows' states (e.g. row order)
• Keeps columns' states (e.g. column order)

To replace Handsontable's data and reset states, use the loadData() method.

Read more:

• Binding to data
• Saving data

Emits: Hooks#event:beforeUpdateData, Hooks#event:afterUpdateData, Hooks#event:afterChange
Since: 11.1.0

updateSettings

core.updateSettings(settings, [init])

Use it if you need to change configuration after initialization. The settings argument is an object containing the changed 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.).

Since 12.0.0 passing data inside settings objects no longer results 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
});

useTheme

core.useTheme(themeName)

Use the theme specified by the provided name.

Since: 15.0.0

validateCell

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

Validate a single cell.

validateCells

core.validateCells([callback])

Validates every cell in the data set, using a validator function configured for each cell.

Doesn't validate cells that are currently trimmed, hidden, or filtered, as such cells are not included in the data set until you bring them back again.

After the validation, the callback function is fired, with the valid argument set to:

• true for valid cells
• false for invalid cells

Example

hot.validateCells((valid) => {
  if (valid) {
    // ... code for validated cells
  }
})

validateColumns

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

validateRows

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