After Handsontable is constructed, you can modify the grid behavior using the available public methods.
How to call methods.
These are 2 equal ways to call a Handsontable method:
// all following examples assume that you constructed Handsontable like this
const hot = new Handsontable(document.getElementById('example1'), options);
// now, to use setDataAtCell method, you can either:
hot.setDataAtCell(0, 0, 'new value');
Alternatively, you can call the method using jQuery wrapper (obsolete, requires initialization using our jQuery guide
$('#example1').handsontable('setDataAtCell', 0, 0, 'new value');
Parameters:
Name | Type | Default | Description |
---|---|---|---|
rootElement |
HTMLElement |
The element to which the Handsontable instance is injected. |
|
userSettings |
object |
The user defined options. |
|
rootInstanceSymbol |
boolean | false |
optional
Indicates if the instance is root of all later instances created. |
Members
-
columnIndexMapperIndexMapper
-
Instance of index mapper which is responsible for managing the column indexes.
-
isDestroyedboolean
-
A boolean to tell if the Handsontable has been fully destroyed. This is set to
true
afterafterDestroy
hook is called. -
rowIndexMapperIndexMapper
-
Instance of index mapper which is responsible for managing the row indexes.
Methods
-
addHook(key, callback)
-
Adds listener to the specified hook name (only for this Handsontable instance).
Parameters:
Name Type Description key
string Hook name (see
Hooks
).callback
function | Array Function or array of functions.
- See:
Example
hot.addHook('beforeInit', myCallback);
-
addHookOnce(key, callback)
-
Adds listener to specified hook name (only for this Handsontable instance). After the listener is triggered,
it will be automatically removed.Parameters:
Name Type Description key
string Hook name (see
Hooks
).callback
function | Array Function or array of functions.
- See:
Example
hot.addHookOnce('beforeInit', myCallback);
-
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.Parameters:
Name 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.
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]]);
-
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.Parameters:
Name Type Description wrappedOperations
function Batched operations wrapped in a function.
- Since: 8.3.0
Returns: {*} Returns result from the wrappedOperations callback.
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 });
-
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.Parameters:
Name 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.- Since: 8.3.0
Returns: {*} Returns result from the wrappedOperations callback.
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 });
-
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.Parameters:
Name Type Description wrappedOperations
function Batched operations wrapped in a function.
- Since: 8.3.0
Returns: {*} Returns result from the wrappedOperations callback.
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 });
-
clear()
-
Clears the data from the table (the table settings remain intact).
-
colToProp(column){string|number}
-
Returns the property name that corresponds with the given column index (see
DataMap#colToProp
).
If the data source is an array of arrays, it returns the columns index.Parameters:
Name Type Description column
number Visual column index.
Returns: {string|number} Column property or physical column index.
-
countCols(){number}
-
Returns the total number of visible columns in the table.
Returns: {number} Total number of columns.
-
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.Parameters:
Name 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(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.Parameters:
Name 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(){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(){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(){number}
-
Returns the total number of visual rows in the table.
Returns: {number} Total number of rows.
-
countSourceCols(){number}
-
Returns the total number of columns in the data source.
Returns: {number} Total number of columns.
-
countSourceRows(){number}
-
Returns the total number of rows in the data source.
Returns: {number} Total number of rows.
-
countVisibleCols(){number}
-
Returns the number of visible columns. Returns -1 if table is not visible.
Returns: {number} Number of visible columns or -1.
-
countVisibleRows(){number}
-
Returns the number of visible rows (rendered rows that fully fit inside viewport).
Returns: {number} Number of visible rows or -1.
-
deselectCell()
-
Deselects the current cell selection on the table.
-
destroy()
-
Removes the table from the DOM and destroys the instance of the Handsontable.
Fires:
-
destroyEditor(revertOriginal, prepareEditorIfNeeded)
-
Destroys the current editor, render the table and prepares the editor of the newly selected cell.
Parameters:
Name 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)
-
Erases content from cells that have been selected in the table.
Parameters:
Name 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.
- Since: 0.36.0
-
getActiveEditor(){BaseEditor}
-
Returns the active editor class instance.
Returns: {BaseEditor} The active editor instance.
-
getCell(row, column, topmost){HTMLTableCellElement|null}
-
Returns a TD element for the given
row
andcolumn
arguments, if it is rendered on screen.
Returnsnull
if the TD is not rendered on screen (probably because that part of the table is not visible).Parameters:
Name 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 thetop
overlay.Returns: {HTMLTableCellElement|null} The cell's TD element.
-
getCellEditor(row, column){function}
-
Returns the cell editor class by the provided
row
andcolumn
arguments.Parameters:
Name Type Description row
number Visual row index or cell meta object (see
Core#getCellMeta
).column
number Visual column index.
Returns: {function} The editor class.
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));
-
getCellMeta(row, column){object}
-
Returns the cell properties object for the given
row
andcolumn
coordinates.Parameters:
Name Type Description row
number Visual row index.
column
number Visual column index.
Fires:
Returns: {object} The cell properties object.
-
getCellMetaAtRow(row){Array}
-
Returns an array of cell meta objects for specified physical row index.
Parameters:
Name Type Description row
number Physical row index.
Returns: {Array}
-
getCellRenderer(row, column){function}
-
Returns the cell renderer function by given
row
andcolumn
arguments.Parameters:
Name 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.
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));
-
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(row, column){function|RegExp|undefined}
-
Returns the cell validator by
row
andcolumn
.Parameters:
Name 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.
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));
-
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.Parameters:
Name Type Description column
number optional Visual column index.
Fires:
Returns: {Array|string|number} The column header(s).
-
getColWidth(column){number}
-
Returns the width of the requested column.
Parameters:
Name Type Description column
number Visual column index.
Fires:
Returns: {number} Column width.
-
getCoords(element){CellCoords|null}
-
Returns the coordinates of the cell, provided as a HTML table cell element.
Parameters:
Name Type Description element
HTMLTableCellElement The HTML Element representing the cell.
Returns: {CellCoords|null} Visual coordinates object.
Example
hot.getCoords(hot.getCell(1, 1)); // it returns CellCoords object instance with props row: 1 and col: 1.
-
getCopyableData(row, column){string}
-
Returns the data's copyable value at specified
row
andcolumn
index (seeDataMap#getCopyable
).Parameters:
Name Type Description row
number Visual row index.
column
number Visual column index.
Returns: {string}
-
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 (seeDataMap#getCopyableText
).Parameters:
Name 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.
Returns: {string}
-
getData(row, column, row2, column2){Array.<Array>}
-
Returns the current data object (the same one that was passed by
data
configuration option orloadData
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 theCore#getSourceData
method.).Optionally you can provide cell range by defining
row
,column
,row2
,column2
to get only a fragment of table data.Parameters:
Name 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.
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);
-
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.
Parameters:
Name Type Description row
number Visual row index.
column
number Visual column index.
Returns: {*} Data at cell.
-
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.
Parameters:
Name Type Description column
number Visual column index.
Returns: {Array} Array of cell values.
-
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.Parameters:
Name Type Description prop
string | number Property name or physical column index.
Returns: {Array} Array of cell values.
-
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.
Parameters:
Name Type Description row
number Visual row index.
Returns: {Array} Array of row's cell data.
-
getDataAtRowProp(row, prop){*}
-
Returns value at visual
row
andprop
indexes (seeDataMap#get
).Note: If data is reordered, sorted or trimmed, the currently visible order will be used.
Parameters:
Name Type Description row
number Visual row index.
prop
string Property name.
Returns: {*} Cell value.
-
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.
Parameters:
Name 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(){Handsontable}
-
Returns the Handsontable instance.
Returns: {Handsontable} The Handsontable instance.
-
getPlugin(pluginName){BasePlugin|undefined}
-
Returns plugin instance by provided its name.
Parameters:
Name Type Description pluginName
string The plugin name.
Returns: {BasePlugin|undefined} The plugin instance or undefined if there is no plugin.
-
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.Parameters:
Name Type Description row
number optional Visual row index.
Fires:
Returns: {Array|string|number} Array of header values / single header value.
-
getRowHeight(row){number}
-
Returns the row height.
Parameters:
Name Type Description row
number Visual row index.
Fires:
Returns: {number} The given row's height.
-
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(){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 usegetSelectedLast
method.Returns: {Array.<Array>|undefined} An array of arrays of the selection's coordinates.
-
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(){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 usegetSelectedRangeLast
method.Returns: {Array.<CellRange>|undefined} Selected range object or undefined if there is no selection.
-
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(){object}
-
Returns the object settings.
Returns: {object} Object containing the current table settings.
-
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 therow
,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.Parameters:
Name 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(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 therow
,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.Parameters:
Name 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(row, column){*}
-
Returns a single value from the data source.
Parameters:
Name Type Description row
number Physical row index.
column
number Visual column index.
Returns: {*} Cell data.
-
getSourceDataAtCol(column){Array}
-
Returns an array of column values from the data source.
Parameters:
Name Type Description column
number Visual column index.
Returns: {Array} Array of the column's cell values.
-
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.Parameters:
Name Type Description row
number Physical row index.
Returns: {Array|object} Single row of data.
-
getTranslatedPhrase(dictionaryKey, extraArguments){string}
-
Get language phrase for specified dictionary key.
Parameters:
Name Type Description dictionaryKey
string Constant which is dictionary key.
extraArguments
* Arguments which will be handled by formatters.
- Since: 0.35.0
Returns: {string}
-
getValue(){*}
-
Get value from the selected cell.
Returns: {*} Value of selected cell.
-
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(key){boolean}
-
Check if for a specified hook name there are added listeners (only for this Handsontable instance). All available
hooks you will findHooks
.Parameters:
Name Type Description key
string Hook name.
- See:
Returns: {boolean}
Example
const hasBeforeInitListeners = hot.hasHook('beforeInit');
-
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(){boolean}
-
Checks if the data format and config allows user to modify the column structure.
Returns: {boolean}
-
isEmptyCol(column){boolean}
-
Check if all cells in the the column declared by the
column
argument are empty.Parameters:
Name Type Description column
number Column index.
Returns: {boolean}
true
if the column at the givencol
is empty,false
otherwise. -
isEmptyRow(row){boolean}
-
Check if all cells in the row declared by the
row
argument are empty.Parameters:
Name Type Description row
number Visual row index.
Returns: {boolean}
true
if the row at the givenrow
is empty,false
otherwise. -
isExecutionSuspended(){boolean}
-
Checks if the table indexes recalculation process was suspended. See explanation
inCore#suspendExecution
.- Since: 8.3.0
Returns: {boolean}
-
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. -
isRenderSuspended(){boolean}
-
Checks if the table rendering process was suspended. See explanation in
Core#suspendRender
.- Since: 8.3.0
Returns: {boolean}
-
listen()
-
Listen to the keyboard input on document body. This allows Handsontable to capture keyboard events and respond
in the right way.Fires:
-
loadData(data)
-
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.).Parameters:
Name Type Description data
Array Array of arrays or array of objects containing data.
Fires:
-
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]]
). UseendRow
,endCol
when you
want to cut input when a certain row is reached.Optional
method
argument has the same effect as pasteMode option (seeOptions#pasteMode
).Parameters:
Name 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 isnumeric
.Returns: {object|undefined} Ending td in pasted area (only if any cell was changed).
-
propToCol(prop){number}
-
Returns column index that corresponds with the given property (see
DataMap#propToCol
).Parameters:
Name Type Description prop
string | number Property name or physical column index.
Returns: {number} Visual column index.
-
refreshDimensions()
-
Updates dimensions of the table. The method compares previous dimensions with the current ones and updates accordingly.
Fires:
-
removeCellMeta(row, column, key)
-
Remove a property defined by the
key
argument from the cell meta object for the providedrow
andcolumn
coordinates.Parameters:
Name Type Description row
number Visual row index.
column
number Visual column index.
key
string Property name.
Fires:
-
removeHook(key, callback)
-
Removes the hook listener previously registered with
Core#addHook
.Parameters:
Name Type Description key
string Hook name.
callback
function Reference to the function which has been registered using
Core#addHook
.- See:
Example
hot.removeHook('beforeInit', myCallback);
-
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(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.Parameters:
Name 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.- 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()
-
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(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.Parameters:
Name 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.
- See:
Returns: {*}
Example
// Run built-in hook hot.runHooks('beforeInit'); // Run custom hook hot.runHooks('customAction', 10, 'foo');
-
scrollViewportTo(row, column, snapToBottom, snapToRight, considerHiddenIndexes){boolean}
-
Scroll viewport to coordinates specified by the
row
andcolumn
arguments.Parameters:
Name 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(includeHeaders)
-
Select the whole table. The previous selection will be overwritten.
Parameters:
Name Type Default Description includeHeaders
boolean true optional true
If the selection should include the row, column and corner headers,
false
otherwise.- Since: 0.38.2
-
selectCell(row, column, endRow, endColumn, scrollToCell, changeListener){boolean}
-
Select cell specified by
row
andcolumn
values or a range of cells finishing atendRow
,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.Parameters:
Name 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.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);
-
selectCells(coords, scrollToCell, changeListener){boolean}
-
Make multiple, non-contiguous selection specified by
row
andcolumn
values or a range of cells
finishing atendRow
,endColumn
. The method supports two input formats which are the same as that
produces bygetSelected
andgetSelectedRange
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.Parameters:
Name Type Default Description coords
Array.<Array> | Array.<CellRange> Visual coords passed as an array of array (
[[rowStart, columnStart, rowEnd, columnEnd], ...]
)
the same format asgetSelected
method returns or as an CellRange objects
which is the same format whatgetSelectedRange
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.- Since: 0.38.0
Returns: {boolean}
true
if selection was successful,false
otherwise.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);
-
selectColumns(startColumn, endColumn){boolean}
-
Select column specified by
startColumn
visual index, column property or a range of columns finishing atendColumn
.Parameters:
Name 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 bystartColumn
will be selected.- Since: 0.38.0
Returns: {boolean}
true
if selection was successful,false
otherwise.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');
-
selectRows(startRow, endRow){boolean}
-
Select row specified by
startRow
visual index or a range of rows finishing atendRow
.Parameters:
Name 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 bystartRow
will be selected.- Since: 0.38.0
Returns: {boolean}
true
if selection was successful,false
otherwise.Example
// Select row using visual index. hot.selectRows(1); // Select range of rows using visual indexes. hot.selectRows(1, 4);
-
setCellMeta(row, column, key, value)
-
Sets a property defined by the
key
property to the meta object of a cell corresponding to paramsrow
andcolumn
.Parameters:
Name Type Description row
number Visual row index.
column
number Visual column index.
key
string Property name.
value
string Property value.
Fires:
-
setCellMetaObject(row, column, prop)
-
Set cell meta data object defined by
prop
to the corresponding paramsrow
andcolumn
.Parameters:
Name Type Description row
number Visual row index.
column
number Visual column index.
prop
object Meta object.
-
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.Parameters:
Name 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(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.Parameters:
Name 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(row, column, value, source)
-
Set the provided value in the source data set at the provided coordinates.
Parameters:
Name 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(visualIndex, deleteAmount, cellMetaRows)
-
Removes or adds one or more rows of the cell meta objects to the cell meta collections.
Parameters:
Name 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 repeatable The new cell meta row objects to be added to the cell meta collection.
- Since: 0.30.0
-
spliceCol(column, index, amount, elements){Array}
-
Adds/removes data from the column. This method works the same as Array.splice for arrays (see
DataMap#spliceCol
).Parameters:
Name 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 repeatable 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(row, index, amount, elements){Array}
-
Adds/removes data from the row. This method works the same as Array.splice for arrays (see
DataMap#spliceRow
).Parameters:
Name 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 repeatable 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()
-
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()
-
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 theCore#batchRender
method orCore#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(){string}
-
Converts instance into outerHTML of HTMLTableElement.
- Since: 7.1.0
Returns: {string}
-
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.Parameters:
Name Type Description column
number Visual column index.
Returns: {number} Returns physical column index.
-
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.Parameters:
Name Type Description row
number Visual row index.
Returns: {number} Returns physical row index.
-
toTableElement(){HTMLTableElement}
-
Converts instance into HTMLTableElement.
- Since: 7.1.0
Returns: {HTMLTableElement}
-
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.Parameters:
Name Type Description column
number Physical column index.
Returns: {number} Returns visual column index.
-
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.Parameters:
Name Type Description row
number Physical row index.
Returns: {number} Returns visual row index.
-
unlisten()
-
Stop listening to keyboard input on the document body. Calling this method makes the Handsontable inactive for
any keyboard events. -
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
ordata
insidesettings
objects will result in resetting states corresponding to rows and columns
(for example, row/column sequence, column width, row height, frozen columns etc.).Parameters:
Name Type Default Description settings
object New settings object (see
Options
).init
boolean false optional Internally used for in initialization mode.
Fires:
Example
hot.updateSettings({ contextMenu: true, colHeaders: true, fixedRowsTop: 2 });
-
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 asfalse
- otherwise it
would equaltrue
.Parameters:
Name Type Description callback
function optional The callback function.
Example
hot.validateCells((valid) => { if (valid) { // ... code for validated cells } })
-
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 asfalse
- otherwise it
would equaltrue
.Parameters:
Name Type Description columns
Array optional Array of validation target visual columns indexes.
callback
function optional The callback function.
Example
hot.validateColumns([3, 4, 5], (valid) => { if (valid) { // ... code for validated columns } })
-
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 asfalse
- otherwise it
would equaltrue
.Parameters:
Name Type Description rows
Array optional Array of validation target visual row indexes.
callback
function optional The callback function.
Example
hot.validateRows([3, 4, 5], (valid) => { if (valid) { // ... code for validated rows } })