Skip to content

Core

Description

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

How to call a method

Options

activeHeaderClassName

Can be set at: grid

Source code

core.activeHeaderClassName : string

The activeHeaderClassName option lets you add a CSS class name to every currently-active, currently-selected header (when a whole column or row is selected).

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Read more:

Default: “ht__active_highlight”
Since: 0.38.2
Example

// add an `ht__active_highlight` CSS class name
// to every currently-active, currently-selected header
activeHeaderClassName: 'ht__active_highlight',

allowEmpty

Can be set at: grid columns cells cell

Source code

core.allowEmpty : boolean

The allowEmpty option determines whether Handsontable accepts the following values:

  • null
  • undefined
  • ''

You can set the allowEmpty option to one of the following:

SettingDescription
true (default)- Accept null, undefined and '' values
- Mark cells that contain null, undefined or '' values as valid
false- Don’t accept null, undefined and '' values
- Mark cells that contain null, undefined or '' values with as invalid

This option can be set at any level of the cascading configuration: the grid level, the columns level, the cells level, and the cell level.

Default: true
Example

// allow empty values in each cell of the entire grid
allowEmpty: true,
// or
columns: [
{
type: 'date',
dateFormat: { day: '2-digit', month: '2-digit', year: 'numeric' },
// allow empty values in each cell of the 'date' column
allowEmpty: true
}
],
// or, using the `cells` option
cells(row, col) {
if (col === 2) {
return { allowEmpty: false };
}
},

allowHtml

Can be set at: grid columns cells cell

Source code

core.allowHtml : boolean

The allowHtml option configures whether autocomplete and dropdown cells’ source data is treated as HTML.

You can set the allowHtml option to one of the following:

SettingDescription
false (default)The source data is not treated as HTML
trueThe source data is treated as HTML

Warning: Setting the allowHtml option to true can cause serious XSS vulnerabilities. The sanitizer option does not apply to this content: allowHtml exists to render the markup you supply, so sanitize the source items yourself before passing them in.

Read more:

Default: false
Example

columns: [
{
// set the `type` of each cell in this column to `autocomplete`
type: 'autocomplete',
// set options available in every `autocomplete` cell of this column
source: ['<strong>foo</strong>', '<strong>bar</strong>']
// use HTML in the `source` list
allowHtml: true,
},
],

allowInsertColumn

Can be set at: grid

Source code

core.allowInsertColumn : boolean

The allowInsertColumn option controls two things: the insert items in the menus, and whether the grid may add columns on its own.

If set to true, the option adds the following menu items to the context menu and to the column menu:

  • Insert column left
  • Insert column right

If set to false, the option also stops the grid from adding columns on its own:

  • A paste that is wider than the columns left to the right of the selection stops at the last column. Handsontable drops the extra values, and reports no error. In the shift_right pasteMode the values pushed past the last column are lost, because no column is created to receive them.
  • An autofill that reaches past the last column stops at the last column. longer create the missing columns when you write past the last column. The write still reaches the source data, so getSourceData() returns the value while the grid never displays it. This bullet applies only when your data is an array of arrays and you do not set the columns option – in any other configuration these methods never add columns anyway, whatever this option is set to.

This option does not decide whether the value reaches the source data – the write path does. A paste or an autofill stops at the last column, so nothing is written there at all. A direct setDataAtCell() or setDataAtRowProp() call writes the value whatever this option is set to. On an object data source that direct write is deprecated as of 19.0.0 and will be ignored from 20.0.0 on. See setDataAtCell(), which owns that rule; setDataAtRowProp() is not affected, because the property you pass names the field to write.

The option does not stop these ways of adding columns:

  • The minCols and minSpareCols options. Both are themselves skipped when the columns option is set, and minSpareCols also requires data to be an array of arrays.
  • Undo and redo.
  • Pressing Enter at the last column, when minSpareCols is above 0 and enterMoves is set to move the column. The default enterMoves moves the row only, so this does not happen out of the box.

To cap the number of columns whatever the source, use maxCols as well.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: true
Example

// hide the 'Insert column left' and 'Insert column right' menu items,
// and stop the grid from adding columns during paste, autofill, and `setDataAtCell()`
allowInsertColumn: false,

allowInsertRow

Can be set at: grid

Source code

core.allowInsertRow : boolean

The allowInsertRow option controls two things: the insert items in the context menu, and whether the grid may add rows on its own.

If set to true, the option adds the following menu items to the context menu:

  • Insert row above
  • Insert row below

If set to false, the option also stops the grid from adding rows on its own:

  • A paste that is taller than the rows left below the selection stops at the last row. Handsontable drops the extra values, and reports no error. In the shift_down pasteMode the rows pushed past the last row are lost, because no row is created to receive them.
  • An autofill whose fill reaches past the last row stops at the last row, unless the fillHandle option’s autoInsertRow setting has already appended rows to take it – see the next list. not create the missing rows when you write below the last row. Both currently throw a TypeError in that case, so guard the call, or keep the row index within countRows().

The option does not stop these ways of adding rows:

  • The minRows and minSpareRows options.
  • Undo and redo.
  • The fill handle appending rows when you drag it below the last row. That is governed solely by the fillHandle option’s autoInsertRow setting, which ignores allowInsertRow. It applies only when you set fillHandle explicitly – left unset, the grid does not append rows this way.
  • Pressing Enter at the last row, when minSpareRows is above 0. Only Enter does this – the arrow keys and Tab never create a row.

To cap the number of rows whatever the source, use maxRows as well.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: true
Example

// hide the 'Insert row above' and 'Insert row below' menu items from the context menu,
// and stop the grid from adding rows during paste, autofill, and `setDataAtCell()`
allowInsertRow: false,

allowInvalid

Can be set at: grid columns cells cell

Source code

core.allowInvalid : boolean

The allowInvalid option determines whether Handsontable accepts values that were marked as invalid by the cell validator.

You can set the allowInvalid option to one of the following:

SettingDescription
true (default)- Accept invalid values
- Allow the user to close the cell editor with invalid values
- Save invalid values into the data source
false- Don’t accept invalid values
- Don’t allow the user to close the cell editor with invalid values
- Don’t save invalid values into the data source

Setting the allowInvalid option to false can be useful when used with the Autocomplete strict mode.

Read more:

Default: true
Example

// don't accept `invalid` values
// don't allow the user to close the cell editor
// don't save `invalid` values into the data source
allowInvalid: false,

allowRemoveColumn

Can be set at: grid

Source code

core.allowRemoveColumn : boolean

If set to true, the allowRemoveColumn option adds the following menu item to the context menu and to the column menu:

  • Remove column

The option hides that menu item only. It does not stop the alter() method’s remove_col action, and it does not stop undo or redo. To block a removal, return false from the beforeRemoveCol hook – that is the only lever that stops one. minCols does not: it appends an empty column afterwards to restore the count, and the removed data is already gone.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Read more:

Default: true
Example

// hide the 'Remove column' menu item from the context menu and the column menu
allowRemoveColumn: false,

allowRemoveRow

Can be set at: grid

Source code

core.allowRemoveRow : boolean

If set to true, the allowRemoveRow option adds the following menu item to the context menu:

  • Remove row

The option hides that menu item only. It does not stop the alter() method’s remove_row action, and it does not stop undo or redo. To block a removal, return false from the beforeRemoveRow hook – that is the only lever that stops one. minRows does not: it appends an empty row afterwards to restore the count, and the removed data is already gone.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: true
Example

// hide the 'Remove row' menu item from the context menu
allowRemoveRow: false,

applyCellsToDataReads

Can be set at: grid columns

Source code

core.applyCellsToDataReads : boolean

The applyCellsToDataReads option makes data reads call the cells function for every cell they read, so a valueGetter or a key/value cell type that cells sets applies to every row, rendered or not.

By default, a data read applies such a valueGetter only to the cells the grid has rendered. The grid keeps the cell meta of the rows around the viewport and drops it when they scroll away, so without this option, getData() and the other getDataAt*() methods, copying, and column sorting return the raw value for the other rows.

With this option on, those reads call cells once for every cell they return. A read runs no beforeGetCellMeta or afterGetCellMeta hook and stores no cell meta. The cost grows with what cells does: a cells function that reads grid data (for example, this.instance.getDataAtRow(row)) pays that read for every cell, so a full getData() of a large grid can take seconds. Turn the option on only for the columns whose cells function sets a valueGetter or a cell type.

Read more:

Default: false
Since: 19.0.0
Example

columns: [
{
// apply the `valueGetter` that `cells` sets to every row a data read returns
applyCellsToDataReads: true,
},
{},
],
cells(row, column) {
return column === 0 ? { valueGetter: value => String(value).toUpperCase() } : {};
},

ariaTags

Can be set at: grid columns cells cell

Source code

core.ariaTags : boolean

The ariaTags option decides whether Handsontable adds the ARIA roles and attributes that describe the grid to assistive technologies: role="treegrid" on the grid, role="row" on each row, role="gridcell" on each cell, the header roles, aria-sort, aria-expanded, and the rest. It defaults to true. Set it to false only when you add your own ARIA markup. The option also removes the tabindex the grid puts on cells, headers, and menu items, so browser focus no longer moves onto them. The menu styles read aria-expanded too, so a menu item keeps its focus outline while its submenu is open.

You can set the ariaTags option only at Handsontable’s initialization. Any change of it after the initialization (e.g. using the updateSettings() method) throws an error, even when you didn’t set the option at initialization.

Read more:

Default: true
Since: 14.0.0
Example

// turn the ARIA roles and attributes off (default: true)
ariaTags: false,

autoWrapCol

Can be set at: grid

Source code

core.autoWrapCol : boolean

SettingDescription
false (default)When you select a bottom-most cell, pressing ↓ doesn’t do anything.

When you select a top-most cell, pressing ↑ doesn’t do anything.
trueWhen you select a bottom-most cell, pressing ↓ takes you to the top-most cell of the next column.

When you select a top-most cell, pressing ↑ takes you to the bottom-most cell of the previous column.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: false
Example

// when you select a bottom-most cell, pressing ⬇ doesn't do anything
// when you select a top-most cell, pressing ⬆ doesn't do anything
autoWrapCol: false, // default setting
// when you select a bottom-most cell, pressing ⬇ takes you to the top-most cell of the next column
// when you select a top-most cell, pressing ⬆ takes you to the bottom-most cell of the previous column
autoWrapCol: true,

autoWrapRow

Can be set at: grid

Source code

core.autoWrapRow : boolean

SettingDescription
false (default)When you select the first cell of a row, pressing ←* (or Shift+Tab**) doesn’t do anything.

When you select the last cell of a row, pressing →* (or Tab**) doesn’t do anything.
trueWhen you select the first cell of a row, pressing ←* (or Shift+Tab**) takes you to the last cell of the row above.

When you select the last cell of a row, pressing →* (or Tab**) takes you to the first cell of the row below.

* The exact key depends on your layoutDirection configuration.
** Unless tabNavigation is set to false.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: false
Example

// when you select the first cell of a row, pressing ⬅ (or Shift+Tab) doesn't do anything
// when you select the last cell of a row, pressing ➡ (or Tab) doesn't do anything
autoWrapRow: false, // default setting
// when you select the first cell of a row, pressing ⬅ (or Shift+Tab) takes you to the last cell of the row above
// when you select the last cell of a row, pressing ➡ (or Tab) takes you to the first cell of the row below
autoWrapRow: true,

cell

Can be set at: grid

Source code

core.cell : Array<Array>

The cell option lets you apply configuration options to individual cells.

The cell option overwrites the top-level grid options, and the columns options.

Each entry’s row and col are visual indexes. This differs from the cells option, whose row and column are physical indexes.

The cell option persists across updateSettings() calls that do not mention it. Passing cell again replaces every previously declared entry, so cell: [] removes them all. An entry follows its row through sorting and row moves, and a later setCellMeta() call on the same property wins over the declared value - until the next call restates cell, which wins over everything.

A value that is not an array is ignored, and reported in the console. It does not reach getSettings() either, so the previously declared entries stay in place. Wrap a single entry in an array.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: []
Example

// set the `cell` option to an array of objects
cell: [
// make the cell with coordinates (0, 0) read-only
{
row: 0,
col: 0,
readOnly: true
}
],

cells

Can be set at: grid

Source code

core.cells : function

The cells option lets you apply any other configuration options to individual grid elements (columns, rows, cells), based on any logic you implement.

The cells option overwrites all other options (including options set by columns and cell).

Handsontable merges the object that cells returns into the cell’s meta. It doesn’t replace the meta. A key that the function returned before and doesn’t return now keeps its last value. For example, a cell stays readOnly: true after cells returns {}. To avoid this, return the value for every key on every call (for example, readOnly: false). Or, outside the cells function, call removeCellMeta() with the cell’s visual coordinates to remove the key. The key comes back if cells returns it again. The meta resets in three cases: In React, that happens when you pass cells as a new function. updateSettings({ data }) don’t reset it.

  • A row that scrolls more than one viewport out of view and back, unless it is the row of the selected cell. Cells with meta you set with setCellMeta() or the cell option, and cells marked invalid, keep their meta. Horizontal scrolling doesn’t reset it.

cells takes the following parameters:

ParameterRequiredTypeDescription
rowYesNumberA physical row index
columnYesNumberA physical column index
propNoString | NumberIf data is set to an array of arrays, prop is the same number as column.

If data is set to an array of objects, prop is a property name for the column’s data object.

Inside a regular (non-arrow) cells function, this is the cell meta object. Its this.instance property is the Handsontable instance, so you can call core API methods such as this.instance.toVisualRow(row) or this.instance.toVisualColumn(column) (as in the example below). Arrow functions (cells: () => {}) do not bind this, so this.instance is not available inside them – use a regular or shorthand function instead.

Read more:

Default: undefined
Example

// set the `cells` option to your custom function
cells(row, column, prop) {
const cellProperties = { readOnly: false };
const visualRowIndex = this.instance.toVisualRow(row);
const visualColIndex = this.instance.toVisualColumn(column);
if (visualRowIndex === 0 && visualColIndex === 0) {
cellProperties.readOnly = true;
} else {
cellProperties.readOnly = false;
}
return cellProperties;
},

checkedTemplate

Can be set at: grid columns cells cell

Source code

core.checkedTemplate : boolean | string | number

The checkedTemplate option lets you configure what value a checked checkbox cell has.

You can set the checkedTemplate option to one of the following:

SettingDescription
true (default)If a checkbox cell is checked,
the getDataAtCell method for this cell returns true
A stringIf a checkbox cell is checked,
the getDataAtCell method for this cell returns a string of your choice

This option can be set at any level of the cascading configuration: the grid level, the columns level, the cells level, and the cell level.

Read more:

Default: true
Example

columns: [
{
// set the `type` of each cell in this column to `checkbox`
// when checked, the cell's value is `true`
// when unchecked, the cell's value is `false`
type: 'checkbox',
},
{
// set the `type` of each cell in this column to `checkbox`
type: 'checkbox',
// when checked, the cell's value is `'Yes'`
checkedTemplate: 'Yes',
// when unchecked, the cell's value is `'No'`
uncheckedTemplate: 'No'
}
],

className

Can be set at: grid columns cells cell

Source code

core.className : string | Array<string>

The className option lets you add CSS class names to every cell that has this option set.

You can set the className option to one of the following:

SettingDescription
A stringAdd a single CSS class name to every matching cell
An array of stringsAdd multiple CSS class names to every matching cell

Where Handsontable adds the class names

The target depends on the level at which you set the option:

LevelContainer elementCells
GridYesEvery cell
columnsNoCells of that column
cells or cellNoThe matching cells

At the grid level, Handsontable adds the class names to two places. It adds them to the container element – the element that holds the grid – and, through cascading configuration, to every cell. To add class names to the <table> element instead, use tableClassName.

To style the container element alone, set className at the grid level and clear it at the cell level:

const hot = new Handsontable(container, {
className: 'your-class-name',
// the container element keeps `your-class-name`, the cells don't receive it
cells() {
return { className: '' };
},
});

A className set at a lower level replaces the value from a higher level. It doesn’t merge with it. To keep a class name from a higher level, repeat it at the lower level.

Custom renderers

Handsontable adds these class names to a cell even when the cell uses a custom renderer that calls no built-in renderer. Handsontable runs baseRenderer after your renderer whenever your renderer didn’t run it. Before version 17.0.0, such a cell received no class names.

To apply different CSS class names on different levels, use Handsontable’s cascading configuration.

Read more:

Default: undefined
Example

// add a `your-class-name` CSS class name to every cell
className: 'your-class-name',
// add `first-class-name` and `second-class-name` CSS class names to every cell
className: ['first-class-name', 'second-class-name'],

colHeaders

Can be set at: grid

Source code

core.colHeaders : boolean | Array<string> | function

The colHeaders option configures your grid’s column headers.

You can set the colHeaders option to one of the following:

SettingDescription
trueEnable the default column headers (‘A’, ‘B’, ‘C’, …)
falseDisable column headers
An arrayDefine your own column headers (e.g. ['One', 'Two', 'Three', ...])
A functionDefine your own column headers, using a function

To set the header label of an individual column, use that column’s title option.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: null
Example

// enable the default column headers
colHeaders: true,
// set your own column headers
colHeaders: ['One', 'Two', 'Three'],
// set your own column headers, using a function
colHeaders: function(physicalColumnIndex) {
return `${physicalColumnIndex} + : AB`;
},

colorScheme

Can be set at: grid

Source code

core.colorScheme : string | undefined

The colorScheme option sets the color scheme of the grid without declaring a theme.

You can set it to one of the following:

SettingDescription
undefined (default)Use the color scheme of the current theme
'light'Always render the light color scheme
'dark'Always render the dark color scheme
'auto'Follow the color scheme of the operating system

The option is a per-instance override. It applies on top of the current theme, so the theme itself stays unchanged and other grids that use the same theme keep their own color scheme. You can change it at runtime with updateSettings().

The option requires the theme engine, so it has no effect when the theme comes from a CSS class name (the theme option set to a string, or an ht-theme-* class on the container element). In that case, use the theme’s dark class name instead.

An unsupported value is ignored with a console warning rather than throwing.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Since: 18.1.0
Example

// Render the grid in dark mode, without declaring a theme
const hot = new Handsontable(container, {
colorScheme: 'dark',
});

Example

// Switch the color scheme at runtime
hot.updateSettings({
colorScheme: 'auto',
});

columnHeaderHeight

Can be set at: grid

Source code

core.columnHeaderHeight : number | Array<number> | string | Array<string> | Array<(number|string)>

The columnHeaderHeight option configures the height of column headers.

You can set the columnHeaderHeight option to one of the following:

SettingDescription
A numberSet the same height for every column header
A stringSet the same height, written as a pixel size ('25', '25px')
An arraySet different heights for individual column headers

The height is a number of pixels. A string that states a pixel size works too, either as a bare number ('25') or with the unit ('25px'), so a value coming from an attribute or a JSON config still applies. Both forms may be mixed inside the array. A value that is not a pixel size, such as '50%' or '20em', is ignored and the default height is used instead.

A negative number is kept as it is, because numbers keep the behavior they had before this option read strings at all. A negative string is rejected instead, so a typo cannot collapse the header.

The height is the header’s border-box height, so it includes the header’s own top and bottom borders. A column header carries a 1px border on each side, which makes columnHeaderHeight: 40 leave a 38px content box for the label. Before Handsontable 19.0 the bottom border was dropped while the grid sat at the top of its scroll range and added back as soon as it scrolled, so the same setting produced a 39px content box unscrolled and 38px scrolled. The header keeps that border at every scroll position now, so the option resolves to the same height wherever the grid is scrolled to.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Example

// set the same height for every column header
columnHeaderHeight: 25,
// set the same height, written as a pixel size
columnHeaderHeight: '25px',
// set different heights for individual column headers
columnHeaderHeight: [25, 30, 55],

columns

Can be set at: grid

Source code

core.columns : Array<object> | function

The columns option lets you apply any other configuration options to individual columns (or ranges of columns).

You can set the columns option to one of the following:

  • An array of objects (each object represents one column)
  • A function that returns an array of objects

The columns option overwrites the top-level grid options.

When you use columns, the startCols, minCols, and maxCols options are ignored.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Example

// set the `columns` option to an array of objects
// each object represents one column
columns: [
{
// column options for the first (by physical index) column
type: 'numeric',
numericFormat: {
style: 'currency',
currency: 'USD',
minimumFractionDigits: 2,
maximumFractionDigits: 2
}
},
{
// column options for the second (by physical index) column
type: 'text',
readOnly: true
}
],
// or set the `columns` option to a function, based on physical indexes
columns(index) {
return {
type: index > 0 ? 'numeric' : 'text',
readOnly: index < 1
}
}

colWidths

Can be set at: grid

Source code

core.colWidths : number | Array<number> | string | Array<string> | Array<undefined> | function

The colWidths option sets columns’ widths, in pixels.

The default column width is 50px. To change it, set the colWidths option to one of the following:

SettingDescriptionExample
A numberSet the same width for every columncolWidths: 100
A stringSet the same width for every columncolWidths: '100px'
An arraySet widths separately for each column,
by physical column index
colWidths: [100, 120, undefined]
A functionSet column widths dynamically,
on each render, by physical column index
colWidths(physicalColumnIndex) { return physicalColumnIndex * 10; }
undefinedUsed by the modifyColWidth hook,
to detect column width changes.
colWidths: undefined
nullSame as undefined: no width is set,
so the AutoColumnSize plugin sizes the columns
colWidths: null

A null entry in the array and a null returned by the function also set no width: the modifyColWidth hook receives undefined for that column. The AutoColumnSize plugin stays off there, because any other colWidths value turns it off, so such a column gets the default 50px width. A column width: null behaves like undefined and falls back to colWidths.

The array and the function address a column by its physical index, so a width stays with its column when the user moves the column. The physical index doesn’t change when columns are moved or hidden. When you insert or remove a column with alter(), each width of an array colWidths stays with its column. A column added after the last one takes the next width in the array. A column inserted between others has no width of its own, and neither has a column inserted after a column the user moved to the end. The array itself is never changed: getSettings() returns the array you passed. A function is called with the physical index the column has now. Switching colWidths to or from an array, or passing a new array to updateSettings(), clears the undo history, the way enabling a plugin does. The rowHeights option addresses rows by their physical index in the same way.

Setting colWidths even for a single column disables the AutoColumnSize plugin for all columns. For this reason, if you use colWidths, we recommend you set a width for each one of your columns. Otherwise, every column with an undefined width defaults back to 50px, which may cut longer columns names.

A column resized by dragging keeps its width until the width is re-declared. Passing colWidths to updateSettings() re-declares the widths and discards the ones stored by the ManualColumnResize plugin. To keep the stored widths, leave colWidths out of the call.

Passing manualColumnResize as an array in the same call replaces the stored widths with that array rather than keeping them.

These cases never discard the stored widths:

  • A colWidths function. It states no fixed width, so it is left alone.
  • A grid whose manualColumnResize option is already a non-empty array. The plugin replays that array, so the stored widths stay.
  • The React, Angular and Vue wrappers, when the colWidths prop did not change. An unchanged prop is not forwarded, so re-applying the same value resets nothing.

In each case, call ManualColumnResize#clearManualSizes() followed by render().

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Example

// set every column's width to 100px
colWidths: 100,
// set every column's width to 100px
colWidths: '100px',
// set the first (by physical index) column's width to 100
// set the second (by physical index) column's width to 120
// set the third (by physical index) column's width to `undefined`, so that it defaults to 50px
// set any other column's width to the default 50px (note that longer cell values and column names can get cut)
colWidths: [100, 120, undefined],
// set each column's width individually, using a function
colWidths(physicalColumnIndex) {
return physicalColumnIndex * 10;
},

commentedCellClassName

Can be set at: grid columns cells cell

Source code

core.commentedCellClassName : string

The commentedCellClassName option lets you add a CSS class name to cells that have comments.

Read more:

Default: “htCommentCell”
Example

// add a `has-comment` CSS class name
// to each cell that has a comment
commentedCellClassName: 'has-comment',

copyable

Can be set at: grid columns cells cell

Source code

core.copyable : boolean

The copyable option determines whether a cell’s value can be copied to the clipboard or not.

You can set the copyable option to one of the following:

SettingDescription
true (default)- On pressing Ctrl/Cmd+C, add the cell’s value to the clipboard
false
(default for the password cell type)
- On pressing Ctrl/Cmd+C, add an empty string ("") to the clipboard

With copyable: false, the cell’s value doesn’t move through other user actions either: cutting the cell clears it and adds an empty string to the clipboard, and dragging the fill handle from it fills the target cells with empty strings. Data access methods, such as getDataAtCell(), still return the real value, while copy-related methods, such as getCopyableData(), return an empty string. The copyable option is not a security measure: formulas and the ExportFile plugin still read the real value. See Password cell type: Copy, cut, paste, and autofill.

Read more:

Default: true
Example

// enable copying for each cell of the entire grid
copyable: true,
// enable copying for individual columns
columns: [
{
// enable copying for each cell of this column
copyable: true
},
{
// disable copying for each cell of this column
copyable: false
}
]
// enable copying for specific cells
cell: [
{
col: 0,
row: 0,
// disable copying for cell (0, 0)
copyable: false,
}
],

currentColClassName

Can be set at: grid

Source code

core.currentColClassName : string

The currentColClassName option lets you add a CSS class name to each cell of the currently-visible, currently-selected columns.

With nested or grouped column headers (the nestedHeaders plugin), the class name reaches every header level above the selected column, not only the leaf level.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Example

// add a `your-class-name` CSS class name
// to each cell of the currently-visible, currently-selected columns
currentColClassName: 'your-class-name',

currentHeaderClassName

Can be set at: grid

Source code

core.currentHeaderClassName : string

The currentHeaderClassName option lets you add a CSS class name to every currently-visible, currently-selected header.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: “ht__highlight”
Example

// add an `ht__highlight` CSS class name
// to every currently-visible, currently-selected header
currentHeaderClassName: 'ht__highlight',

currentRowClassName

Can be set at: grid

Source code

core.currentRowClassName : string

The currentRowClassName option lets you add a CSS class name to each cell of the currently-visible, currently-selected rows.

With multiple row-header columns (added through the afterGetRowHeaderRenderers hook), the class name reaches every row-header column, not only the first one.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Example

// add a `your-class-name` CSS class name
// to each cell of the currently-visible, currently-selected rows
currentRowClassName: 'your-class-name',

data

Can be set at: grid columns

Source code

core.data : Array<Array> | Array<object>

The data option sets the initial data of your Handsontable instance.

Handsontable’s data is bound to your source data by reference (i.e. when you edit Handsontable’s data, your source data alters as well).

You can set the data option:

If you don’t set the data option (or set it to null), Handsontable renders as an empty 5x5 grid by default.

Unless you set the columns or dataSchema option, Handsontable reads the number of columns from the first row of data. If that row has no fields (for example, [{}], [null], or [[], [1, 2]]), the grid displays rows with no cells, and values in later rows are not displayed. For such data, Handsontable logs a console warning. Two cases log no warning: an empty data: [], and an array of empty arrays ([[]]) while allowInsertColumn is on, because writing to it creates the columns. The check runs when the data loads, so set columns together with data. A columns option that arrives in a later update (for example, from a column component rendered after the grid) can come too late to stop the warning.

When used inside the columns option, data has a different meaning: it acts as a property name (or a dot-separated path) pointing to the field in each data row object that this column reads from and writes to. In this context, data is not the full dataset but a column accessor string.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Example

// as an array of arrays
data: [
['A', 'B', 'C'],
['D', 'E', 'F'],
['G', 'H', 'J']
]
// as an array of objects
data: [
{id: 1, name: 'Ted Right'},
{id: 2, name: 'Frank Honest'},
{id: 3, name: 'Joan Well'},
{id: 4, name: 'Gail Polite'},
{id: 5, name: 'Michael Fair'},
]
// as a column accessor inside `columns`
columns: [
{ data: 'id' },
{ data: 'name' }
]

dataDotNotation

Can be set at: grid

Source code

core.dataDotNotation : boolean

If true, Handsontable will interpret the dots in the columns mapping as a nested object path. If your dataset contains the dots in the object keys and you don’t want Handsontable to interpret them as a nested object path, set this option to false.

The option only works when defined in the global table settings.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: true
Since: 14.4.0
Example

// All dots are interpreted as nested object paths
dataDotNotation: true,
data: [
{ id: 1, name: { first: 'Ted', last: 'Right' }, user: { address: '1234 Any Street' } },
],
columns={[
{ data: 'name.first' },
{ data: 'user.address' },
]},
// All dots are interpreted as simple object keys
dataDotNotation: false,
data: [
{ id: 1, 'name.first': 'Ted', 'user.address': '1234 Any Street' },
],
columns={[
{ data: 'name.first' },
{ data: 'user.address' },
]},

dataProvider

Can be set at: grid

Source code

core.dataProvider : object | null

When set, the table loads data from an async provider (e.g. a REST API) instead of a static data array. Use the object form with every key defined: rowId, fetchRows, onRowsCreate, onRowsUpdate, and onRowsRemove. All five are required on that object so paging, row identity, and create, update, and remove map cleanly to your backend. Pair with pagination for server-side paging. The optional refetchAfterCreate key (default true) controls whether a successful onRowsCreate is followed by a fetchRows refetch of the current query. Set it to false when your onRowsCreate applies the server response to the grid itself, for example to keep a new row on the current page while the grid is sorted. With pagination enabled, a skipped refetch leaves the row total and the page count stale until the next fetchRows call, so reconcile them yourself. Valid cell edits apply at once; if onRowsUpdate fails or beforeRowsMutation blocks the update, affected cells roll back.

A string rowId is read the same way as the rowId option: a property named exactly as the string wins, dots included, and otherwise the dots read a nested property. rowId can also be a function that receives the source row and returns its id. Keep that function as a stable reference: a new function passed on each updateSettings() call counts as a new key and fires afterRowIdsReset.

Set it to null to turn server-backed loading off again, for example through updateSettings().

Passing another dataProvider object through updateSettings() reloads the rows. Passing the same object again keeps the rows and sends no request, unless the same call also passes pagination, columnSorting, filters, or columns: those reset the page, sort, or filters, so the rows are fetched again. The React and Angular wrappers pass only the settings that changed, so in React keep the object stable (create it with useMemo). A change made inside the same object is used by the next request; to load the rows right away, call fetchData().

While the sheetsBar option is enabled, a grid-level dataProvider is ignored (with one console warning), and the grid gets it back when you turn the sheets bar off. Declare dataProvider in the settings of each sheet that loads from a server instead, and change it with updateSheetSettings(). If you keep a grid-level dataProvider anyway, pass the same object every time: a framework wrapper that builds a new object on every render re-configures the sheet you see.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Since: 17.1.0
Example

dataProvider: {
rowId: 'id',
fetchRows: async (queryParameters, { signal }) => {
const { page, pageSize, sort, filters } = queryParameters;
const params = new URLSearchParams({ page: String(page), pageSize: String(pageSize) });
if (sort) {
params.set('sortBy', sort.prop);
params.set('sortDir', sort.order);
}
const res = await fetch(`/api/products?${params}`, { signal });
const json = await res.json();
return { rows: json.data, totalRows: json.total };
},
onRowsCreate: async ({ position, referenceRowId, rowsAmount }) => { ... },
onRowsUpdate: async (rows) => { ... },
onRowsRemove: async (rowIds) => { ... },
// Optional: set to `false` to skip the automatic refetch after a successful create (default `true`).
// refetchAfterCreate: false,
},

dataSchema

Can be set at: grid

Source code

core.dataSchema : object | function

When the data option is set to an array of objects (or is empty), the dataSchema option defines the structure of new rows.

Using the dataSchema option, you can start out with an empty grid.

You can set the dataSchema option to one of the following:

  • An object
  • A function

If you don’t set the columns option, dataSchema also defines the columns of the grid. When you change it with updateSettings() and the columns it defines change, Handsontable resets the column and row index state, as it does for a new columns value. Sorting, filtering, and columns that users moved, hid, or resized start over. Options you declare in your settings apply again. A change that only affects the default values of new rows resets nothing. A new data value alone doesn’t reset the index state.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Example

// with `dataSchema`, you can start with an empty grid
data: null,
dataSchema: {id: null, name: {first: null, last: null}, address: null},
colHeaders: ['ID', 'First Name', 'Last Name', 'Address'],
columns: [
{data: 'id'},
{data: 'name.first'},
{data: 'name.last'},
{data: 'address'}
],
startRows: 5,
minSpareRows: 1

dateFormat

Can be set at: grid columns cells cell

Source code

core.dateFormat : Intl.DateTimeFormatOptions

Configures the date format for date cells using an Intl.DateTimeFormat options object.

The locale is controlled separately via the locale option.

Style shortcuts:

PropertyPossible valuesDescription
dateStyle'full', 'long', 'medium', 'short'Date formatting style (expands to weekday, day, month, year, era)

Date-time component options:

PropertyPossible valuesDescription
weekday'long', 'short', 'narrow'Representation of the weekday
era'long', 'short', 'narrow'Representation of the era
year'numeric', '2-digit'Representation of the year
month'numeric', '2-digit', 'long', 'short', 'narrow'Representation of the month
day'numeric', '2-digit'Representation of the day
dayPeriod'narrow', 'short', 'long'Day period (e.g. “am”, “noon”)
hour'numeric', '2-digit'Representation of the hour
minute'numeric', '2-digit'Representation of the minute
second'numeric', '2-digit'Representation of the second
fractionalSecondDigits1, 2, 3Fraction-of-second digits
timeZoneName'long', 'short', 'shortOffset', 'longOffset', 'shortGeneric', 'longGeneric'Time zone display

Locale and other options:

PropertyPossible valuesDescription
localeMatcher'best fit' (default), 'lookup'Locale matching algorithm
calendar'chinese', 'gregory', 'persian', etc.Calendar to use
numberingSystem'latn', 'arab', 'hans', etc.Numbering system
timeZoneIANA time zone (e.g. 'UTC', 'America/New_York')Time zone for formatting
hour12true, falseUse 12-hour vs 24-hour time
hourCycle'h11', 'h12', 'h23', 'h24'Hour cycle
formatMatcher'basic', 'best fit' (default)Format matching algorithm

For complete reference, see MDN: Intl.DateTimeFormat.

Read more:

Default: { year: ‘numeric’, month: ‘2-digit’, day: ‘2-digit’ }
Example

columns: [
{
type: 'date',
locale: 'en-US',
dateFormat: {
dateStyle: 'short'
}
}
]

dateTimeFormat

Can be set at: grid columns cells cell

Source code

core.dateTimeFormat : object

Configures the date-time format for intl-datetime cells using an Intl.DateTimeFormat options object. The locale is controlled separately via the locale option.

For the full list of supported properties, see MDN: Intl.DateTimeFormat.

Read more:

Default: { year: ‘numeric’, month: ‘2-digit’, day: ‘2-digit’, hour: ‘2-digit’, minute: ‘2-digit’, second: ‘2-digit’, hour12: false }
Since: 18.1.0
Example

columns: [
{
type: 'intl-datetime',
locale: 'en-US',
dateTimeFormat: {
dateStyle: 'medium',
timeStyle: 'short'
}
}
]

defaultDate

Can be set at: grid columns cells cell

Source code

core.defaultDate : string

The defaultDate option configures the date pre-selected in the date picker editor when opening an empty date cell for editing.

The option accepts a string in ISO 8601 format (YYYY-MM-DD).

This option can be set at any level of the cascading configuration: the grid level, the columns level, the cells level, and the cell level.

Read more:

Default: undefined
Example

columns: [
{
type: 'date',
defaultDate: '2015-02-02'
}
],

density

Can be set at: grid

Source code

core.density : string | undefined

The density option sets the amount of white space inside the grid without declaring a theme.

You can set it to one of the following:

SettingDescription
undefined (default)Use the density of the current theme
'default'Standard spacing
'compact'Tighter spacing, fits more rows on the screen
'comfortable'Looser spacing, easier to read and to tap

The option is a per-instance override. It applies on top of the current theme, so the theme itself stays unchanged and other grids that use the same theme keep their own density. You can change it at runtime with updateSettings().

The option requires the theme engine, so it has no effect when the theme comes from a CSS class name (the theme option set to a string, or an ht-theme-* class on the container element).

An unsupported value is ignored with a console warning rather than throwing.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Since: 18.1.0
Example

// Render the grid with tighter spacing, without declaring a theme
const hot = new Handsontable(container, {
density: 'compact',
});

Example

// Change the density at runtime
hot.updateSettings({
density: 'comfortable',
});

disableVisualSelection

Can be set at: grid columns cells cell

Source code

core.disableVisualSelection : boolean | string | Array<string>

The disableVisualSelection option configures how selection is shown.

You can set the disableVisualSelection option to one of the following:

SettingDescription
false (default)- Show single-cell selection
- Show range selection
- Show header selection
true- Don’t show single-cell selection
- Don’t show range selection
- Don’t show header selection
'current'- Don’t show single-cell selection
- Show range selection
- Show header selection
'area'- Show single-cell selection
- Don’t show range selection
- Show header selection
'header'- Show single-cell selection
- Show range selection
- Don’t show header selection
An arrayA combination of 'current', 'area', and/or 'header'

The current-row and current-column indicators (currentRowClassName and currentColClassName) are selection feedback rather than header selection, so 'header' does not remove them. They are hidden only when every selection type is off – true, or an array holding all of 'current', 'area', and 'header'. The classes also mark the current row’s and column’s header cell, as they do with false, so 'header' still leaves your currentRowClassName and currentColClassName on those header cells.

When set to any non-false value, the second-click deselect behavior (Ctrl/Cmd+click on an already-selected cell removing it from a multi-cell selection) is also skipped. Without visible feedback, toggling layers off can cause unexpected highlight jumps.

Read more:

Default: false
Example

// don't show single-cell selection
// don't show range selection
// don't show header selection
disableVisualSelection: true,
// don't show single-cell selection
// show range selection
// show header selection
disableVisualSelection: 'current',
// don't show single-cell selection
// don't show range selection
// show header selection
disableVisualSelection: ['current', 'area'],

editor

Can be set at: grid columns cells cell

Source code

core.editor : string | function | boolean

The editor option sets a cell editor for a cell.

You can set the editor option to one of the following cell editor aliases:

AliasCell editor function
A custom aliasYour custom cell editor function
'autocomplete'AutocompleteEditor
'base'BaseEditor
'checkbox'CheckboxEditor
'date'DateEditor
'intl-date'IntlDateEditor
'dropdown'DropdownEditor
'formula'The FormulaBuilder formula editor (a bare textarea while that plugin is off)
'handsontable'HandsontableEditor
'numeric'NumericEditor
'password'PasswordEditor
'select'SelectEditor
'text'TextEditor
'time'TimeEditor
'intl-time'IntlTimeEditor

To disable editing cells through cell editors, set the editor option to false. You’ll still be able to change cells’ content through Handsontable’s API or through plugins (e.g. CopyPaste), though.

When the editor option is set to false, you can still use these keyboard shortcuts:

ShortcutAction
Delete / BackspaceClear the contents of the selected cells
Ctrl + Enter / Cmd + EnterFill selected cells with the value of the active cell

A checkbox cell with no editor is the exception: Delete and Backspace leave it unchanged.

Setting the editor option to true names no editor. It keeps the editor that the cell’s type provides, or the editor inherited from a higher configuration level. Unlike leaving the option out, it also asks for the type’s editor when editor: false is set at a higher configuration level, so the cell stays editable (see below).

An editor of false is not overridden by a type set at a lower configuration level. A type normally supplies its own editor, but it never re-enables editing that you disabled higher up, so editor: false for the whole grid keeps a typed column non-editable. Everything else the type provides still applies, so such a column keeps its renderer and its validator:

// no cell in this grid can be edited, and the second column still
// renders and validates as numeric
editor: false,
columns: [
{ type: 'text' },
{ type: 'numeric' }
]

To let one column opt back in, give it an editor of its own, at the same configuration level as its type:

editor: false,
columns: [
{ type: 'text' },
// editable, despite the grid-level `editor: false`
{ type: 'numeric', editor: 'numeric' }
]

To keep the editor that the column’s type provides, without naming it, set editor: true instead, for example { type: 'numeric', editor: true }. A single cell opts back in the same way, through the cell option or setCellMeta(), also when its type comes from its column.

A custom cell type that declares editor: false supplies a default, not a setting of yours. If you set such a type on the whole grid, a column with a type of its own still gets that type’s editor.

A named editor behaves differently: a type set at a lower configuration level does override it, because both name an editor and the more specific level wins.

Only false is kept this way. An editor of null set at a higher configuration level is replaced by the editor of a lower-level type, like a named editor.

One limitation applies when you switch editing off at runtime. A column’s type writes its editor onto that column when the column is built, so an updateSettings() call that passes editor: false without also passing columns does not reach a column that declares a type. Pass columns in the same call to rebuild those columns:

// the numeric column stays editable
hot.updateSettings({ editor: false });
// the numeric column becomes non-editable too
hot.updateSettings({ editor: false, columns: [{ type: 'text' }, { type: 'numeric' }] });

To set the editor, renderer, and validator options all at once, use the type option.

Read more:

Default: undefined
Example

// use the `numeric` editor for each cell of the entire grid
editor: 'numeric',
// apply the `editor` option to individual columns
columns: [
{
// use the `autocomplete` editor for each cell of this column
editor: 'autocomplete'
},
{
// disable editing cells through cell editors for each cell of this column
editor: false
}
]

emptyValue

Can be set at: grid columns cells cell

Source code

core.emptyValue : *

The emptyValue option sets the value stored when a cell ends up empty.

A cell can be emptied in several ways, and by default they do not agree on what to store. The Delete key, the setDataAtCell() method, filling a blank cell across a range, and merging cells over data all store null. Clearing the cell editor and confirming, or pasting a blank cell, store an empty string (''). Set emptyValue to null to make every one of those paths agree on null.

The mapping is one-way: it rewrites an empty string to the value you set, and never the other way round. Paths that already store null are untouched.

SettingDescription
'' (default)Leave an emptied cell as the empty string the write produced
nullStore null instead
undefinedSame as the default — the option counts as unset
Any other valueStore that value instead

Set emptyValue: null when the cell’s value leaves the grid — saved to a server, written to a database, or read by a formula. An empty string in a numeric, date or time column is a string where a number, a date or nothing at all is expected, and '' is not the same value as NULL to a database. It also matches how spreadsheets tell a blank cell from an empty string: ISBLANK() is true for null and false for ''.

The option applies to every write path: the editor, a paste, a fill, setDataAtCell() and setSourceDataAtCell(). Writing '' through either API with emptyValue: null set stores null.

A valueSetter runs first, so a custom setter that returns '' still means “empty” and is mapped as well.

A column whose configuration already gives '' a meaning keeps it. In a checkbox column, an '' used as checkedTemplate or uncheckedTemplate is one of the two states the column defines, not an empty cell. In an autocomplete or dropdown column, an '' listed in source is an option you can pick. Both keep storing ''.

This option can be set at any level of the cascading configuration: the grid level, the columns level, the cells level, and the cell level.

Default: ”
Since: 18.3.0
Example

// store `null` in every emptied cell of the grid
emptyValue: null,
// or per column: keep text columns storing `''`, and store `null` in the typed ones
columns: [
{ data: 'name' },
{ data: 'amount', type: 'numeric', emptyValue: null },
{ data: 'due', type: 'date', emptyValue: null }
]

enterBeginsEditing

Can be set at: grid

Source code

core.enterBeginsEditing : boolean

The enterBeginsEditing option configures the action of the Enter key.

You can set the enterBeginsEditing option to one of the following:

SettingDescription
true (default)- On pressing Enter once, enter the editing mode of the active cell
- On pressing Enter twice, move to another cell,
as configured by the enterMoves setting
false- On pressing Enter once, move to another cell,
as configured by the enterMoves setting

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: true
Example

// press Enter once to start editing
// press Enter twice to move to another cell
enterBeginsEditing: true,
// press Enter once to move to another cell
enterBeginsEditing: false,

enterCommits

Can be set at: grid columns cells cell

Source code

core.enterCommits : boolean

The enterCommits option configures whether the Enter key closes the multiSelect editor.

Default: true
Since: 17.0.0
Example

columns: [{
type: 'multiselect',
// press Enter to close the `multiSelect` editor and Space to select an option
enterCommits: true,
}, {
type: 'multiselect',
// press Enter to select an option
enterCommits: false,
}],
],

enterMoves

Can be set at: grid

Source code

core.enterMoves : object | function

The enterMoves option configures the action of the Enter key.

If the enterBeginsEditing option is set to true, the enterMoves setting applies to the second pressing of the Enter key.

If the enterBeginsEditing option is set to false, the enterMoves setting applies to the first pressing of the Enter key.

You can set the enterMoves option to an object with the following properties (or to a function that returns such an object):

PropertyTypeDescription
colNumber- On pressing Enter, move selection col columns right
- On pressing Shift+Enter, move selection col columns left
rowNumber- On pressing Enter, move selection row rows down
- On pressing Shift+Enter, move selection row rows up

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: {col: 0, row: 1}
Example

// on pressing Enter, move selection 1 column right and 1 row down
// on pressing Shift+Enter, move selection 1 column left and 1 row up
enterMoves: {col: 1, row: 1},
// the same setting, as a function
// `event` is a DOM Event object received on pressing Enter
// you can use it to check whether the user pressed Enter or Shift+Enter
enterMoves(event) {
return {col: 1, row: 1};
},

fillHandle

Can be set at: grid

Source code

core.fillHandle : boolean | string | object

The fillHandle option configures the Autofill plugin.

You can set the fillHandle option to one the following:

SettingDescription
true- Enable autofill in all directions
- Add the fill handle
falseDisable autofill
'vertical'- Enable vertical autofill
- Add the fill handle
'horizontal'- Enable horizontal autofill
- Add the fill handle
An object- Enable autofill
- Add the fill handle
- Configure autofill options

If you set the fillHandle option to an object, you can configure the following autofill options:

OptionPossible settingsDescription
autoInsertRowtrue (default) | falsetrue: When you reach the grid’s bottom, add new rows
false: When you reach the grid’s bottom, stop
direction'vertical' | 'horizontal''vertical': Enable vertical autofill
'horizontal': Enable horizontal autofill

The autoInsertRow default above applies once you set fillHandle yourself, to any of the values in the first table. Leave fillHandle unset and the grid does not append rows when you drag the fill handle below the last row. Setting direction to 'horizontal' also turns autoInsertRow off.

Rows appended this way bypass allowInsertRow: only autoInsertRow governs them.

The fill handle is shown only when the selection is a single range. A selection of several separate ranges (for example, made with Ctrl/Cmd+click) has no fill handle.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: { autoInsertRow: false }
Example

// enable autofill in all directions
// with `autoInsertRow` enabled
fillHandle: true,
// enable vertical autofill
// with `autoInsertRow` enabled
fillHandle: 'vertical',
// enable horizontal autofill
// with `autoInsertRow` enabled
fillHandle: 'horizontal',
// enable autofill in all directions
// with `autoInsertRow` disabled
fillHandle: {
autoInsertRow: false,
},
// enable vertical autofill
// with `autoInsertRow` disabled
fillHandle: {
autoInsertRow: false,
direction: 'vertical'
},

filter

Can be set at: grid columns cells cell

Source code

core.filter : boolean

The filter option configures whether autocomplete cells’ lists are updated by the end user’s input.

You can set the filter option to one of the following:

SettingDescription
true (default)When the end user types into the input area, only options matching the input are displayed
falseWhen the end user types into the input area, all options are displayed
(options matching the input are put in bold

Read more:

Default: true
Example

columns: [{
// set the `type` of each cell in this column to `autocomplete`
type: 'autocomplete',
// set options available in every `autocomplete` cell of this column
source: ['Apple', 'Apricot', 'Avocado', 'Banana', 'Blueberry'],
// when the end user types in `a`, display options that contain `a`
// when the end user types in `ap`, display only `Apple` and `Apricot`
filter: true
}],

filteringCaseSensitive

Can be set at: grid columns cells cell

Source code

core.filteringCaseSensitive : boolean

The filteringCaseSensitive option configures whether autocomplete and multiSelect-typed cells’ search inputs are case-sensitive.

You can set the filteringCaseSensitive option to one of the following:

SettingDescription
false (default)autocomplete cells’ input is not case-sensitive
trueautocomplete cells’ input is case-sensitive

Read more:

Default: false
Example

columns: [
{
type: 'autocomplete',
source: [ ... ],
// match case while searching autocomplete options
filteringCaseSensitive: true
},
{
type: 'multiselect',
source: [ ... ],
// match case while searching multiSelect options
filteringCaseSensitive: true
}
],

filterSelectedItems

Can be set at: grid columns cells cell

Source code

core.filterSelectedItems : boolean

The filterSelectedItems option configures whether the selected items are filtered out of the dropdown, when using the search input of the multiSelect editor.

Default: true
Example

// filter out the selected items from the dropdown
filterSelectedItems: true,
// keep the selected items in the dropdown
filterSelectedItems: false,
### fixedColumnsEnd
<p class="tag-config-scope-list"><span class="tag-config-scope-label">Can be set at:</span> <span class="tag-config-scope">grid</span></p>
<button type="button" class="ask-about-api-btn" data-option="fixedColumnsEnd" data-plugin="Core" aria-label="Ask AI about fixedColumnsEnd">Ask AI</button>
<a href="https://github.com/handsontable/handsontable/blob/2ecb8ba3f3d6fe761b9a6ddd011a9743405396b2/handsontable/handsontable/tmp/dataMap/metaManager/metaSchema.ts#L3931" target="_blank" rel="noopener noreferrer" class="source-code-link">Source code</a>
_core.fixedColumnsEnd : number_
The `fixedColumnsEnd` option sets the number of [frozen columns](/docs/vue-data-grid/column-freezing/) at the end edge of the grid.
If your grid's [layout direction](/docs/vue-data-grid/layout-direction/) is LTR (default), the end edge is the right-hand edge.
If your layout direction is RTL, the end edge is the left-hand edge.
The frozen columns are the last columns of the grid. They stay in place while the rest of the grid scrolls horizontally.
Hidden columns count toward `fixedColumnsEnd`. The frozen area is always the last `fixedColumnsEnd` columns,
hidden ones included. A trimmed column gives up its slot.
See [Hidden columns](/docs/vue-data-grid/column-freezing/#hidden-columns).
Use `fixedColumnsEnd` together with [`fixedColumnsStart`](/docs/vue-data-grid/api/options/#fixedcolumnsstart), [`fixedRowsTop`](/docs/vue-data-grid/api/options/#fixedrowstop),
and [`fixedRowsBottom`](/docs/vue-data-grid/api/options/#fixedrowsbottom) to freeze all four edges.
<aside class="starlight-aside starlight-aside--tip" aria-label="Tip">
<p class="starlight-aside__title" aria-hidden="true">Tip</p>
<div class="starlight-aside__content"><p>Freeze only as many columns as fit within the grid's width. By default, Handsontable draws frozen columns in full. To draw only the ones that fit, use <a href="/docs/vue-data-grid/api/options/#limitfixedtoviewport"><code>limitFixedToViewport</code></a>.
If they need more space than the grid has, they cover the whole grid. You can then no longer scroll
the remaining columns into view.</p></div>
</aside>
<aside class="starlight-aside starlight-aside--tip" aria-label="Tip">
<p class="starlight-aside__title" aria-hidden="true">Tip</p>
<div class="starlight-aside__content"><p>While <code>fixedColumnsEnd</code> is above <code>0</code>, Handsontable doesn't add empty columns for <a href="/docs/vue-data-grid/api/options/#minsparecols"><code>minSpareCols</code></a>
or <a href="/docs/vue-data-grid/api/options/#mincols"><code>minCols</code></a>. A column added after the last end column would take over the frozen position
and unfreeze the column that holds your data.</p></div>
</aside>
<aside class="starlight-aside starlight-aside--tip" aria-label="Tip">
<p class="starlight-aside__title" aria-hidden="true">Tip</p>
<div class="starlight-aside__content"><p>If <a href="/docs/vue-data-grid/api/options/#fixedcolumnsstart"><code>fixedColumnsStart</code></a> and <code>fixedColumnsEnd</code> together exceed the number of columns,
<code>fixedColumnsStart</code> takes priority and Handsontable reduces the end columns to the columns that remain.</p></div>
</aside>
Read more:
- [Column freezing](/docs/vue-data-grid/column-freezing/)
- [Layout direction](/docs/vue-data-grid/layout-direction/)
- [`fixedColumnsStart`](/docs/vue-data-grid/api/options/#fixedcolumnsstart)
- [`fixedRowsBottom`](/docs/vue-data-grid/api/options/#fixedrowsbottom)
- [`layoutDirection`](/docs/vue-data-grid/api/options/#layoutdirection)
This option can only be set at the [grid level](/docs/vue-data-grid/configuration-options/#set-grid-options).
It has no effect when set in the [`columns`](/docs/vue-data-grid/api/options/#columns), [`cells`](/docs/vue-data-grid/api/options/#cells), or [`cell`](/docs/vue-data-grid/api/options/#cell) options.
**Default**: <code>0</code>
**Since**: 19.0.0
**Example**
```js
// freeze the last 2 columns at the end edge of the grid
// (the right-hand edge in LTR, the left-hand edge in RTL)
fixedColumnsEnd: 2,

fixedColumnsLeft

Can be set at: grid

Source code

core.fixedColumnsLeft : number

fixedColumnsLeft is a legacy option.

If your grid’s layout direction is LTR (default), fixedColumnsLeft acts like the fixedColumnsStart option.

If your grid’s layout direction is RTL, using fixedColumnsLeft throws an error.

Don’t set fixedColumnsLeft and fixedColumnsStart in one settings object: that throws an error. When you set them in separate updateSettings() calls, the later value applies.

Use fixedColumnsStart, which works in any layout direction.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: 0
Example

// freeze the first 3 columns from the left
fixedColumnsLeft: 3,

fixedColumnsStart

Can be set at: grid

Source code

core.fixedColumnsStart : number

If your grid’s layout direction is LTR (default), the fixedColumnsStart option sets the number of frozen columns at the left-hand edge of the grid.

If your grid’s layout direction is RTL, the fixedColumnsStart option sets the number of frozen columns at the right-hand edge of the grid.

Hidden columns count toward fixedColumnsStart. With fixedColumnsStart: 3 and column 1 hidden by HiddenColumns, the grid freezes 2 visible columns. See Hidden columns.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: 0
Example

// when `layoutDirection` is set to `inherit` (default)
// freeze the first 3 columns from the left or from the right
// depending on your HTML document's `dir` attribute
layoutDirection: 'inherit',
fixedColumnsStart: 3,
// when `layoutDirection` is set to `rtl`
// freeze the first 3 columns from the right
// regardless of your HTML document's `dir` attribute
layoutDirection: 'rtl',
fixedColumnsStart: 3,
// when `layoutDirection` is set to `ltr`
// freeze the first 3 columns from the left
// regardless of your HTML document's `dir` attribute
layoutDirection: 'ltr',
fixedColumnsStart: 3,

fixedRowsBottom

Can be set at: grid

Source code

core.fixedRowsBottom : number

The fixedRowsBottom option sets the number of frozen rows at the bottom of the grid.

Rows hidden with HiddenRows count toward fixedRowsBottom. The frozen area is always the last fixedRowsBottom rows, hidden ones included. A trimmed or filtered row gives up its slot. See Hidden rows.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: 0
Example

// freeze the bottom 3 rows
fixedRowsBottom: 3,

fixedRowsTop

Can be set at: grid

Source code

core.fixedRowsTop : number

The fixedRowsTop option sets the number of frozen rows at the top of the grid.

Hidden rows count toward fixedRowsTop. With fixedRowsTop: 3 and row 1 hidden by HiddenRows, the grid freezes 2 visible rows. See Hidden rows.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: 0
Example

// freeze the top 3 rows
fixedRowsTop: 3,

fragmentSelection

Can be set at: grid

Source code

core.fragmentSelection : boolean | string

The fragmentSelection option configures text selection settings.

You can set the fragmentSelection option to one of the following:

SettingDescription
false (default)Disable text selection
trueEnable text selection in multiple cells at a time
'cell'Enable text selection in one cell at a time

With fragmentSelection: true, copying text across multiple cells requires a selectionMode that allows selecting more than one cell. When selectionMode is set to 'single', copying is limited to a single cell.

A text selection cannot span a frozen area and the rest of the grid, because the two are rendered as separate tables. Selecting text inside a frozen row or column works, but as soon as you drag the pointer out of the area you started in, the selection is cleared.

Headers are not selectable, whether or not they are frozen.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: false
Example

// enable text selection in multiple cells at a time
fragmentSelection: true,
// enable text selection in one cell a time
fragmentSelection: 'cell',

hashLength

Can be set at: grid columns cells cell

Source code

core.hashLength : number

The hashLength option sets a fixed display length for the hash mask used by the password cell type.

By default, the hash length equals the actual value length. Set hashLength to a positive integer to always display that many hash symbols regardless of the real value length.

Default: undefined
Example

columns: [
{
type: 'password',
hashLength: 10,
},
],

hashRevealDelay

Can be set at: grid columns cells cell

Source code

core.hashRevealDelay : number

The hashRevealDelay option enables a brief character-reveal on each keystroke in the password cell type editor.

When set to a positive number (milliseconds), each typed character stays visible for that duration and is then replaced by the hashSymbol. This lets the user confirm what they typed without permanently exposing the value. Requires type: 'password'.

Default: undefined
Since: 17.2.0
Example

columns: [
{
type: 'password',
hashRevealDelay: 1000,
},
],

hashSymbol

Can be set at: grid columns cells cell

Source code

core.hashSymbol : string

The hashSymbol option sets the character used as the hash mask in the password cell type renderer.

Defaults to '*'. You can use any character, HTML entity, or string.

Default: ”*“
Example

columns: [
{
type: 'password',
hashSymbol: '•',
},
],

headerClassName

Can be set at: grid columns

Source code

core.headerClassName : string

The headerClassName option allows adding one or more class names to the column headers’ inner div element. It can be used to align the labels in the column headers to left, center or right by setting this option to htLeft, htCenter, or htRight respectively.

Default: undefined
Since: 14.5.0
Example

// Adding class names to all column headers
headerClassName: 'htRight my-class',
columns: [
{
// Adding class names to the column header of a single column
headerClassName: 'htRight my-class',
}
]

height

Can be set at: grid

Source code

core.height : number | ‘auto’ | string | function

The height option configures the height of your grid.

You can set the height option to one of the following:

SettingExample
A number of pixelsheight: 500
A string with a number of pixelsheight: '500', height: '500px'
A string with a CSS unitheight: '50%', height: '75vh'
'auto'height: 'auto'
A function that returns a valid number or stringheight() { return 500; }

Any other value the browser can read as a CSS length or expression ('20em', 'calc(100% - 40px)', 'var(--grid-height)') is passed through as written. A value the browser cannot read as a size ('abc', -100, true) is ignored, and so are these CSS keywords: 'inherit', 'initial', 'unset', 'revert', 'revert-layer', 'none', and 'normal', which do not set a size; 'min-content', 'max-content', and 'fit-content', which size the grid to its full content, so it cannot scroll inside its box; and 'stretch', '-webkit-fill-available', and '-moz-available', which fill the container but read as a fixed size. An ignored value leaves the grid’s height as it was, and a warning is printed once per grid and value.

A number or a CSS length sizes the grid’s box. Handsontable writes height: <value>; overflow: clip; as inline styles on the root element, and the grid scrolls its rows inside that box. An overflow-x or overflow-y you set yourself on the root element is left alone, on that axis, and clips the grid in its place.

How 'auto' differs from leaving height unset

When you set height: 'auto', Handsontable writes height: auto as an inline style on the root element, and nothing else. The grid behaves like a plain block element: it grows to fit its rows, the nearest scrolling ancestor or the page scrolls it, and off-screen rows stay virtualized. The inline value overrides a height a stylesheet sets on the root element.

When you leave height unset, Handsontable does not touch the root element’s inline styles. Sizing is governed by your CSS, and the nearest ancestor with overflow: auto or overflow: hidden becomes the scroll parent. If no such ancestor exists, the window scrolls. See the Grid size guide for details.

Passing null through updateSettings() restores the root element’s initial inline height and the overflow that came with it. A width set through the option is left in place.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Example

// set the grid's height to 500px
height: 500,
// set the grid's height to 75vh
height: '75vh',
// let the grid grow to fit all its rows (no internal vertical scroll)
height: 'auto',
// set the grid's height to 500px, using a function
height() {
return 500;
},

imeFastEdit

Can be set at: grid

Source code

core.imeFastEdit : boolean

The imeFastEdit option allows using the “fast edit” feature for the IME users. It’s disabled by default because of its incompatibility with some of the accessibility features.

Enabling this option can make a negative impact on how some screen readers handle reading the table cells.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Since: 14.0.0

initialState

Can be set at: grid

Source code

core.initialState : object | undefined

The initialState option configures the grid’s initial state. This object accepts any grid configuration option. In case of conflicts between initialState and table settings, the table settings take precedence. Note: The initialState option is ignored when passed to the updateSettings() method.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Since: 16.1.0
Example

initialState: {
// configure initial column order
manualColumnMove: [1, 0],
},

injectCoreCss

Can be set at: grid

Source code

core.injectCoreCss : boolean

The injectCoreCss option controls whether Handsontable injects its core CSS into the document.

You can set the injectCoreCss option to one of the following:

SettingDescription
true (default)Inject core styles into the document head
falseDo not inject core styles (use when you load CSS yourself, e.g. import 'handsontable/styles/handsontable.css')

Handsontable reads this option once, when it creates the grid. Changing it with updateSettings() has no effect.

Grids that Handsontable builds inside a grid follow the grid’s setting. These include the lists of the autocomplete, dropdown, and handsontable editors, the context menu, the dropdown menu, and the Filters menus. With false, none of them injects the core styles. A menu that renders into another document through the uiContainer option injects them there only when the grid injects them.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: true
Since: 17.0.0
Example

// inject core CSS (default)
injectCoreCss: true,
// skip injection when you load Handsontable CSS yourself
injectCoreCss: false,

invalidCellClassName

Can be set at: grid columns cells cell

Source code

core.invalidCellClassName : string

The invalidCellClassName option lets you add a CSS class name to cells that were marked as invalid by the cell validator.

Read more:

Default: “htInvalid”
Example

// add a `highlight-error` CSS class name
// to every `invalid` cell`
invalidCellClassName: 'highlight-error',

label

Can be set at: grid columns cells cell

Source code

core.label : object

The label option configures checkbox cells` labels.

You can set the label option to an object with the following properties:

PropertyPossible valuesDescription
position'after' (default) | 'before''after': place the label to the right of the checkbox
'before': place the label to the left of the checkbox
valueA string | A functionThe label’s text
separatedfalse (default) | truefalse: don’t separate the label from the checkbox
true: separate the label from the checkbox
propertyA string- A data object property name that’s used as the label’s text
- Works only when the data option is set to an array of objects

Read more:

Default: undefined
Example

columns: [{
type: 'checkbox',
// add 'My label:' after the checkbox
label: { position: 'before', value: 'My label: ', separated: true }
}],

language

Can be set at: grid

Source code

core.language : string

The language option configures Handsontable’s language settings.

This option controls the language used for all built-in UI strings, including context menu labels, column sorting labels, validation messages, and other user-visible text. It does not affect the locale used for number or date formatting - use the locale option for that.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

You can set the language option to one of the following:

SettingDescription
'en-US' (default)English - United States
'ar-AR'Arabic - Global

To properly render this language, set the layout direction to RTL.
'cs-CZ'Czech - Czech Republic
'de-CH'German - Switzerland
'de-DE'German - Germany
'es-MX'Spanish - Mexico
'fa-IR'Persian - Iran
'fr-FR'French - France
'hr-HR'Croatian - Croatia
'it-IT'Italian - Italy
'ja-JP'Japanese - Japan
'ko-KR'Korean - Korea
'lv-LV'Latvian - Latvia
'nb-NO'Norwegian (Bokmål) - Norway
'nl-NL'Dutch - Netherlands
'pl-PL'Polish - Poland
'pt-BR'Portuguese - Brazil
'ru-RU'Russian - Russia
'sr-Latn-RS'Serbian (Latin) - Serbia
'sr-SP'Serbian (Latin) - Serbia (deprecated alias of 'sr-Latn-RS')
'zh-CN'Chinese - China
'zh-TW'Chinese - Taiwan

Read more:

Default: “en-US”
Example

// set Handsontable's language to Polish
language: 'pl-PL',

layout

Can be set at: grid

Source code

core.layout : object

The layout option configures the order of plugin UI elements within the user-orderable wrapper slots rendered around the grid: top, bottom, start, and end. The top and bottom slots sit above and below the grid. The start and end slots sit at the grid’s inline-start and inline-end edges (with layoutDirection: 'rtl', start is on the right). Each slot takes an ordered array of element keys (for example 'pagination'). Keys you list are placed first in that order; any remaining elements follow by their default weight. The grid and the overlays layer (the modal layer, such as the dialog) are not orderable through this option. The license notification is not orderable either; it always renders last in the bottom slot. The start and end slots are available since 19.0.0.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Since: 18.0.0
Example

// render pagination above a custom 'summary' element registered in the bottom slot
layout: {
bottom: ['pagination', 'summary'],
},
// in the start side slot, render a custom 'filters' panel at the outer edge, before a custom 'notes' panel
layout: {
start: ['filters', 'notes'],
},

layoutDirection

Can be set at: grid

Source code

core.layoutDirection : string

The layoutDirection option configures whether Handsontable renders from the left to the right, or from the right to the left.

You can set the layout direction only at Handsontable’s initialization. Any change of the layoutDirection option after the initialization (e.g. using the updateSettings() method) throws an error, even when you didn’t set the option at initialization.

You can set the layoutDirection option only for the entire grid. You can’t set it for individual columns, rows, or cells.

You can set the layoutDirection option to one of the following strings:

SettingDescription
inherit (default)Set Handsontable’s layout direction automatically,
based on the value of your HTML document’s dir attribute
rtlRender Handsontable from the right to the left,
even when your HTML document’s dir attribute is set to ltr
ltrRender Handsontable from the left to the right,
even when your HTML document’s dir attribute is set to rtl

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: “inherit”
Example

// inherit Handsontable's layout direction
// from the value of your HTML document's `dir` attribute
layoutDirection: 'inherit',
// render Handsontable from the right to the left
// regardless of your HTML document's `dir`
layoutDirection: 'rtl',
// render Handsontable from the left to the right
// regardless of your HTML document's `dir`
layoutDirection: 'ltr',

licenseKey

Can be set at: grid

Source code

core.licenseKey : string

The licenseKey option sets your Handsontable license key.

You can set the licenseKey option to one of the following:

SettingDescription
A string with your commercial license keyFor commercial use
A string with your entitlement license key (plain-English text ending with a [...] block)For trial, subscription, or perpetual use

Since Handsontable 19.0, the 'non-commercial-and-evaluation' key, and its second form 'ht68e-1f2b7-47158-70b05-0842f', are not valid keys: they lock the grid, as any invalid key does. See Get a license key.

An entitlement license key can name one or more tiers. The grid turns on the features of those tiers, and a plugin they do not include stays off: the console and the bar under the grid name it. The plugin’s option keeps the value you set, so passing a key whose tier includes the feature through updateSettings() turns the plugin on. A key that names no tier turns on every feature. See Keys that name a tier.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Example

// for commercial use (legacy 25-character format)
licenseKey: 'xxxxx-xxxxx-xxxxx-xxxxx-xxxxx', // your commercial license key
// for an entitlement license key (trial, subscription, or perpetual),
// pass the whole key string exactly as you received it – the key
// protects its text too, so the `[...]` block on its own is not a valid key;
// the text contains quotes, so use a template literal
licenseKey: `This is a Handsontable license key for Acme Corp, ... for the "Acme Portal" project. ... [eyJwcm9kdWN0cyI6...3a4f8361]`,

limitFixedToViewport

Can be set at: grid

Source code

core.limitFixedToViewport : boolean

The limitFixedToViewport option keeps the frozen rows and columns from growing larger than the space the grid has.

By default, Handsontable draws the frozen area in full. If the frozen rows and columns need more space than the grid has, they cover the whole grid, and you can no longer scroll the rest of it into view.

When you set limitFixedToViewport to true, Handsontable draws only as many frozen columns and rows as fit, and keeps a strip of the grid scrollable. The option changes what is drawn, not what you configured: fixedColumnsEnd, fixedRowsTop, and fixedRowsBottom.

  • The count is measured again when the grid is resized, so the frozen area returns when the grid grows.
  • A strip of at least 40 px stays scrollable on each axis.
  • The start columns have priority over the end columns, and the top rows have priority over the bottom rows. When the start columns or top rows fill the grid, the end columns or bottom rows are not drawn as frozen at all.
  • When a user changes the frozen area with the FreezeBar plugin, the new count replaces the configured one, and the frozen area no longer returns when the grid grows.
  • When one more frozen column would not fit, freezeColumn() does nothing, and its afterColumnFreeze hook reports that the freeze was not performed.

Handsontable measures the frozen area while it renders. When the first measurement was off (a row that was never drawn, or a scrollbar that appeared), it draws once more, so beforeViewRender and afterViewRender can run twice for one render. A change that makes a frozen row taller can cost that extra draw each time.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: false
Since: 19.0.0
Example

// draw only the frozen columns and rows that fit the grid
limitFixedToViewport: true,

locale

Can be set at: grid columns cells cell

Source code

core.locale : string

The locale option configures Handsontable’s locale settings.

You can set the locale option to any valid and canonicalized Unicode BCP 47 locale tag, both for the entire grid, and for individual columns.

Read more:

Default: “en-US”
Example

// set the entire grid's locale to Polish
locale: 'pl-PL',
// set individual columns' locales
columns: [
{
// set the first column's locale to Polish
locale: 'pl-PL',
},
{
// set the second column's locale to German
locale: 'de-DE',
},
],

maxCols

Can be set at: grid

Source code

core.maxCols : number

The maxCols option sets a maximum number of columns.

The maxCols option is used:

  • At initialization: if the maxCols value is lower than the initial number of columns, Handsontable trims columns from the right.
  • At runtime: for example, when inserting columns.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: Infinity
Example

// set the maximum number of columns to 300
maxCols: 300,

maxLength

Can be set at: grid columns cells cell

Source code

core.maxLength : number

The maxLength option sets the maximum number of characters that a cell can hold.

The limit counts the characters a reader sees, in the same way as the length limit of a sheet name in the SheetsBar plugin. A flag, an emoji with a skin tone, and a letter with a combining accent each count as one character.

Handsontable enforces the limit in two places:

  • In the cell editor. The text editor, and any custom editor that extends it, stops the user from typing or pasting more characters than the limit allows. The autocomplete, dropdown, and handsontable editors cap what the user types in the same way, but the user can still pick an option that is longer than the limit, and the validator then marks it as invalid. The built-in editors of the other cell types, such as numeric, date, and password, don’t limit input.
  • In the cell validator, which marks a value that is too long as invalid. Use allowInvalid to decide whether the grid keeps such a value. The validator checks the values that you type, paste into the grid, or write with setDataAtCell(), and the values that validateCells() checks. It doesn’t check the values that you load with loadData(), updateData(), or setSourceDataAtCell(), or that a data provider fetches. Such a value stays unmarked until you call validateCells().

If a cell also has a validator, a value must pass both checks. The length check runs first. Setting validator to false turns off the validator, but not the length check.

Keep these points in mind:

  • Handsontable checks string values only. It doesn’t check a value that is stored as a number, such as the digits typed into a numeric cell, or as any other non-string type.
  • The validator checks every string value in a cell that has a limit, whatever the cell type is. If you set maxLength at the grid level, it also applies to the text of date, time, dropdown, and autocomplete cells, so a date such as '2026-10-02' is invalid with maxLength: 8. Set the option on the columns that hold free text instead.
  • A cell that has a limit validates every write, as any cell with a validator does. Validation is asynchronous, so setDataAtCell() applies a value after the validation finishes, and getDataAtCell() returns the previous value until then. Use the afterChange hook to react to the new value.
  • The editor and the validator both count the value after trimWhitespace is applied, so the leading and trailing spaces of a pasted text don’t count.
  • With the Formulas plugin, the editor counts the formula that the user types, but the validator counts the calculated result. With maxLength: 5, the editor cuts =SUM(A1:A10) to =SUM(, although the result 55 fits.
  • If your app already uses maxLength as a custom cell meta key, for example to feed your own validator or editor, the built-in check and the editor limit now apply to those cells too.

By default, the number of characters is not limited.

Read more:

Default: Infinity
Since: 19.0.0
Example

// limit the free-text columns, and leave the others unlimited
columns: [
{ data: 'code', maxLength: 10 },
{ data: 'comment', maxLength: 140, allowInvalid: false },
{ data: 'quantity', type: 'numeric' },
],
// let a single cell hold more than its column allows
cell: [
{ row: 0, col: 0, maxLength: 20 },
],

maxRows

Can be set at: grid

Source code

core.maxRows : number

The maxRows option sets a maximum number of rows.

The maxRows option is used:

  • At initialization: if the maxRows value is lower than the initial number of rows, Handsontable trims rows from the bottom.
  • At runtime: for example, when inserting rows.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: Infinity
Example

// set the maximum number of rows to 300
maxRows: 300,

maxSelections

Can be set at: grid columns cells cell

Source code

core.maxSelections : number

The maxSelections option sets a maximum number of selections for the multiSelect-typed cells.

Default: undefined
Since: 17.0.0
Example

columns: [{
// set the `type` of each cell in this column to `multiSelect`
type: 'multiselect',
// set the maximum number of selections to 3
maxSelections: 3,
}],

minCols

Can be set at: grid

Source code

core.minCols : number

The minCols option sets a minimum number of columns.

The minCols option is used:

  • At initialization: if the minCols value is higher than the initial number of columns, Handsontable adds empty columns to the right.
  • At runtime: for example, when removing columns.

While fixedColumnsEnd is above 0, Handsontable doesn’t add empty columns for minCols, because a column added after the last end column would take over the frozen position at the grid’s end.

When you lower the minCols value with updateSettings(), Handsontable removes the empty columns it added that the new value no longer requires. It never removes a column that holds data, a column that came with your data, or a column you added yourself. Nothing is removed while maxCols hides part of the grid. The removal fires the beforeRemoveCol and afterRemoveCol hooks with the auto source, and returning false from beforeRemoveCol keeps the columns.

The minCols option works only when your data is an array of arrays. When your data is an array of objects, you can only have as many columns as defined in:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: 0
Example

// set the minimum number of columns to 10
minCols: 10,

minRowHeights

Can be set at: grid

Source code

core.minRowHeights : number | Array<number> | string | Array<string> | Array<undefined> | function

The minRowHeights option sets the minimum height of rows, in pixels.

A row is never shorter than this value, but it grows to fit taller content. A value smaller than the default row height has no effect, because a row is never shorter than the default. To set a row to an exact height and clip content that does not fit, use rowHeights instead. You can set both options: rowHeights sets the rows it gives a height, and minRowHeights applies to the others.

Take the accepted forms (a number, a string, an array, or a function) from the rowHeights option description. Like rowHeights, the array and the function address a row by its physical index, so a minimum height stays with its row.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Since: 16.2.0
Example

// set every row's minimum height to 100px
minRowHeights: 100,
// set every row's minimum height to 100px
minRowHeights: '100px',
// set the first (by physical index) row's minimum height to 100
// set the second (by physical index) row's minimum height to 120
// set any other row's minimum height to the default height value
minRowHeights: [100, 120],
// set each row's minimum height individually, using a function
minRowHeights(physicalRowIndex) {
return physicalRowIndex * 10;
},

minRows

Can be set at: grid

Source code

core.minRows : number

The minRows option sets a minimum number of rows.

The minRows option is used:

  • At initialization: if the minRows value is higher than the initial number of rows, Handsontable adds empty rows at the bottom.
  • At runtime: for example, when removing rows.

When you lower the minRows value with updateSettings(), Handsontable removes the empty rows it added that the new value no longer requires. It never removes a row that holds data, a row that came with your data, or a row you added yourself. Nothing is removed while maxRows hides part of the grid. The removal fires the beforeRemoveRow and afterRemoveRow hooks with the auto source, and returning false from beforeRemoveRow keeps the rows. The value counts only the rows on screen, so while filters or trimRows hides rows, lowering it can leave some of the added empty rows in place.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: 0
Example

// set the minimum number of rows to 10
minRows: 10,

minSpareCols

Can be set at: grid

Source code

core.minSpareCols : number

The minSpareCols option sets a minimum number of empty columns at the grid’s right-hand end.

If there already are other empty columns at the grid’s right-hand end, they are counted into the minSpareCols value.

When you lower the minSpareCols value with updateSettings(), Handsontable removes the empty columns it added that the new value no longer requires. It never removes a column that holds data, a column that came with your data, or a column you added yourself. Nothing is removed while maxCols hides part of the grid. The removal fires the beforeRemoveCol and afterRemoveCol hooks with the auto source, and returning false from beforeRemoveCol keeps the columns.

The total number of columns can’t exceed the maxCols value.

While fixedColumnsEnd is above 0, Handsontable doesn’t add spare columns, because a spare column would take over the frozen position at the grid’s end.

The minSpareCols option works only when your data is an array of arrays. When your data is an array of objects, you can only have as many columns as defined in:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: 0
Example

// at Handsontable's initialization, add at least 3 empty columns on the right
minSpareCols: 3,

minSpareRows

Can be set at: grid

Source code

core.minSpareRows : number

The minSpareRows option sets a minimum number of empty rows at the bottom of the grid.

If there already are other empty rows at the bottom, they are counted into the minSpareRows value.

When you lower the minSpareRows value with updateSettings(), Handsontable removes the empty rows it added that the new value no longer requires. It never removes a row that holds data, a row that came with your data, or a row you added yourself. Nothing is removed while maxRows hides part of the grid. The removal fires the beforeRemoveRow and afterRemoveRow hooks with the auto source, and returning false from beforeRemoveRow keeps the rows. The value counts only the rows on screen, so while filters or trimRows hides rows, lowering it can leave some of the added empty rows in place.

The total number of rows can’t exceed the maxRows value.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: 0
Example

// at Handsontable's initialization, add at least 3 empty rows at the bottom
minSpareRows: 3,

moveCells

Can be set at: grid

Source code

core.moveCells : boolean

The moveCells option lets you move a selection by dragging its edge. When enabled, hovering the border of a selected cell range shows a grab cursor; dragging the border moves the block’s data (values, the className cell meta, and – with the formulas plugin – adjusted formula references) to the new location. Other cell meta (for example numericFormat or readOnly) stays at the source cells. Hold Ctrl/Cmd during the drag to copy instead of move.

The move applies to a single contiguous cell range only. It has no effect on full-row, full-column, select-all, or multiple selections, the range may span at most 100,000 cells, and the source and target must stay within the grid. Neither the target nor the source may overlap read-only cells, because a move has to clear the source — a copy leaves the source in place, so a read-only source cell blocks a move but not a copy.

This option can only be set at the grid level.

Default: false
Since: 18.1.0
Example

// enable drag-to-move for selections
moveCells: true,

Can be set at: grid

Source code

core.navigableHeaders : boolean

When set to true, the navigableHeaders option lets you navigate row headers and column headers, using the arrow keys or the Tab key (if the tabNavigation option is set to true).

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: false
Since: 14.0.0
Example

// you can navigate row and column headers with the keyboard
navigableHeaders: true,
// default behavior: you can't navigate row and column headers with the keyboard
navigableHeaders: false,

noWordWrapClassName

Can be set at: grid columns cells cell

Source code

core.noWordWrapClassName : string

The noWordWrapClassName option lets you add a CSS class name to each cell that has the wordWrap option set to false.

Handsontable always adds the built-in htNoWrap class, which keeps the content on one line, and then adds your class too. You can use your class for styling without a white-space rule. To set a different white-space value, use a selector stronger than .handsontable .htNoWrap, for example .handsontable td.yourClass.

If you set noWordWrapClassName to an empty string, Handsontable adds no class at all.

Read more:

Default: “htNoWrap”
Example

// add an `is-noWrapCell` CSS class name
// to each cell that doesn't wrap content
noWordWrapClassName: 'is-noWrapCell',

numericFormat

Can be set at: grid columns cells cell

Source code

core.numericFormat : object

Configures the number format for numeric cells, including currency, units, precision, and other display options.

Since v17.0.0, this option accepts all properties of the Intl.NumberFormatOptions object. The locale is controlled separately via the locale option.

Style options:

PropertyPossible valuesDescription
style'decimal' (default), 'currency', 'percent', 'unit'The formatting style to use
currencyISO 4217 currency codes (e.g., 'USD', 'EUR', 'PLN')Required when style is 'currency'
currencyDisplay'symbol' (default), 'narrowSymbol', 'code', 'name'How to display the currency
currencySign'standard' (default), 'accounting'Use parentheses for negative values in accounting format
unitUnit identifiers (e.g., 'kilometer', 'liter')Required when style is 'unit'
unitDisplay'short' (default), 'narrow', 'long'How to display the unit

Notation options:

PropertyPossible valuesDescription
notation'standard' (default), 'scientific', 'engineering', 'compact'The formatting notation
compactDisplay'short' (default), 'long'Display style for compact notation (e.g., 1.5M vs 1.5 million)

Sign and grouping options:

PropertyPossible valuesDescription
signDisplay'auto' (default), 'never', 'always', 'exceptZero', 'negative'When to display the sign
useGroupingtrue, false (default), 'always', 'auto', 'min2'Whether to use grouping separators (e.g., 1,000)

Digit options:

PropertyPossible valuesDescription
minimumIntegerDigits1 to 21Minimum number of integer digits (pads with zeros)
minimumFractionDigits0 to 100Minimum number of fraction digits
maximumFractionDigits0 to 100Maximum number of fraction digits
minimumSignificantDigits1 to 21Minimum number of significant digits
maximumSignificantDigits1 to 21Maximum number of significant digits

Rounding options:

PropertyPossible valuesDescription
roundingMode'halfExpand' (default), 'ceil', 'floor', 'expand', 'trunc', 'halfCeil', 'halfFloor', 'halfTrunc', 'halfEven'Rounding algorithm
roundingPriority'auto' (default), 'morePrecision', 'lessPrecision'Priority between fraction and significant digits
roundingIncrement1, 2, 5, 10, 20, 25, 50, 100, 200, 250, 500, 1000, 2000, 2500, 5000Increment for rounding (e.g., nickel rounding)
trailingZeroDisplay'auto' (default), 'stripIfInteger'Whether to strip trailing zeros for integers

Locale options:

PropertyPossible valuesDescription
localeMatcher'best fit' (default), 'lookup'Locale matching algorithm
numberingSystem'latn', 'arab', 'hans', 'deva', 'thai', etc.Numbering system to use

For complete reference, see MDN: Intl.NumberFormat.

This option affects only the displayed output in the cell renderer. It has no effect on the numeric cell editor. In the source data, numeric values are stored as JavaScript numbers, so a value beyond the safe-integer limit (9007199254740991) loses precision before the formatter ever sees it. To store and display such a value exactly, set preserveNumericLiteral to true and provide the value as a string.

Read more:

Default: undefined
Since: 0.35.0
Example

columns: [
{
type: 'numeric',
locale: 'en-US',
numericFormat: {
style: 'currency',
currency: 'USD',
}
}
],

observeDOMVisibility

Can be set at: grid

Source code

core.observeDOMVisibility : boolean

If the observeDOMVisibility option is set to true, Handsontable rerenders every time it detects that the grid was made visible in the DOM.

Handsontable uses a MutationObserver to watch for CSS changes (such as display: none being removed) on the container element and its ancestors. When visibility is restored after being hidden, Handsontable automatically triggers a rerender to ensure correct layout and dimensions. Set this option to false if you want to control rendering manually (e.g. by calling render() yourself).

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: true
Example

// don't rerender the grid on visibility changes
observeDOMVisibility: false,

outsideClickDeselects

Can be set at: grid

Source code

core.outsideClickDeselects : boolean | function

The outsideClickDeselects option determines what happens to the current selection when you click outside of the grid.

You can set the outsideClickDeselects option to one of the following:

SettingDescription
true (default)On a mouse click outside of the grid, clear the current selection
falseOn a mouse click outside of the grid, keep the current selection
A functionA function that takes the click event target and returns a boolean

A click on the sheets bar doesn’t count as a click outside of the grid: it keeps the current selection and saves a cell you are editing, whatever this option is set to.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: true
Example

// on a mouse click outside of the grid, clear the current selection
outsideClickDeselects: true,
// on a mouse click outside of the grid, keep the current selection
outsideClickDeselects: false,
// take the click event target and return `false`
outsideClickDeselects(event) {
return false;
}
// take the click event target and return `true`
outsideClickDeselects(event) {
return false;
}

placeholder

Can be set at: grid columns cells cell

Source code

core.placeholder : string

The placeholder option lets you display placeholder text in every empty cell.

You can set the placeholder option to one of the following:

SettingExampleDescription
A non-empty string'Empty cell'Display Empty cell text in empty cells
A non-string value000Display 000 text in empty cells (non-string values get stringified)

Read more:

Default: undefined
Example

// display 'Empty cell' text
// in every empty cell of the entire grid
placeholder: 'Empty cell',
// or
columns: [
{
data: 'date',
dateFormat: { day: '2-digit', month: '2-digit', year: 'numeric' },
// display 'Empty date cell' text
// in every empty cell of the `date` column
placeholder: 'Empty date cell'
}
],

placeholderCellClassName

Can be set at: grid columns cells cell

Source code

core.placeholderCellClassName : string

The placeholderCellClassName option lets you add a CSS class name to cells that contain placeholder text.

Read more:

Default: “htPlaceholder”
Example

// add a `has-placeholder` CSS class name
// to each cell that contains `placeholder` text
placeholderCellClassName: 'has-placeholder',

preserveNumericLiteral

Can be set at: grid columns cells cell

Source code

core.preserveNumericLiteral : boolean

Controls whether a numeric cell keeps the exact text you typed when converting it to a JavaScript number would lose information.

By default (false), a numeric cell always stores the parsed JavaScript number, so a value like 9.0 is stored as 9 and the editor shows 9 the next time you open it. Numbers whose magnitude exceeds the safe-integer limit (9007199254740991) also lose precision.

When set to true, and only when parsing would be lossy, the cell keeps the original literal string instead of the number. This preserves trailing decimal zeros (9.0, 9.50) and the full precision of large numbers in the cell editor, matching spreadsheet software. Values that convert without loss (for example 9, 9.5, 1000) are still stored as numbers, so sorting, filtering, and formula calculations are unaffected. A preserved literal also keeps behaving like a number in those features: column sorting and filter conditions compare it numerically, and the Formulas engine parses the literal as a number, so functions such as SUM still include the cell. The cell renderer still formats the value according to numericFormat, and it keeps every digit of the literal: Intl.NumberFormat reads a string operand as an exact decimal instead of converting it to a JavaScript number. That makes preserveNumericLiteral the supported way to display a value beyond the safe-integer limit: the literal '9007199254740993' renders with every digit intact, while the same value held as a number renders as 9007199254740992. Grouping and decimals still follow numericFormat. One exception: the filter menu’s “Filter by value” checkbox list compares values strictly, so a preserved literal ('9.0') and its plain number (9) appear as two separate entries.

The default is false so existing configurations keep their current behavior.

Default: false
Since: 18.1.0
Example

columns: [
{
type: 'numeric',
// keep `9.0` and very large numbers as typed in the editor
preserveNumericLiteral: true,
}
],

preventOverflow

Can be set at: grid

Source code

core.preventOverflow : string | boolean

The preventOverflow option configures preventing Handsontable from overflowing outside of its parent element.

When enabled, Handsontable caps its own dimensions to match the parent container’s size in the specified direction, preventing the grid from extending beyond the visible bounds of its parent. This is useful when the parent element has overflow: hidden or a fixed size and you want the grid to fit within it.

You can set the preventOverflow option to one of the following:

SettingDescription
false (default)Don’t prevent overflowing
'horizontal'Prevent horizontal overflowing
'vertical'Prevent vertical overflowing

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: false
Example

// prevent horizontal overflowing
preventOverflow: 'horizontal',

readOnly

Can be set at: grid columns cells cell

Source code

core.readOnly : boolean

The readOnly option determines whether a cell, comment, column or the entire grid is editable or not. You can configure it as follows:

SettingDescription
false (default)Set as editable
true- Set as read-only
- Add the readOnlyCellClassName CSS class name (by default: htDimmed)

readOnly cells can’t be changed by the populateFromArray() method.

Read more:

Default: false
Example

// make the entire grid read-only
const configurationOptions = {
columnSorting: true,
};
// make the third column read-only
const configurationOptions = {
columns: [
{},
{},
{
readOnly: true,
},
],
};
// make a specific cell read-only
const configurationOptions = {
cell: [
{
row: 0,
col: 0,
readOnly: true,
},
};

readOnlyCellClassName

Can be set at: grid columns cells cell

Source code

core.readOnlyCellClassName : string

The readOnlyCellClassName option lets you add a CSS class name to read-only cells.

Read more:

Default: “htDimmed”
Example

// add a `is-readOnly` CSS class name
// to every read-only cell
readOnlyCellClassName: 'is-readOnly',

readOnlyStyling

Can be set at: grid columns cells cell

Source code

core.readOnlyStyling : boolean

The readOnlyStyling option controls whether read-only cells look different from editable ones.

You can set the readOnlyStyling option to one of the following:

SettingDescription
true (default)Read-only cells are dimmed, through the readOnlyCellClassName CSS class
falseRead-only cells look exactly like editable ones

Set readOnlyStyling to false to make a grid non-editable without the cells looking different. Only the appearance changes: read-only cells still reject edits, pasting, and autofill, and are still announced as read-only by screen readers.

When readOnlyStyling is false, no readOnlyCellClassName class is added at all, so setting both options means readOnlyStyling wins.

The same applies to a checkbox cell with no editor: when readOnlyStyling is false, its checkbox is not rendered disabled, but a click still doesn’t change its value.

A multiselect cell works the same way: a read-only cell, or one with no editor, normally draws its chips without the remove button, but when readOnlyStyling is false the button stays, and a click on it doesn’t change the value.

Read more:

Default: true
Since: 19.0.0
Example

// make the whole grid read-only, but keep it looking like a normal table
readOnly: true,
readOnlyStyling: false,
// apply the option to individual columns
columns: [
{
readOnly: true,
// this column is read-only, and is not dimmed
readOnlyStyling: false
}
]

renderAllColumns

Can be set at: grid

Source code

core.renderAllColumns : boolean

The renderAllColumns option configures Handsontable’s column virtualization.

You can set the renderAllColumns option to one of the following:

SettingDescription
false (default)Enable column virtualization, rendering only visible columns for better performance with many columns.
trueDisable column virtualization
(render all columns of the grid), rendering all columns in the dataset, and ensuring all columns are available regardless of horizontal scrolling.

Setting renderAllColumns to true overwrites the viewportColumnRenderingOffset setting.

You can set the renderAllColumns option only at Handsontable’s initialization. Any change of it after the initialization (e.g. using the updateSettings() method) throws an error, even when you didn’t set the option at initialization.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: false
Since: 14.1.0
Example

// disable column virtualization
renderAllColumns: true,

renderAllRows

Can be set at: grid

Source code

core.renderAllRows : boolean

The renderAllRows option controls Handsontable’s row virtualization. You can configure it as follows:

SettingDescription
false (default)Enable row virtualization, rendering only the visible rows for optimal performance with large datasets.
trueDisable row virtualization
(render all rows of the grid), rendering all rows in the dataset for consistent rendering and screen reader accessibility.

Setting renderAllRows to true overwrites the viewportRowRenderingOffset setting.

You can set the renderAllRows option only at Handsontable’s initialization. Any change of it after the initialization (e.g. using the updateSettings() method) throws an error, even when you didn’t set the option at initialization.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: false
Example

// disable row virtualization
renderAllRows: true,

renderer

Can be set at: grid columns cells cell

Source code

core.renderer : string | function

The renderer option sets a cell renderer for a cell.

You can set the renderer option to one of the following:

AliasCell renderer function
A custom aliasYour custom cell renderer function
'autocomplete'AutocompleteRenderer
'base'BaseRenderer
'checkbox'CheckboxRenderer
'date'DateRenderer
'intl-date'IntlDateRenderer
'dropdown'DropdownRenderer
'html'HtmlRenderer
'numeric'NumericRenderer
'password'PasswordRenderer
'text'TextRenderer
'time'TimeRenderer
'intl-time'IntlTimeRenderer

To set the renderer, editor, and validator options all at once, use the type option.

Read more:

Default: undefined
Example

// use the `numeric` renderer for each cell of the entire grid
renderer: `'numeric'`,
// add a custom renderer function
renderer(hotInstance, td, row, column, prop, value, cellProperties) {
// your custom renderer's logic
...
}
// apply the `renderer` option to individual columns
columns: [
{
// use the `autocomplete` renderer for each cell of this column
renderer: 'autocomplete'
},
{
// use the `myCustomRenderer` renderer for each cell of this column
renderer: 'myCustomRenderer'
}
]

renderMode

Can be set at: grid columns cells cell

Source code

core.renderMode : string

The renderMode option decides when a cell is painted during a render.

You can set the renderMode option to one of the following:

SettingDescription
'always' (default)The cell is painted on every render.
'onChange'The cell is painted only when the element it lands in showed something else after its last paint: another cell, another value, another renderer, a changed cell meta (through setCellMeta() or the cells function), or a structural change of the grid.

Under 'onChange', a render skips the cells whose paint would produce the same result as their last paint. A vertical scroll keeps the elements of the rows that stay rendered, so it paints only the rows that enter the rendered area, plus the cells of merged blocks, whose span depends on that area. A horizontal scroll repaints the rendered cells, and so does any scroll in a grid that scrolls with the page. Some changes are not detected, because nothing in the grid sees them:

  • a meta object mutated directly (getCellMeta(row, col).x = y, including inside the beforeGetCellMeta and afterGetCellMeta hooks),
  • a value object mutated in place (the grid compares values by identity),
  • state outside the grid that a renderer reads,
  • a renderer that reads the data of other cells, such as the checkbox renderer with label.property,
  • a renderer that reads where the rendered area starts or ends, through getFirstRenderedVisibleRow() or its siblings: a vertical scroll keeps such a cell as it is.

Set renderMode: 'always' on such cells, or mark them with markCellChanged() before rendering. A cells function result is compared value by value, so return the same references for an unchanged result: a renderer function created on every call counts as a change on every render.

The option cascades, so a single column of slow renderers can use 'onChange' while the rest of the grid keeps the default.

Read more:

Default: “always”
Since: 19.0.0
Example

// paint every cell on every render (default)
renderMode: 'always',
// paint only the cells that changed
renderMode: 'onChange',
// skip unchanged cells in one slow column only
columns: [
{ data: 'chart', renderer: chartRenderer, renderMode: 'onChange' },
{ data: 'name' },
],

rowHeaders

Can be set at: grid

Source code

core.rowHeaders : boolean | Array<string> | function

The rowHeaders option configures your grid’s row headers.

You can set the rowHeaders option to one of the following:

SettingDescription
trueEnable the default row headers (‘1’, ‘2’, ‘3’, …)
falseDisable row headers
An arrayDefine your own row headers (e.g. ['One', 'Two', 'Three', ...])
A functionDefine your own row headers, using a function

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Example

// enable the default row headers
rowHeaders: true,
// set your own row headers
rowHeaders: ['One', 'Two', 'Three'],
// set your own row headers, using a function
rowHeaders: function(visualRowIndex) {
return `${visualRowIndex}: AB`;
},

rowHeaderWidth

Can be set at: grid

Source code

core.rowHeaderWidth : number | Array<number> | string | Array<string> | Array<(number|string)>

The rowHeaderWidth option configures the width of row headers.

You can set the rowHeaderWidth option to one of the following:

SettingDescription
A numberSet the same width for every row header
A stringSet the same width, written as a pixel size ('25', '25px')
An arraySet different widths for individual row headers

The width is a number of pixels. A string that states a pixel size works too, either as a bare number ('25') or with the unit ('25px'), so a value coming from an attribute or a JSON config still applies. Both forms may be mixed inside the array.

A value that is not a pixel size, such as '50%' or '20em', is ignored and the default width is used instead. Inside an array, that applies per level, so one unreadable entry does not disturb the levels around it.

A negative number is kept as it is, because numbers keep the behavior they had before this option read strings at all. A negative string is rejected instead, so a typo cannot collapse the header.

Row headers have a fixed width. A label longer than that width is clipped, and unlike column headers, the header does not grow to fit it. To size the header to its content instead, turn on the autoRowHeaderSize plugin - it takes the width over, and this option is then ignored.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Example

// set the same width for every row header
rowHeaderWidth: 25,
// set the same width, written as a pixel size
rowHeaderWidth: '25px',
// set different widths for individual row headers
rowHeaderWidth: [25, 30, 55],

rowHeights

Can be set at: grid

Source code

core.rowHeights : number | Array<number> | string | Array<string> | Array<undefined> | function

The rowHeights option sets rows’ heights, in pixels.

A row renders at exactly the height you set. Content taller than the row is clipped, as in Excel, instead of stretching the row. A row can be shorter than the default row height, which is classic: 26px, main: 29px, horizon: 37px or whatever the used theme defines (based on the line height, vertical padding and cell borders). A row with no height of its own, or with a height of 0, keeps the default.

To set a minimum that content can grow past, use minRowHeights instead. You can set both options: rowHeights sets the rows it gives a height, and minRowHeights applies to the others.

You can set the rowHeights option to one of the following:

SettingDescriptionExample
A numberSet the same height for every rowrowHeights: 100
A stringSet the same height for every rowrowHeights: '100px'
An arraySet heights separately for each row,
by physical row index
rowHeights: [100, 120, undefined]
A functionSet row heights dynamically,
on each render, by physical row index
rowHeights(physicalRowIndex) { return physicalRowIndex * 10; }
undefinedUsed by the modifyRowHeight hook,
to detect row height changes
rowHeights: undefined

The array and the function address a row by its physical index, so a height stays with its row when rows are moved with the ManualRowMove plugin, sorted, filtered, trimmed, or collapsed (for example, by the NestedRows plugin). The physical index doesn’t change in any of those cases. A row that the NestedRows plugin moves by dragging or detaching takes a new physical index: an array entry follows the row, but a function is called with the new index. An array entry also stays with the row it was declared for when you insert or remove rows: a row inserted between others has no height of its own, a row added after the last one takes the next entry, and the array you passed is never changed. A function is called with the physical index the row has now. To declare the heights again, pass a new array to updateSettings(). Switching the option to or from an array, or passing a new array, clears the undo history, the way enabling a plugin does. colWidths addresses columns by the physical index too.

When the AutoRowSize plugin is enabled, rowHeights sets the minimum row height, so a row still grows to fit its content, and the clipping described above does not apply. The autoRowSize option alone decides this, not the state of the plugin: with autoRowSize set, rowHeights stays a minimum even when the plugin is not registered, or after you call disablePlugin() on it.

When AutoRowSize is disabled, a row resized by dragging keeps its height until the height is re-declared. Passing rowHeights or minRowHeights to updateSettings() re-declares the heights and discards the ones stored by the ManualRowResize plugin. To keep the stored heights, leave both options out of the call.

Passing manualRowResize as an array in the same call replaces the stored heights with that array rather than keeping them.

These cases never discard the stored heights:

  • A rowHeights function. It states no fixed height, so it is left alone.
  • A grid whose manualRowResize option is already a non-empty array. The plugin replays that array, so the stored heights stay.
  • The React, Angular and Vue wrappers, when the rowHeights prop did not change. An unchanged prop is not forwarded, so re-applying the same value resets nothing.

In each case, call ManualRowResize#clearManualSizes() followed by render().

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Example

// set every row's height to 100px
rowHeights: 100,
// set every row's height to 100px
rowHeights: '100px',
// set the first (by physical index) row's height to 100
// set the second (by physical index) row's height to 120
// set the third (by physical index) row's height to `undefined`
// set any other row's height to the default height value
rowHeights: [100, 120, undefined],
// set each row's height individually, using a function
rowHeights(physicalRowIndex) {
return physicalRowIndex * 10;
},

rowId

Can be set at: grid

Source code

core.rowId : string | function | boolean

The rowId option gives each row an id that stays with the row’s record when you sort, filter, move, trim, insert, or remove rows, and when you undo or redo any of those actions.

Read a row’s id with getRowId(), and find a row by its id with getVisualRowById() or getPhysicalRowById().

You can set the rowId option to one of the following:

SettingDescription
A stringThe property that holds the id in each row object (for example, 'id' or 'meta.id'), or the index of that value in each row array
A functionA function that receives the source row and returns its id
trueHandsontable generates the ids: a number for each row, never reused within the instance
falseNo row ids

For a string with a dot, a property named exactly as the string wins ({ 'meta.id': 'SKU-4821' }), as it does for a column’s data property. Otherwise, the dots read a nested property ({ meta: { id: 'SKU-4821' } }), even when dataDotNotation is false and a column with the same data shows nothing.

Keep the ids unique. If two rows share an id, the lookups return the row with the lower physical index.

Generated ids follow the physical rows. loadData() gives every row a new id, and updateData() keeps the ids of the rows that stay, by position. To keep ids across data loads, store them in the data and use a string or a function.

When the dataProvider option sets its own rowId, Handsontable reads row ids with dataProvider.rowId, and ignores the rowId option.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Since: 19.0.0
Example

// read the id from the `id` property of each row object
rowId: 'id',
// read the id with a function (return `null` while a row lacks the values, as an empty row does)
rowId: (row) => (row.country == null || row.code == null ? null : `${row.country}-${row.code}`),
// let Handsontable generate the ids
rowId: true,

sanitizer

Can be set at: grid

Source code

core.sanitizer : function

The sanitizer option configures the function used to sanitize HTML before it is written to the DOM. Sanitization is important when content comes from users or external sources to prevent XSS (e.g. script injection, event handlers).

By default (when no sanitizer is set), HTML is applied as-is (pass-through). You are responsible for XSS protection. Set a sanitizer when you need to allow rich content while stripping or neutralizing dangerous markup.

The sanitizer covers the HTML that Handsontable writes on your behalf:

Two surfaces are deliberately excluded, because both exist to render raw markup you supply: the html cell type, and allowHtml sources in autocomplete and dropdown cells. Sanitize that content yourself before passing it to the grid.

The function receives the raw HTML string and a second argument (source) naming the write surface ('header', 'password', 'contextMenu', 'selectEditor', 'dialog', 'notification', 'CopyPaste.paste', 'CopyPaste.paste.sourceData'), so you can apply different rules per source. It must return a string that is safe to assign to innerHTML, or a TrustedHTML when the page enforces Trusted Types. Handsontable passes the returned value to the DOM unchanged, so a TrustedHTML keeps its trust.

In TypeScript, annotate that parameter with the exported SanitizerContext type (see TypeScript types) to get editor completion on the values above.

'CopyPaste.paste.sourceData' carries Handsontable’s own clipboard payload, the one that lets an object-valued cell survive a copy between grids. It is parsed into an inert document, so returning it unchanged does not expose you to a crafted clipboard, and doing so is what keeps parsePastedValue working under a sanitizer that escapes HTML rather than stripping it.

This option is only respected when set in the table settings. It does not work when defined per column or per cell (e.g. in columns or cell meta).

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Since: 17.0.0
Example

// Allowlist-based sanitization using a custom library
sanitizer: (content, source) => myLibrary.sanitize(content),

Example

// Maximum safety: strip all tags and escape output (no rich HTML)
sanitizer: (content, source) => {
const tpl = document.createElement('template');
tpl.innerHTML = content;
const text = tpl.content.textContent ?? '';
return text
.replace(/&/g, '&amp;')
.replace(/</g, '&lt;')
.replace(/>/g, '&gt;')
.replace(/"/g, '&quot;')
.replace(/'/g, '&#39;');
},

Example

// Trusted Types: wrap sanitization in a policy so the sink accepts the result. Handsontable
// needs no policy of its own - it builds its own markup as DOM nodes - so the directive only
// has to name yours (e.g. trusted-types my-app-sanitizer). Name it after your application:
// `createPolicy` throws when the same name is created twice.
const policy = window.trustedTypes?.createPolicy('my-app-sanitizer', {
createHTML: (input) => myLibrary.sanitize(input),
});
sanitizer: (content, source) =>
policy ? policy.createHTML(content) : myLibrary.sanitize(content),

searchInput

Can be set at: grid columns cells cell

Source code

core.searchInput : boolean

The searchInput option configures whether the multiSelect editor’s search input is visible.

Default: true
Since: 17.0.0
Example

columns: [{
type: 'multiselect',
// hide the `multiSelect` editor's search input
searchInput: false,
}],

selectionHandles

Can be set at: grid

Source code

core.selectionHandles : boolean

The selectionHandles option enables draggable handles on the edges of a selection. When enabled, hovering over a selected range shows a pill-shaped handle at the midpoint of each edge; dragging a handle resizes that edge of the selection. This adjusts the selected area only – it does not move, fill, or change any cell data.

Handles are shown on desktop only and are hidden on any edge that is flush with the grid boundary — or that lands on a frozen-pane line (fixedRowsTop, fixedRowsBottom, fixedColumnsStart, fixedColumnsEnd). The option has no effect when selectionMode is 'single'.

This option can only be set at the grid level.

Default: false
Since: 18.1.0
Example

// enable draggable selection-edge handles
selectionHandles: true,

selectionMode

Can be set at: grid

Source code

core.selectionMode : string

The selectionMode option configures how selection works.

You can set the selectionMode option to one of the following:

SettingDescription
'single'Allow the user to select only one cell at a time.
'range'Allow the user to select one range of cells at a time.
'multiple'Allow the user to select multiple ranges of cells at a time.

When selectionMode is set to 'single', copying with fragmentSelection enabled is limited to a single cell.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: “multiple”
Example

// you can only select one cell at at a time
selectionMode: 'single',
// you can select one range of cells at a time
selectionMode: 'range',
// you can select multiple ranges of cells at a time
selectionMode: 'multiple',

selectOptions

Can be set at: grid columns cells cell

Source code

core.selectOptions : Array<string> | object | function

The selectOptions option configures options that the end user can choose from in select cells.

You can set the selectOptions option to one of the following:

SettingDescription
An array of stringsEach string is one option’s value and label
An object with key-string pairs- Each key is one option’s value
- The key’s string is that option’s label
A functionA function that returns an object with key-string pairs

Read more:

Default: undefined
Example

columns: [
{
// set the `type` of each cell in this column to `select`
type: 'select',
// set the first option's value and label to `A`
// set the second option's value and label to `B`
// set the third option's value and label to `C`
selectOptions: ['A', 'B', 'C'],
},
{
// set the `type` of each cell in this column to `select`
type: 'select',
selectOptions: {
// set the first option's value to `value1` and label to `Label 1`
value1: 'Label 1',
// set the second option's value to `value2` and label to `Label 2`
value2: 'Label 2',
// set the third option's value to `value3` and label to `Label 3`
value3: 'Label 3',
},
},
{
// set the `type` of each cell in this column to `select`
type: 'select',
// set `selectOption` to a function that returns available options as an object
selectOptions(visualRow, visualColumn, prop) {
return {
value1: 'Label 1',
value2: 'Label 2',
value3: 'Label 3',
};
},
],

skipColumnOnPaste

Can be set at: grid columns cells cell

Source code

core.skipColumnOnPaste : boolean

The skipColumnOnPaste option determines whether you can paste data into a given column.

You can only apply the skipColumnOnPaste option to an entire column, using the columns option. This option is not supported for the global table level settings.

You can set the skipColumnOnPaste option to one of the following:

SettingDescription
false (default)Enable pasting data into this column
true- Disable pasting data into this column
- On pasting, paste data into the next column to the right

Read more:

Default: false
Example

columns: [
{
// disable pasting data into this column
skipColumnOnPaste: true
}
],

skipRowOnPaste

Can be set at: grid columns cells cell

Source code

core.skipRowOnPaste : boolean

The skipRowOnPaste option determines whether you can paste data into a given row.

You can only apply the skipRowOnPaste option to an entire row, using the cells option. This option is not supported for the global table level settings.

You can set the skipRowOnPaste option to one of the following:

SettingDescription
false (default)Enable pasting data into this row
true- Disable pasting data into this row
- On pasting, paste data into the row below

Read more:

Default: false
Example

cells(row, column) {
const cellProperties = {};
// disable pasting data into row 1
if (row === 1) {
cellProperties.skipRowOnPaste = true;
}
return cellProperties;
}

sortByRelevance

Can be set at: grid columns cells cell

Source code

core.sortByRelevance : boolean

The sortByRelevance option configures whether autocomplete cells’ lists are sorted in the same order as provided in the source option.

You can set the sortByRelevance option to one of the following:

SettingDescription
true (default)Sort options in the same order as provided in the source option
falseSort options alphabetically

Read more:

Default: true
Example

columns: [{
// set the `type` of each cell in this column to `autocomplete`
type: 'autocomplete',
// set options available in every `autocomplete` cell of this column
source: ['D', 'C', 'B', 'A'],
// sort the `autocomplete` option in this order: D, C, B, A
sortByRelevance: true
}],

source

Can be set at: grid columns cells cell

Source code

core.source : Array | function

The source option sets options available in autocomplete and dropdown cells.

You can set the source option to one of the following:

  • An array of string values
  • An array of objects with key and value properties
  • A function

Note: When defining the source option as an array of objects with key and value properties, the data format for that cell needs to be an object with key and value properties as well.

Note: The value property can be an object. Use the sourceLabel option to tell the cell which text to display for it. The cell then stores the whole source entry, so the object reaches your data unchanged.

Note: When source is a function, Handsontable ignores a response that arrives after the editor closed - including a close you may not notice, such as scrolling the edited cell out of view - and it ignores a response that a newer query has superseded, which happens as you type. Call the callback whenever the request completes, even late.

Read more:

Default: undefined
Example

// set `source` to an array of string values
columns: [{
// set the `type` of each cell in this column to `autocomplete`
type: 'autocomplete',
// set options available in every `autocomplete` cell of this column
source: ['A', 'B', 'C', 'D']
}],
// set `source` to an array of objects with `key` and `value` properties
columns: [{
// set the `type` of each cell in this column to `autocomplete`
type: 'autocomplete',
// set options available in every `autocomplete` cell of this column
source: [{
key: 'A',
value: 'Label A'
}, {
key: 'B',
value: 'Label B'
}]
}],
// set `source` to a function
columns: [{
// set the `type` of each cell in this column to `autocomplete`
type: 'autocomplete',
// for every `autocomplete` cell in this column, fetch data from an external source
source(query, callback) {
fetch('https://example.com/query?q=' + query, function(response) {
callback(response.items);
})
}
}],

sourceDataValidator

Can be set at: grid columns cells cell

Source code

core.sourceDataValidator : function

The sourceDataValidator option sets a function that validates values when they are written to the source data layer. Validation runs on table initialization and when calling loadData, updateData, or setSourceDataAtCell. It does not run for the setData* family of methods.

Return true from the function to mark the value as valid, or false to mark it invalid. When a value is invalid and allowInvalid is false, it is replaced with null in the source (on initialization and when calling loadData or updateData). When allowInvalid is true, invalid values are kept; a warning is still logged when the validator returns false. An exception: setSourceDataAtCell - when the validator returns false, the write is skipped and the cell is not nullified; the previous value in the source remains unchanged. Use allowEmpty to treat null, undefined, or '' as valid when appropriate.

Optionally set sourceDataWarningMessage to customize the message logged for invalid values.

Limitation: source-data validation only sees a sourceDataValidator (and a validating cell type) that you define in the global settings, the columns option, the cell option, or with setCellMeta(). It does not run the cells function or the beforeGetCellMeta / afterGetCellMeta hooks, so a validator that you add only through those is skipped. Define the validator in one of the supported places to validate the source data.

Default: undefined
Since: 17.0.0
Example

sourceDataWarningMessage: 'The source data is invalid.',
sourceDataValidator: (value, cellMeta) => {
if (cellMeta.allowEmpty && value == null) {
return true;
}
if (typeof value === 'string') {
return true;
}
return false;
}

sourceDataWarningMessage

Can be set at: grid columns cells cell

Source code

core.sourceDataWarningMessage : string

The sourceDataWarningMessage option sets the message used when a value fails sourceDataValidator. When not set, no message is logged.

Default: undefined
Since: 17.0.0
Example

sourceDataWarningMessage: 'The source data is invalid.',

sourceLabel

Can be set at: grid columns cells cell

Source code

core.sourceLabel : string | function

The sourceLabel option sets the text that autocomplete and dropdown cells display for a source entry whose value is an object.

You can set the sourceLabel option to one of the following:

SettingDescription
undefined(Default) Display the value as it is
A stringDisplay the property of the value object at that path, for example 'name', 'address.city', or 'aliases.0'
A functionDisplay what the function returns. The function receives the value object

The label is used everywhere the cell shows text: in the cell, in the list of options, when you type to filter the options, and when you paste. The cell itself stores the whole source entry, including the value object. To change an entry, replace it in source and in the cells that hold it, instead of changing the object in place: depending on how the value was written, a cell holds either the source entry itself or a plain-object copy of it.

Each entry needs a unique label: if two entries display the same label, picking or pasting that label stores the first of them. An entry whose label resolves to nothing, for example a missing property, isn’t listed as an option.

The sourceLabel option affects only a value that is an object. A string or number value is displayed as it is. With sortByRelevance set to false, a source that holds an object value is sorted by the labels.

Read more:

Default: undefined
Since: 19.0.0
Example

columns: [{
type: 'dropdown',
source: [
{ key: 'US', value: { name: 'United States', currency: 'USD' } },
{ key: 'PL', value: { name: 'Poland', currency: 'PLN' } },
],
// display the `name` property of each `value` object
sourceLabel: 'name',
}],
columns: [{
type: 'dropdown',
source: [
{ key: 'US', value: { name: 'United States', currency: 'USD' } },
{ key: 'PL', value: { name: 'Poland', currency: 'PLN' } },
],
// build the label from several properties
sourceLabel: value => `${value.name} (${value.currency})`,
}],

sourceSortFunction

Can be set at: grid columns cells cell

Source code

core.sourceSortFunction : function

The sourceSortFunction option sets a function to sort the options available in multiSelect-typed cells.

Default: undefined
Since: 17.0.0
Example

columns: [{
// set the `type` of each cell in this column to `multiSelect`
type: 'multiselect',
// set options available in every `multiSelect` cell of this column
source: ['A', 'B', 'C', 'D'],
// sort the `multiSelect` options in this order: D, C, B, A
sourceSortFunction: (entries) => {
return entries.sort((a, b) => b.localeCompare(a));
}
}],

startCols

Can be set at: grid

Source code

core.startCols : number

If the data option is not set, the startCols option sets the initial number of empty columns.

The startCols option works only in Handsontable’s constructor and only when data is not provided.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: 5
Example

// start with 15 empty columns
startCols: 15,

startRows

Can be set at: grid

Source code

core.startRows : number

If the data option is not set, the startRows option sets the initial number of empty rows.

The startRows option works only in Handsontable’s constructor and only when data is not provided.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: 5
Example

// start with 15 empty rows
startRows: 15,

stretchH

Can be set at: grid

Source code

core.stretchH : string

The stretchH option determines what happens when the declared grid width is different from the calculated sum of all column widths.

You can set the stretchH option to one of the following:

SettingDescription
'none' (default)Don’t fit the grid to the container (disable column stretching)
'last'Fit the grid to the container, by stretching only the last column
'all'Fit the grid to the container, by stretching all columns evenly

Read more:

When used with manualColumnResize, columns that have a width set through pre-defined manual sizes are excluded from stretching. Only the remaining columns are stretched to fill the container.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: “none”
Example

// fit the grid to the container
// by stretching all columns evenly
stretchH: 'all',

strict

Can be set at: grid columns cells cell

Source code

core.strict : boolean

The strict option configures the behavior of autocomplete cells.

You can set the strict option to one of the following:

SettingModeDescription
trueStrict modeThe end user:
- Can only choose one of suggested values
- Can’t enter a custom value
falseFlexible modeThe end user:
- Can choose one of suggested values
- Can enter a custom value

The dropdown cell type always runs in strict mode, so it ignores strict: false.

This option can be set at any level of the cascading configuration: the grid level, the columns level, the cells level, and the cell level.

Read more:

Default: undefined
Example

columns: [
{
// set the `type` of each cell in this column to `autocomplete`
type: 'autocomplete',
// set options available in every `autocomplete` cell of this column
source: ['A', 'B', 'C'],
// values entered must match `A`, `B`, or `C`
strict: true
},
],

tableClassName

Can be set at: grid

Source code

core.tableClassName : string | Array<string>

The tableClassName option lets you add CSS class names to every Handsontable instance inside the container element.

You can set the tableClassName option to one of the following:

SettingDescription
A stringAdd a single CSS class name to every Handsontable instance inside the container element
An array of stringsAdd multiple CSS class names to every Handsontable instance inside the container element

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Example

// add a `your-class-name` CSS class name
// to every Handsontable instance inside the `container` element
tableClassName: 'your-class-name',
// add `first-class-name` and `second-class-name` CSS class names
// to every Handsontable instance inside the `container` element
tableClassName: ['first-class-name', 'second-class-name'],

tabMoves

Can be set at: grid

Source code

core.tabMoves : object | function

The tabMoves option configures the action of the Tab key.

You can set the tabMoves option to an object with the following properties (or to a function that returns such an object):

PropertyTypeDescription
rowNumber- On pressing Tab, move selection row rows down
- On pressing Shift+Tab, move selection row rows up
colNumber- On pressing Tab, move selection col columns right
- On pressing Shift+Tab, move selection col columns left

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: {row: 0, col: 1}
Example

// on pressing Tab, move selection 2 rows down and 2 columns right
// on pressing Shift+Tab, move selection 2 rows up and 2 columns left
tabMoves: {row: 2, col: 2},
// the same setting, as a function
// `event` is a DOM Event object received on pressing Tab
// you can use it to check whether the user pressed Tab or Shift+Tab
tabMoves(event) {
return {row: 2, col: 2};
},

tabNavigation

Can be set at: grid

Source code

core.tabNavigation : boolean

The tabNavigation option decides what the Tab and Shift+Tab keys do while the grid has the focus.

SettingDescription
true (default)The grid captures Tab and Shift+Tab and moves the selection between cells, so the grid is a set of tab stops (the spreadsheet mode).
falseThe grid returns both keys to the browser, so Tab leaves the grid and the grid is one tab stop in the page’s tab sequence (the data grid mode).

Pair tabNavigation: false with navigableHeaders: true for the data grid mode described in the Accessibility guide.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: true
Since: 14.0.0
Example

// Tab leaves the grid: one tab stop, the arrow keys move between cells
tabNavigation: false,
// default behavior: Tab and Shift+Tab move between cells
tabNavigation: true,

textEllipsis

Can be set at: grid columns cells cell

Source code

core.textEllipsis : boolean | number

The textEllipsis option configures whether the text content in the cells should be truncated with an ellipsis (three dots), either on one line or after a number of lines. Support for a number was added in 19.0.0.

You can set the textEllipsis option to one of the following:

SettingDescription
false (default)Don’t truncate text content with an ellipsis
trueKeep text content on one line and truncate it with an ellipsis
A number, 2 or greaterWrap text content and truncate it with an ellipsis after that many lines

A number of 1 works like true. A number that is not a positive integer (such as 0, -1, or 2.5) works like false.

A number works in cells whose renderer writes plain text through the built-in textRenderer. That covers the text, numeric, date, time, intl-date, intl-datetime, intl-time, select, autocomplete, dropdown, and handsontable cell types, and any custom renderer that calls textRenderer. Renderers that draw their own markup, such as the html and password renderers (and the autocomplete renderer with allowHtml: true), can’t clamp: for them a number works like true, and the text stays on one line with an ellipsis.

Truncation only changes how the text looks. The full text stays in the cell’s DOM, in getData(), and in copied data. The grid shows no tooltip with the full text.

The wordWrap option set to false takes precedence over a number: the text stays on one line and ends with an ellipsis.

A row grows up to the given number of lines, so the clamped text stays readable.

Default: false
Since: 16.0.0
Example

columns: [
{
// truncate text content with an ellipsis
textEllipsis: true,
},
{
// wrap text content and truncate it with an ellipsis after 3 lines
textEllipsis: 3,
},
{
// don't truncate text content with an ellipsis
textEllipsis: false,
}
],

textExtractor

Can be set at: grid

Source code

core.textExtractor : boolean | function

The textExtractor option configures how grid content is turned into plain text for consumers that do not write to the DOM, such as an exported file.

It is the counterpart to sanitizer. Read the pair as one idea:

  • sanitizer decides how content is written to the screen (HTML in, HTML out).
  • textExtractor decides how the same content becomes text everywhere else (HTML in, text out).

The option exists because a header setting is also its display string. A header of '<b>Total</b>' renders as Total in the grid, and without this option the same header reaches a CSV file as the literal <b>Total</b>, so the file disagrees with the screen. Copying a header row to the clipboard carries the same markup.

By default (when no extractor is set) content is exported exactly as it is stored, which is the behavior of every earlier version.

Set true to use the built-in extraction, which returns the text the grid displays:

textExtractor: true,

false behaves the same as leaving the option out, so you can pass a flag straight through without a ternary.

Set a function for full control. It receives the content and the consumer surface, so you can apply different rules per surface. In TypeScript, annotate the second parameter with the exported TextExtractorContext type (see TypeScript types) to get editor completion on the values below.

The surfaces that pass a context today are 'ExportFile.columnHeader', 'ExportFile.rowHeader', 'CopyPaste.columnHeader', 'A11y.columnLabel' (a column header read for a cell editor’s accessible name or a sort announcement, when the header is not rendered), and 'A11y.rowLabel' (a custom row header read for a cell editor’s accessible name). A plugin may pass a surface of its own, so treat the list as open.

The built-in extraction runs a configured sanitizer first, under the 'header' surface, then reduces the result to text. That order matters: a sanitizer may remove content rather than only unwrap it, so extracting text from the unsanitized value would put content in a file that the grid never displayed. Parsing is also what turns entities back into the characters they stand for, so a header shown as Tom & Jerry is written to a file as Tom & Jerry rather than Tom &amp; Jerry.

Values that are not strings are never passed to the extractor. A numeric header stays a number, so a spreadsheet still reads it as one.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Since: 19.0.0
Example

// Export headers as the text the grid displays
textExtractor: true,

Example

// Keep row headers as they are, reduce column headers to text
textExtractor: (content, source) => {
if (source === 'ExportFile.rowHeader') {
return content;
}
const tpl = document.createElement('template');
tpl.innerHTML = content;
return tpl.content.textContent ?? '';
},

theme

Can be set at: grid

Source code

core.theme : ThemeBuilder | object | string | undefined

The theme option configures the visual theme for your Handsontable instance.

You can set the theme option to one of the following:

SettingDescription
undefined (default)Don’t apply any theme and use the default main theme
A string (e.g., 'ht-theme-horizon')Apply a registered theme by name (required to import CSS file)
A plain theme config objectApply a theme with default settings (import and pass the config, e.g. horizonTheme)
A ThemeBuilder objectApply a theme with runtime configuration (recommended)

When using a ThemeBuilder object, you can configure the theme at runtime using these methods:

MethodDescription
setColorScheme(mode)Sets the color scheme: 'light', 'dark', or 'auto' (default: 'auto')
setDensityType(type)Sets the row density: 'compact', 'default', or 'comfortable' (default: 'default')
params(paramsObject)Sets custom theme parameters e.g. icons, colors, tokens

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Since: 17.0.0
Example

// Enable a theme by class name (requires loading the theme CSS)
theme: 'ht-theme-horizon',

Example

// Pass a plain theme config object
import { horizonTheme } from 'handsontable/themes';
const hot = new Handsontable(container, {
theme: horizonTheme,
});

Example

// Pass a ThemeBuilder object (for customization before initialization)
import { horizonTheme, registerTheme } from 'handsontable/themes';
const theme = registerTheme(horizonTheme)
.setColorScheme('dark')
.setDensityType('compact')
.params({
tokens: {
fontSize: '14px',
iconSize: 'size_5',
borderColor: ['colors.palette.100', 'colors.palette.800'],
},
});
const hot = new Handsontable(container, {
theme,
});

themeName

Can be set at: grid

Source code

core.themeName : string | undefined

The themeName option allows enabling a theme by that name.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: undefined
Since: 15.0.0
Example

themeName: 'ht-theme-name',

timeFormat

Can be set at: grid columns cells cell

Source code

core.timeFormat : object

Configures the time format for intl-time cells using an Intl.DateTimeFormat options object. The locale is controlled separately via the locale option.

Style shortcuts:

PropertyPossible valuesDescription
timeStyle'full', 'long', 'medium', 'short'Time formatting style (expands to hour, minute, second, timeZoneName)

Time component options:

PropertyPossible valuesDescription
hour'numeric', '2-digit'Representation of the hour
minute'numeric', '2-digit'Representation of the minute
second'numeric', '2-digit'Representation of the second
fractionalSecondDigits1, 2, 3Fraction-of-second digits
dayPeriod'narrow', 'short', 'long'Day period (e.g. “am”, “noon”)
timeZoneName'long', 'short', 'shortOffset', 'longOffset', 'shortGeneric', 'longGeneric'Time zone display

Locale and other options:

PropertyPossible valuesDescription
localeMatcher'best fit' (default), 'lookup'Locale matching algorithm
timeZoneIANA time zone (e.g. 'UTC', 'America/New_York')Time zone for formatting
hour12true, falseUse 12-hour vs 24-hour time
hourCycle'h11', 'h12', 'h23', 'h24'Hour cycle
formatMatcher'basic', 'best fit' (default)Format matching algorithm

For complete reference, see MDN: Intl.DateTimeFormat.

Read more:

Default: { hour: ‘2-digit’, minute: ‘2-digit’ }
Example

columns: [
{
type: 'intl-time',
locale: 'en-US',
timeFormat: {
timeStyle: 'medium'
}
}
]

title

Can be set at: columns

Source code

core.title : string

The title option configures column header names.

You can set the title option to a string.

To set the labels of all column headers at once, use the colHeaders option.

Read more:

This option can only be set at the columns level. It has no effect when set at the grid level, or in the cells or cell options.

Default: undefined
Example

columns: [
{
// set the first column header name to `First name`
title: 'First name',
type: 'text',
},
{
// set the second column header name to `Last name`
title: 'Last name',
type: 'text',
}
],

trimDropdown

Can be set at: grid columns cells cell

Source code

core.trimDropdown : boolean

The trimDropdown option configures the width of the autocomplete and dropdown lists.

When set to true (default), the list is trimmed to match the width of the edited cell, which can truncate long option labels. When set to false, the list expands to fit its longest option – it can grow wider than the cell, but never narrower.

You can set the trimDropdown option to one of the following:

SettingDescription
true (default)Make the dropdown/autocomplete list’s width the same as the edited cell’s width
falseExpand the list to its content, but keep it at least as wide as the edited cell

This option can be set at any level of the cascading configuration: the grid level, the columns level, the cells level, and the cell level.

Read more:

Default: true
Example

columns: [
{
type: 'autocomplete',
// for each cell of this column
// make the `autocomplete` list's width the same as the edited cell's width
trimDropdown: true,
},
{
type: 'dropdown',
// for each cell of this column
// scale the `dropdown` list's width to the list's content
trimDropdown: false,
}
],

trimWhitespace

Can be set at: grid columns cells cell

Source code

core.trimWhitespace : boolean

The trimWhitespace option configures automatic whitespace removal. This option affects the cell renderer and the cell editor.

You can set the trimWhitespace option to one of the following:

SettingDescription
true (default)Remove whitespace at the beginning and at the end of each cell
falseDon’t remove whitespace

Default: true
Example

columns: [
{
// don't remove whitespace
// from any cell of this column
trimWhitespace: false
}
]

type

Can be set at: grid columns cells cell

Source code

core.type : string

The type option lets you set the renderer, editor, and validator options all at once, by selecting a cell type.

You can set the type option to one of the following:

Cell typeRenderer, editor & validator
A custom cell typeRenderer: your custom cell renderer
Editor: your custom cell editor
Validator: your custom cell validator
'autocomplete'Renderer: AutocompleteRenderer
Editor: AutocompleteEditor
Validator: AutocompleteValidator
'checkbox'Renderer: CheckboxRenderer
Editor: CheckboxEditor
Validator: -
'date'Renderer: DateRenderer
Editor: DateEditor
Validator: DateValidator
'intl-date'Renderer: IntlDateRenderer
Editor: IntlDateEditor
Validator: IntlDateValidator
'dropdown'Renderer: DropdownRenderer
Editor: DropdownEditor
Validator: DropdownValidator
'handsontable'Renderer: AutocompleteRenderer
Editor: HandsontableEditor
Validator: -
'numeric'Renderer: NumericRenderer
Editor: NumericEditor
Validator: NumericValidator
'password'Renderer: PasswordRenderer
Editor: PasswordEditor
Validator: -
'text'Renderer: TextRenderer
Editor: TextEditor
Validator: -
'time’Renderer: TimeRenderer
Editor: TimeEditor
Validator: TimeValidator
'intl-time'Renderer: IntlTimeRenderer
Editor: IntlTimeEditor
Validator: IntlTimeValidator
'intl-datetime'Renderer: IntlDatetimeRenderer
Editor: IntlDatetimeEditor
Validator: IntlDatetimeValidator

A grid-level type changed with updateSettings() applies the new type’s editor, renderer, and validator. A grid-level editor, renderer, or validator set earlier, or in the same call, keeps winning over the type.

Read more:

Default: “text”
Example

// set the `numeric` cell type for each cell of the entire grid
type: `'numeric'`,
// apply the `type` option to individual columns
columns: [
{
// set the `autocomplete` cell type for each cell of this column
type: 'autocomplete'
},
{
// set the `myCustomCellType` cell type for each cell of this column
type: 'myCustomCellType'
}
]

uncheckedTemplate

Can be set at: grid columns cells cell

Source code

core.uncheckedTemplate : boolean | string | number

The uncheckedTemplate option lets you configure what value an unchecked checkbox cell has.

You can set the uncheckedTemplate option to one of the following:

SettingDescription
false (default)If a checkbox cell is unchecked,
the getDataAtCell method for this cell returns false
A stringIf a checkbox cell is unchecked,
the getDataAtCell method for this cell returns a string of your choice

This option can be set at any level of the cascading configuration: the grid level, the columns level, the cells level, and the cell level.

Read more:

Default: false
Example

columns: [
{
// set the `type` of each cell in this column to `checkbox`
// when unchecked, the cell's value is `false`
// when checked, the cell's value is `true`
type: 'checkbox',
},
{
// set the `type` of each cell in this column to `checkbox`
// when unchecked, the cell's value is `'No'`
// when checked, the cell's value is `'Yes'`
type: 'checkbox',
uncheckedTemplate: 'No'
checkedTemplate: 'Yes',
}
],

validator

Can be set at: grid columns cells cell

Source code

core.validator : function | RegExp | string

The validator option sets a cell validator for a cell.

You can set the validator option to one of the following:

SettingDescription
A stringA cell validator alias
A functionYour custom cell validator function
A regular expressionA regular expression used for cell validation

This option can be set at any level of the cascading configuration: the grid level, the columns level, the cells level, and the cell level.

By setting the validator option to a string, you can use one of the following cell validator aliases:

AliasCell validator function
A custom aliasYour custom cell validator
'autocomplete'AutocompleteValidator
'checkbox'CheckboxValidator (opt-in; the checkbox cell type doesn’t apply it)
'date'DateValidator
'intl-date'IntlDateValidator
'dropdown'DropdownValidator
'numeric'NumericValidator
'time'TimeValidator
'intl-time'IntlTimeValidator

To set the editor, renderer, and validator options all at once, use the type option.

Read more:

Default: undefined
Example

columns: [
{
// use a built-in `numeric` cell validator
validator: 'numeric'
},
{
// validate against a regular expression
validator: /^[0-9]$/
},
{
// add a custom cell validator function
validator(value, callback) {
callback(value >= 0 && value <= 100);
}
},
],

valueFormatter

Can be set at: grid columns cells cell

Source code

core.valueFormatter : function

The valueFormatter option sets a custom function for formatting cell values before display.

Unlike the renderer option, which is responsible for the complete cell rendering process (DOM structure, performance-optimized content insertion via innerText/innerHTML, a11y attributes, applying styles from className, readOnlyCellClassName, textEllipsis, and other options), the valueFormatter focuses solely on transforming the cell’s value.

The valueFormatter function is called by the rendering engine right before the actual renderer function is called. Separating the value formatting from the renderer logic allows for more flexibility and reuse. This simplifies common formatting use cases where you only need to transform the displayed value (e.g., adding units, formatting dates, or applying custom text transformations).

When to use valueFormatter vs renderer:

Use caseRecommended option
Transform displayed value (add prefix, units)valueFormatter
Custom date/number/text formattingvalueFormatter
Modify DOM structure (add icons, custom elements)renderer

The function receives the raw value and cell properties, and should return the formatted value to be displayed. The formatting can be applied to a single cell, column, or the entire grid.

Function signature:

valueFormatter(value, cellProperties) => formattedValue
ParameterTypeDescription
value*The raw cell value
cellPropertiesobjectThe cell’s meta object (see Core#getCellMeta)
Returns*The formatted value to display

Read more:

Default: undefined
Since: 17.0.0
Example

// add a currency symbol to numeric values
valueFormatter(value, cellProperties) {
if (value === null || value === undefined) {
return '';
}
return `$${value}`;
}
// format dates in a custom format
valueFormatter(value, cellProperties) {
if (!value) {
return '';
}
const date = new Date(value);
return date.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' });
}
// apply valueFormatter to individual columns
columns: [
{
// add "kg" suffix to weight values
valueFormatter(value) {
return value ? `${value} kg` : '';
}
},
{
// format percentages
valueFormatter(value) {
return value !== null ? `${(value * 100).toFixed(1)}%` : '';
}
}
]

valueGetter

Can be set at: grid columns cells cell

Source code

core.valueGetter : function

The valueGetter option configures a function that defines what value will be used when displaying the cell content. It can be used to modify the value of a cell before it is displayed (for example, for object-based data).

Default: undefined
Since: 16.1.0
Example

// use the `label` property of the value object with a fallback to the value itself
valueGetter: (value, row, column, cellMeta) => {
return value?.label ?? value;
}
ParamTypeDescription
value*The value to be displayed in the cell.
rownumberThe visual row index of the cell.
columnnumberThe visual column index of the cell.
cellMetaobjectThe cell meta object.

valueParser

Can be set at: grid columns cells cell

Source code

core.valueParser : function

The valueParser option sets a custom function for converting editor output into the source data format.

Unlike valueFormatter, which formats values for display, valueParser runs only when a value comes from the cell editor - after the user finishes editing. It maps whatever the editor returns (e.g. a localized date string, a formatted number) into the canonical shape stored in the data source (e.g. ISO date string, raw number).

When to use valueParser vs valueFormatter:

Use caseOption
Display: raw value -> shown textvalueFormatter
Edit: editor value -> source datavalueParser

Function signature:

valueParser(value, cellProperties) => sourceValue
ParameterTypeDescription
value*The value produced by the editor
cellPropertiesobjectThe cell’s meta object (see Core#getCellMeta)
Returns*The value to store in the source data

Read more:

Default: undefined
Since: 17.0.0
Example

// parse editor string to ISO date (e.g. intl-date: display format => source format)
valueParser(value, cellProperties) {
if (value == null || value === '') {
return null;
}
const date = new Date(value);
return Number.isNaN(date.getTime()) ? value : date.toISOString().slice(0, 10);
}
// parse formatted number string to number
valueParser(value, cellProperties) {
if (value == null || value === '') {
return null;
}
const num = Number(value.replace(/[^\d.-]/g, ''));
return Number.isNaN(num) ? value : num;
}
// apply valueParser per column
columns: [
{ data: 'date', valueParser: (value) => value ? new Date(value).toISOString().slice(0, 10) : null },
{ data: 'amount', valueParser: (value) => value != null ? Number(value) : null }
]

valueSetter

Can be set at: grid columns cells cell

Source code

core.valueSetter : function

The valueSetter option configures a function that defines what value will be used when setting the cell content. It can be used to modify the value of a cell before it is saved (for example, for object-based data).

setSourceDataAtCell() runs the valueSetter too. When you address the cell by a property name, the grid reads the option from the global settings, the columns option, or the cell option. It does not run the cells function or the beforeGetCellMeta and afterGetCellMeta hooks.

Default: undefined
Since: 16.1.0
Example

// Modify the value of a cell before it is saved
valueSetter: (value, row, column, cellMeta) => {
return { id: value?.id ?? value, value: `${value?.value ?? value} at ${row}, ${column}` }
},
ParamTypeDescription
value*The value to be set to a cell.
rownumberThe visual row index of the cell.
columnnumberThe visual column index of the cell.
cellMetaobjectThe cell meta object.

viewportColumnRenderingOffset

Can be set at: grid

Source code

core.viewportColumnRenderingOffset : number | ‘auto’

The viewportColumnRenderingOffset option configures the number of columns to be rendered outside of the grid’s viewport.

You can set the viewportColumnRenderingOffset option to one of the following:

SettingDescription
auto (default)Use the offset calculated automatically by Handsontable
A numberSet the offset manually

With auto, the option works in a dynamic overscan mode: Handsontable renders 1 extra column on each side of the viewport and, while you scroll horizontally, extends the rendered area by up to 8 extra columns in the scroll direction, so consecutive scroll steps reuse the already-rendered columns instead of re-rendering them.

The scroll-direction overscan works only when Handsontable knows every column’s width up front and all columns share the same width: set colWidths to a single number. Features that measure or change individual column widths turn the overscan off for the column axis – for example, autoColumnSize (enabled by default), manualColumnResize, or hiddenColumns. The grid then keeps the static offset of 1 column on each side.

An explicit number switches the option to a manual mode: exactly that many extra columns render on both sides, with no scroll-direction overscan.

The viewportColumnRenderingOffset setting is ignored when renderAllColumns is set to true.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: ‘auto’
Example

// render 70 columns outside of the grid's viewport
viewportColumnRenderingOffset: 70,

viewportColumnRenderingThreshold

Can be set at: grid

Source code

core.viewportColumnRenderingThreshold : number | ‘auto’

The viewportColumnRenderingThreshold option configures what column number starting from the left or right (depends on the scroll direction) should trigger the rendering of columns outside of the grid’s viewport.

You can set the viewportColumnRenderingThreshold option to one of the following:

SettingDescription
autoTriggers rendering at half the offset defined by viewportColumnRenderingOffset option
A numberSets the offset manually (0 is a default)

The viewportColumnRenderingThreshold setting is ignored when renderAllColumn is set to true.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: 0
Since: 1.14.7
Example

// render 12 columns outside of the grid's viewport
viewportColumnRenderingOffset: 12,
// the columns outside of the viewport will be rendered when the user scrolls to the 8th column from/to
viewportColumnRenderingThreshold: 8,

viewportRowRenderingOffset

Can be set at: grid

Source code

core.viewportRowRenderingOffset : number | ‘auto’

The viewportRowRenderingOffset option configures the number of rows to be rendered outside of the grid’s viewport.

You can set the viewportRowRenderingOffset option to one of the following:

SettingDescription
auto (default)Use the offset calculated automatically by Handsontable
A numberSet the offset manually

With auto, the option works in a dynamic overscan mode: Handsontable renders 1 extra row on each side of the viewport and, while you scroll vertically, extends the rendered area by up to 4 extra rows in the scroll direction, so consecutive scroll steps reuse the already-rendered rows instead of re-rendering them.

The scroll-direction overscan works only when Handsontable knows every row’s height up front and all rows share the same height: keep the default rowHeights or set it to a single number. Features that measure or change individual row heights turn the overscan off for the row axis – for example, autoRowSize, manualRowResize, or hiddenRows. The grid then keeps the static offset of 1 row on each side.

An explicit number switches the option to a manual mode: exactly that many extra rows render on both sides, with no scroll-direction overscan.

The viewportRowRenderingOffset setting is ignored when renderAllRows is set to true.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: ‘auto’
Example

// render 70 rows outside of the grid's viewport
viewportRowRenderingOffset: 70,

viewportRowRenderingThreshold

Can be set at: grid

Source code

core.viewportRowRenderingThreshold : number | ‘auto’

The viewportRowRenderingThreshold option configures what row number starting from the top or bottom (depends on the scroll direction) should trigger the rendering of rows outside of the grid’s viewport.

You can set the viewportRowRenderingThreshold option to one of the following:

SettingDescription
autoTriggers rendering at half the offset defined by viewportRowRenderingOffset option
A numberSets the offset manually (0 is a default)

The viewportRowRenderingThreshold setting is ignored when renderAllRows is set to true.

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Default: 0
Since: 1.14.7
Example

// render 12 rows outside of the grid's viewport
viewportRowRenderingOffset: 12,
// the rows outside of the viewport will be rendered when the user scrolls to the 8th row from/to
viewportRowRenderingThreshold: 8,

visibleRows

Can be set at: grid columns cells cell

Source code

core.visibleRows : number

The visibleRows option sets the height of the autocomplete , dropdown and multiSelect-typed cells’ lists.

When the number of list options exceeds the visibleRows number, a scrollbar appears.

This option can be set at any level of the cascading configuration: the grid level, the columns level, the cells level, and the cell level.

Read more:

Default: 10
Example

columns: [
{
type: 'autocomplete',
// set the `autocomplete` list's height to 15 options
// for each cell of this column
visibleRows: 15,
},
{
type: 'dropdown',
// set the `dropdown` list's height to 5 options
// for each cell of this column
visibleRows: 5,
},
{
type: 'multiselect',
// set the `multiSelect` list's height to 5 options
// for each cell of this column
visibleRows: 5,
}
],

width

Can be set at: grid columns cells cell

Source code

core.width : number | ‘auto’ | string | function

The width option configures the width of your grid.

You can set the width option to one of the following:

SettingExample
A number of pixelswidth: 500
A string with a number of pixelswidth: '500', width: '500px'
A string with a CSS unitwidth: '50%', width: '75vw'
'auto'width: 'auto'
A function that returns a valid number or stringwidth() { return 500; }

Any other value the browser can read as a CSS length or expression ('20em', 'calc(100% - 40px)', 'var(--grid-width)') is passed through as written. A value the browser cannot read as a size ('abc', -100, true) is ignored, and so are these CSS keywords: 'inherit', 'initial', 'unset', 'revert', 'revert-layer', 'none', and 'normal', which do not set a size; 'min-content', 'max-content', and 'fit-content', which size the grid to its full content, so it cannot scroll inside its box; and 'stretch', '-webkit-fill-available', and '-moz-available', which fill the container but read as a fixed size. An ignored value leaves the grid’s width as it was, and a warning is printed once per grid and value.

With side panels docked in the start and end layout slots, the width includes them, and the grid fills the rest. When width is set, a function width runs again whenever a side panel mounts, unmounts, or changes its width.

With width: 'auto', Handsontable writes width: auto as an inline style on the root element. The grid then follows the width of its parent container, like a plain block element. Use this value when you want the grid to stay flexible horizontally while still setting an explicit height.

Passing null through updateSettings() restores the root element’s initial inline width. A height set through the option is left in place.

Read more:

Default: undefined
Example

// set the grid's width to 500px
width: 500,
// set the grid's width to 75vw
width: '75vw',
// let the grid follow its parent container's width
width: 'auto',
// set the grid's width to 500px, using a function
width() {
return 500;
},

wordWrap

Can be set at: grid columns cells cell

Source code

core.wordWrap : boolean

The wordWrap option configures whether content that exceeds a column’s width is wrapped or not.

You can set the wordWrap option to one of the following:

SettingDescription
true (default)If content exceeds the column’s width, wrap the content
falseDon’t wrap content

To style cells that don’t wrap content, use the noWordWrapClassName option.

This option can be set at any level of the cascading configuration: the grid level, the columns level, the cells level, and the cell level.

Read more:

Default: true
Example

// set column width for every column of the entire grid
colWidths: 100,
columns: [
{
// don't wrap content in this column
wordWrap: false,
},
{
// if content exceeds this column's width, wrap the content
wordWrap: true,
}
],

Members

afterValidatorAnswer

Source code

Core~afterValidatorAnswer

The functions _runAfterValidatorAnswer() queued while a validator answer ran. They run when the outermost answer has released its hold on the transaction of the change it answers (see leaveValidatorAnswer()).

columnIndexMapper

Source code

core.columnIndexMapper : IndexMapper

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

columnsSettingIndexes

Source code

Core~columnsSettingIndexes

Caches the index translation that getColHeader derives from the columns option when that option is a function: the source column indexes for which columns(index) returns a truthy settings object. Only the membership array is cached — titles are still read live from the columns function. Rebuilt when the function reference or the column count changes; cleared by updateSettings.

columnTracking

Source code

Core~columnTracking

Follows the physical columns a change that waits for its validator is made at, see core/columnTracker.ts.

dataWorkPhase

Source code

Core~dataWorkPhase

The step _applySettingsAndData() is in: 'configure' while it applies its settings, 'data' while it loads the data, 'meta' while it runs the meta phases it held back, and null outside the call.

displacedMetas

Source code

Core~displacedMetas

The stored cell metas of waiting validator calls whose record updateData() moved to another physical row while the meta stays stored at the row it was read from (updateData() keeps cell meta by physical row). The meta there belongs to the record now at that row, so the answer of such a call is written only to the meta at the record’s row (persistValidationResult()), never on the call’s own meta object. Each maps to the tracked record of its call. A meta leaves the map when the next validator call starts on it.

droppedChangesListeners

Source code

Core~droppedChangesListeners

The functions told about a change set that waited for its validators while loadData() replaced the data, and that is therefore never applied (see _addDroppedChangesListener()).

fontRefreshVisibilityObserver

Source code

Core~fontRefreshVisibilityObserver

Waits for a grid that was hidden when a web font loaded to be shown, so the re-measure skipped then runs (see refreshAfterFontsLoad()), or null when no re-measure is owed.

hadExternalDataSource

Source code

Core~hadExternalDataSource

What hasExternalDataSource answered at the end of the last settings update that sent dataProvider (or at init). A payload without dataProvider does not re-apply the plugin, so an object completed in place and followed by such an update has not been fetched yet, and recording that answer would skip the placeholder when the object is sent again. A settings update compares it with the answer for its own payload, because a dataProvider object completed in place answers true even before the payload merges, and only the earlier answer shows that the grid was not server-backed yet.

heldMetaPhases

Source code

Core~heldMetaPhases

The meta phases of the settings updates made while _applySettingsAndData() configures, run after its load in the order the updates were made.

initPassSettings

Source code

Core~initPassSettings

The settings core’s own init settings pass applies, while beforeInit runs, or null outside that window (see _replaceInitPassSettings()).

initReadyStepsRunning

Source code

Core~initReadyStepsRunning

true while the grid’s init pass runs the ready steps: before the init hook and the first render, with the renders they ask for held.

isAnsweringStaleValidation

Source code

Core~isAnsweringStaleValidation

Whether the postAfterValidate hook that runs now reports the answer of a validator call made before the last loadData(). Such an answer belongs to a change the load dropped, so a listener waiting for the answer to a later call (an editor’s wait) must not take it (see _isAnsweringStaleValidation()).

isBeingDestroyed

Source code

Core~isBeingDestroyed

Set when destroy() starts, so no ready step runs against a grid being torn down.

isDestroyed

Source code

core.isDestroyed : boolean

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

isRunningBeforeExecutionHook

Source code

Core~isRunningBeforeExecutionHook

Set while a beforeSuspendExecution or beforeResumeExecution listener runs. A suspend or resume the listener makes on this grid is part of the call that fired it, so it fires no execution hooks (see suspendExecution()).

isValidatingChange

Source code

Core~isValidatingChange

Whether validateChanges is calling validateCell right now, so the call counts as a change that waits for its validator. validateCell reads and clears it first, before any hook runs: a beforeValidate listener can make a validated change of its own, and its nested validateChanges would otherwise set or clear the flag the outer call reads.

lifecyclePassDepth

Source code

Core~lifecyclePassDepth

How many lifecycle passes are open: updateSettings() and _applySettingsAndData() calls, plugin lifecycle calls (enablePlugin(), updatePlugin(), disablePlugin()), and runs of the ready steps. The ready steps the plugins owe (BasePlugin#onGridReady()) wait while a pass is open, so a pass enables or updates every plugin before any of them runs its step.

pendingColumnLayoutCheck

Source code

Core~pendingColumnLayoutCheck

The column layout a data replacement made by updateSettings() must compare with the one it builds: the layout read before the payload merged, and whether columns added after the existing ones leave it as it was. null outside such a replacement.

pendingValidatorAnswers

Source code

Core~pendingValidatorAnswers

The number of validator calls made for a change (validateChanges) on the data the grid holds that have not answered yet. A call that throws, or answers more than once, is counted out once. A validator that never answers stays counted until the next loadData(), which starts a new count. Calls made by validateCells() and its siblings are not counted: they hold no change waiting to be written.

pluginRequirements

Source code

Core~pluginRequirements

The plugins other plugins need running (see _requirePlugin()).

readyStepsMayBeOwed

Source code

Core~readyStepsMayBeOwed

Whether a plugin may owe a ready step: set by every plugin lifecycle call (the only way a plugin comes to owe one), cleared once a run of the steps leaves none owed. A pass that ran no plugin call then skips the steps without looking at any plugin.

recordReader

Source code

Core~recordReader

What the record resolution reads from the grid, see core/waitingRecords.ts.

recordTracker

Source code

Core~recordTracker

Follows the records that something waits on (a change that waits for its validator, an editor that waits for the answer) by their physical rows, see core/recordTracker.ts.

rowIndexMapper

Source code

core.rowIndexMapper : IndexMapper

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

rowRevealers

Source code

Core~rowRevealers

The functions that can bring a row a hiding feature of their own keeps off screen into view (see _addRowRevealer()).

rowStateToClearAfterDataUpdate

Source code

Core~rowStateToClearAfterDataUpdate

Set while an updateData() call starts the column state over beside a sort or a filter, so they are cleared once the call has finished. Both name columns and change the rows, so the rows would keep a result the column state no longer describes.

runningValidatorLoadGeneration

Source code

Core~runningValidatorLoadGeneration

The validationLoadGeneration of the validator call whose validator runs now, or null outside one. A validator writes a correction through a nested setDataAtCell(..., 'xValidator'), and that correction belongs to the change the validator checks, so it takes this generation instead of the current one: when the change was dropped, its correction is dropped with it.

runningValidatorMeta

Source code

Core~runningValidatorMeta

The cell meta of the validator call whose validator runs now, or null outside one. A correction the validator writes to a null row (its record has no visual row) belongs to the change this call validates first.

settingsFilters

Source code

Core~settingsFilters

The functions that read every updateSettings() and _applySettingsAndData() payload, and the values _replaceInitPassSettings() hands the init pass, before they are applied, in the order they were added (see _addSettingsFilter()).

sideSlotsResizeObserver

Source code

Core~sideSlotsResizeObserver

Watches the elements registered in the start/end side slots (never the slots themselves: they span the full wrapper height at the same DOM depth as the top/bottom slots, so a render in slotsResizeObserver’s callback would resize them in the same frame and the browser would report a ResizeObserver loop). A panel that changes its width re-applies the width option, which includes the side panels.

slotsResizeObserver

Source code

Core~slotsResizeObserver

Watches the root wrapper’s edge slots for a height change (a bar that mounts after init, wraps after a locale switch, or grows a horizontal scrollbar once its width is clamped). A slot’s height feeds two things nothing else observes: the pixel height core writes on the root, and the height the engine reserves inside a scrollable ancestor (layoutReservedHeight).

stopWatchingFontLoads

Source code

Core~stopWatchingFontLoads

Stops watching the document’s web font loads (see refreshAfterFontsLoad()), or null before init started watching.

unansweredValidatorGenerations

Source code

Core~unansweredValidatorGenerations

The validationLoadGeneration of every validator call made for a change that has not answered yet, counted in _hasPendingValidation() or not (a call a beforeValidate load overtook is not counted, but its validator still runs and can still correct), by the cell it validates (property, then the tracked record of its row), oldest first. The record is tracked (recordTracker), so a sort, a move or an insert made while the call waits leaves the entry on the record the call validates. A validator that writes its correction later than its own synchronous run (after a timer or a request) is no longer inside runningValidatorLoadGeneration, so the correction finds the call it corrects here, by the record its row holds when it is written. An entry leaves when its call answers or throws; a load leaves the entries in place, because the calls they stand for are still out and their corrections still belong to the data they were made on.

validationLoadGeneration

Source code

Core~validationLoadGeneration

Advances on every loadData(). A validator call remembers the load it started on, and its answer is counted out only while that load is still the current one.

validatorAnswerDepth

Source code

Core~validatorAnswerDepth

How many validator answers run right now, nested: the microtask that calls a validator, and the callback the validator answers with (which runs inside that microtask when the validator answers synchronously).

waitingChangeRecords

Source code

Core~waitingChangeRecords

The record bookkeeping of every change a waiting set captured a record for, read by getPhysicalRowOfChange() in O(1). An entry lives from the capture until the set has dispatched its afterChange (or was dropped), when WaitingChangeRecords#release() takes it out, so a listener of beforeChangeRender or afterChange can still find the record of a change whose row reads null. Weak, so it holds no change alive.

waitingMetaStamps

Source code

Core~waitingMetaStamps

Keeps the row and visualRow of the stored cell meta of every validator call made for a change on the rows its record has, so this.visualRow in a validator and the row of afterValidate name the record whatever moved it while the validator ran, see core/waitingMetaStamps.ts.

Methods

isEmptyCol

Can be set at: grid

Source code

core.isEmptyCol(col) ⇒ boolean

The isEmptyCol option lets you define your own custom method for checking if a column at a given visual index is empty.

The isEmptyCol setting overwrites the built-in isEmptyCol method. The function receives a visual column index and must return a boolean.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Example

// overwrite the built-in `isEmptyCol` method
isEmptyCol(visualColumnIndex) {
// your custom method
...
},
ParamTypeDescription
colnumberVisual column index.

isEmptyRow

Can be set at: grid

Source code

core.isEmptyRow(row) ⇒ boolean

The isEmptyRow option lets you define your own custom method for checking if a row at a given visual index is empty.

The isEmptyRow setting overwrites the built-in isEmptyRow method. The function receives a visual row index and must return a boolean.

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

Example

// overwrite the built-in `isEmptyRow` method
isEmptyRow(visualRowIndex) {
// your custom method
...
},
ParamTypeDescription
rownumberVisual row index.

addHook

Source code

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);
ParamTypeDescription
keystringHook name (see Hooks).
callbackfunction
Array
Function or array of functions.
[orderIndex]numberoptional Order index of the callback. If > 0, the callback will be added after the others, for example, with an index of 1, the callback will be added before the ones with an index of 2, 3, etc., but after the ones with an index of 0 and lower. If < 0, the callback will be added before the others, for example, with an index of -1, the callback will be added after the ones with an index of -2, -3, etc., but before the ones with an index of 0 and higher. If 0 or no order index is provided, the callback will be added between the “negative” and “positive” indexes.

addHookOnce

Source code

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);
ParamTypeDescription
keystringHook name (see Hooks).
callbackfunction
Array
Function or array of functions.
[orderIndex]numberoptional Order index of the callback. If > 0, the callback will be added after the others, for example, with an index of 1, the callback will be added before the ones with an index of 2, 3, etc., but after the ones with an index of 0 and lower. If < 0, the callback will be added before the others, for example, with an index of -1, the callback will be added after the ones with an index of -2, -3, etc., but before the ones with an index of 0 and higher. If 0 or no order index is provided, the callback will be added between the “negative” and “positive” indexes.

alter

Source code

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);
ActionWith indexWithout index
'insert_row_above'Inserts rows above the index row.Inserts rows above the first row.
'insert_row_below'Inserts rows below the index row.Inserts rows below the last row.
'remove_row'Removes rows, starting from the index row.Removes rows, starting from the last row.
'insert_col_start'Inserts columns before the index column.Inserts columns before the first column.
'insert_col_end'Inserts columns after the index column.Inserts columns after the last column.
'remove_col'Removes columns, starting from the index column.Removes columns, starting from the last column.

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 2 columns, starting from column 3 (by visual index)
hot.alter('remove_col', 3, 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]]);
// pass a custom source string to hooks
hot.addHook('afterCreateRow', (index, amount, source) => {
if (source === 'inventory-import') {
// Run logic only for rows created by the inventory import.
}
});
hot.alter('insert_row_above', 0, 1, 'inventory-import');
// remove a row without immediately adding empty rows required by `minRows` or `minSpareRows`
hot.alter('remove_row', 4, 1, 'inventory-cleanup', true);
ParamTypeDescription
actionstringAvailable operations:
  • 'insert_row_above'
  • 'insert_row_below'
  • 'remove_row'
  • 'insert_col_start'
  • 'insert_col_end'
  • 'remove_col'
[index]number
Array<number>
optional A visual index of the row/column before or after which the new row/column will be inserted or removed. Can also be an array of arrays, in format [[index, amount],...]. For 'remove_row' and 'remove_col', rows and columns that do not exist are never removed. An index that points outside the table (a negative one, or one at or past the last row/column) removes nothing, and in the array format any part of a range that falls outside the table is ignored while the rest is still removed.
[amount]numberoptional The amount of rows or columns to be inserted or removed (default: 1).
[source]stringoptional Source indicator passed to related hooks.
[keepEmptyRows]booleanoptional If set to true, skips the automatic adjustment that normally adds empty rows or columns after the operation to satisfy minRows, minSpareRows, minCols, or minSpareCols.

applyThemeOverrides

Source code

Core~applyThemeOverrides(settings, init) ⇒ boolean

Applies the colorScheme and density options to the ThemeManager of this instance.

The options are per-instance overrides, so the shared theme object stays untouched and other grids using the same theme keep their own look.

ParamTypeDescription
settingsobjectThe settings object that may carry the overrides.
initbooleantrue when called during initialization. The initial styles are injected by the ThemeManager constructor, so nothing has to be refreshed in that case.

Returns: boolean - true when the overrides changed and afterSetTheme still has to run.

batch

Source code

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. Rendering and execution resume even when the callback throws; the error is rethrown.

The method suspends and resumes the execution through Core#suspendExecution and Core#resumeExecution, so the outermost call fires the four execution hooks around the callback.

With the batchEvaluation setting of the formulas option, the Formulas plugin can batch HyperFormula’s recalculation too.

Emits: Hooks#event:beforeSuspendExecution, Hooks#event:afterSuspendExecution, Hooks#event:beforeResumeExecution, Hooks#event:afterResumeExecution
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
});
ParamTypeDescription
wrappedOperationsfunctionBatched operations wrapped in a function.

Returns: * - Returns result from the wrappedOperations callback.

batchExecution

Source code

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.

Execution resumes even when the callback throws; the error is rethrown, and forceFlushChanges is not applied on that path.

Like batch(), the callback is one operation: every change it makes is one undo step of the UndoRedo plugin, with the 'batch' action type.

The method suspends and resumes the execution through Core#suspendExecution and Core#resumeExecution, so the outermost call fires the four execution hooks around the callback.

With the batchEvaluation setting of the formulas option, the Formulas plugin can batch HyperFormula’s recalculation too, but batchExecution() does not suspend rendering, so each render inside the callback still recalculates. For fewer recalculations, use batch().

Emits: Hooks#event:beforeSuspendExecution, Hooks#event:afterSuspendExecution, Hooks#event:beforeResumeExecution, Hooks#event:afterResumeExecution
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
});
ParamTypeDefaultDescription
wrappedOperationsfunctionBatched operations wrapped in a function.
[forceFlushChanges]booleanfalseoptional If true, the table internal data cache is recalculated after the execution of the batched operations. For nested calls, it can be a desire to recalculate the table after each batch.

Returns: * - Returns result from the wrappedOperations callback.

batchRender

Source code

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.

Rendering resumes even when the callback throws; the error is rethrown.

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
});
ParamTypeDescription
wrappedOperationsfunctionBatched operations wrapped in a function.

Returns: * - Returns result from the wrappedOperations callback.

clear

Source code

core.clear()

Clears the data from the table (the table settings remain intact) and clears the current selection.

The method empties every cell of the data set. Neither the current selection nor the selectionMode option limits its range. Cells set as readOnly keep their values.

Emits: Hooks#event:beforeChange, Hooks#event:afterChange

collectEmptyCellChanges

Source code

Core~collectEmptyCellChanges(changes, startRow, endRow, startColumn, endColumn) ⇒ void

Collects “empty this cell” changes for a rectangular range of cells, skipping read-only ones. The passed coordinates are clamped to the grid, so header coordinates (negative values) and corners that reach past the last row or column are safe to pass.

ParamTypeDescription
changesArray<Array>The array that the collected changes are pushed into.
startRownumberThe visual row index the range starts at.
endRownumberThe visual row index the range ends at.
startColumnnumberThe visual column index the range starts at.
endColumnnumberThe visual column index the range ends at.

colToProp

Source code

core.colToProp(column) ⇒ string | number | null

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 null when the index names no column that currently exists, the same way Core#toVisualColumn and the other index translators report an index they cannot resolve. It also returns null for a column declared as { data: null } – a perfectly valid index for a column that binds to no source property. Test the result before you use it as a property name.

ParamTypeDescription
columnnumberVisual column index. An argument that is not an integer comes back unchanged, so the declared type is narrower than what the method accepts at runtime.

Returns: string | number | null - Column property, physical column index, or null when the index names no column or the column binds to no property. When the column’s data option is an accessor function, that function is returned at runtime – check typeof before treating the result as a property name.

columnToPropForSelection

Source code

Core~columnToPropForSelection(column) ⇒ string | number | null

Translates a selection’s column index for the *ByProp hooks.

A selection range uses negative columns as header sentinels – -1 for a row selection, and further negative values for the nested-header levels above it – so they are not out-of-range indexes and must reach the hook unchanged. colToProp() cannot tell the two apart and now answers null for both, which would silently replace the sentinel every consumer of these hooks already handles.

ParamTypeDescription
columnnumberVisual column index, or a negative header sentinel.

Returns: string | number | null - The column property, or the sentinel unchanged.

countColHeaders

Source code

core.countColHeaders() ⇒ number

Returns the number of rendered column headers.

Since: 14.0.0

Returns: number - Number of column headers.

countCols

Source code

core.countCols() ⇒ number

Returns the total number of rendered columns. If the columns option is defined, it returns the number of columns set in that configuration, not the number of columns in the data source.

Returns: number - Total number of columns.

countEmptyCols

Source code

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.

ParamTypeDefaultDescription
[ending]booleanfalseoptional If true, will only count empty columns at the end of the data source row.

Returns: number - Count empty cols.

countEmptyRows

Source code

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.

ParamTypeDefaultDescription
[ending]booleanfalseoptional If true, will only count empty rows at the end of the data source.

Returns: number - Count empty rows.

countRenderedCols

Source code

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

Source code

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

Source code

core.countRowHeaders() ⇒ number

Returns the number of rendered row headers.

Since: 14.0.0

Returns: number - Number of row headers.

countRows

Source code

core.countRows() ⇒ number

Returns the total number of visual rows in the table.

Returns: number - Total number of rows.

countSourceCols

Source code

core.countSourceCols() ⇒ number

Returns the total number of columns in the data source. It will take value either from schema, columns settings or the first row from the data set. Unlike countCols(), this value is not affected by the columns configuration option.

Returns: number - Total number of columns.

countSourceRows

Source code

core.countSourceRows() ⇒ number

Returns the total number of rows in the data source.

Returns: number - Total number of rows.

countVisibleCols

Source code

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

Source code

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

Source code

core.deselectCell()

Deselects the current cell selection on the table.

destroy

Source code

core.destroy()

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

Emits: Hooks#event:afterDestroy

destroyEditor

Source code

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

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

ParamTypeDefaultDescription
[revertOriginal]booleanfalseoptional If true, the previous value will be restored. Otherwise, the edited value will be saved.
[prepareEditorIfNeeded]booleantrueoptional If true, the editor under the selected cell will be prepared to open.

emptySelectedCells

Source code

core.emptySelectedCells([source])

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

Emits: Hooks#event:beforeChange, Hooks#event:afterChange
Since: 0.36.0

ParamTypeDescription
[source]stringoptional String that identifies how this change will be described in the changes array (useful in Hooks#afterChange or Hooks#beforeChange callbacks). Set to ‘edit’ if left empty.

filterSettings

Source code

Core~filterSettings(settings) ⇒ object

Runs a settings payload through every filter _addSettingsFilter() added, in order.

ParamTypeDescription
settingsobjectThe payload.

Returns: object - The payload to apply.

foldUnplacedCorrection

Source code

Core~foldUnplacedCorrection(prop, value, [source])

Folds a validator’s correction written to a null row into the waiting change of the record it corrects, which has no visual row to write it through. The record is the one of the validator call that runs now, or, for a correction written later (after a timer or a request), the only record whose waiting validator call has a null row for the property. A correction no record can be told for is dropped, and the change it corrects lands as it was.

ParamTypeDescription
propstring
number
The property of the corrected cell.
value*The corrected value.
[source]stringoptional The change source.

foldValidatorCorrection

Source code

Core~foldValidatorCorrection(changes, records, prop, physicalRow, visualRow, value)

Writes a validator’s correction into the change of a waiting set it corrects: the change of the same property whose record holds the corrected physical row, or, for a change no record was captured for, the change made at the corrected visual row.

ParamTypeDescription
changesArrayThe changes of the waiting set.
recordsobjectThe records of the set’s changes.
propstring
number
function
The property of the corrected cell.
physicalRownumber
null
The physical row of the corrected cell, or null when it has none.
visualRownumber
null
The visual row of the corrected cell, or null when it has none.
value*The corrected value.

getActiveEditor

Source code

core.getActiveEditor() ⇒ BaseEditor | undefined

Returns the active editor class instance.

The active editor is the editor instance associated with the currently selected cell. An editor becomes active when a cell is selected and the editor is prepared (but not necessarily open). If no cell is selected, the method returns undefined.

Returns: BaseEditor | undefined - The active editor instance, or undefined if no cell is selected.

getActiveSelectionLayerIndex

Source code

core.getActiveSelectionLayerIndex() ⇒ number

Returns the index of the active selection layer. Active selection layer is the layer that has visible focus highlight.

Since: 16.1.0

Returns: number - The index of the active selection layer. 0 to N where 0 is the last (oldest) layer and N is the first (newest) layer.

getCell

Source code

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), or if the grid has no view yet, as inside a hook that fires during initialization.

ParamTypeDefaultDescription
rownumberVisual row index.
columnnumberVisual column index.
[topmost]booleanfalseoptional If set to true, it returns the TD element from the topmost overlay. For example, if the wanted cell is in the range of fixed rows, it will return a TD element from the top overlay.

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

getCellEditor

Source code

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));
ParamTypeDescription
rowOrMetanumberVisual row index or cell meta object (see Core#getCellMeta).
columnnumberVisual column index.

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

getCellMeta

Source code

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

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

The returned object reflects the effective cell configuration after cascading configuration (grid, column, and cell levels). To read global grid settings only, use Core#getSettings. To read column-level meta, use Core#getColumnMeta.

For a read-only bulk scan over many cells, use Core#getCellMetaTransient instead: it returns the same data without permanently caching a meta object per cell.

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

ParamTypeDefaultDescription
rownumberVisual row index.
columnnumberVisual column index.
optionsobjectExecution options for the getCellMeta method.
[options.skipMetaExtension]booleanfalseoptional If true, skips extending the cell meta object. This means, the cells function, as well as the afterGetCellMeta and beforeGetCellMeta hooks, will not be called.

Returns: object - The cell properties object.

getCellMetaAtRow

Source code

core.getCellMetaAtRow(row) ⇒ Array

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

ParamTypeDescription
rownumberPhysical row index.

getCellMetaTransient

Source code

core.getCellMetaTransient(row, column) ⇒ object

Returns the cell properties object for the given row and column coordinates without retaining it in the cell meta cache.

Like Core#getCellMeta, the returned object reflects the effective cell configuration after cascading configuration and dynamic extension (the cells function and the beforeGetCellMeta/afterGetCellMeta hooks run). Unlike getCellMeta, when the cell has no stored meta object the extension runs on a temporary object that is not saved, so scanning many cells (for example, a whole column or the entire dataset) does not permanently allocate one meta object per visited cell. Cells that already carry stored meta (for example, written by Core#setCellMeta or the cell option) return their stored object, exactly as getCellMeta would.

Use this method for read-only bulk scans. Do not write to the returned object - for cells without stored meta the write lands on the temporary object and is lost; use setCellMeta to persist values.

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

ParamTypeDescription
rownumberVisual row index.
columnnumberVisual column index.

Returns: object - The cell properties object.

getCellRenderer

Source code

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));
ParamTypeDescription
rowOrMetanumber
object
Visual row index or cell meta object (see Core#getCellMeta).
columnnumberVisual column index.

Returns: function - Returns the renderer function.

getCellsMeta

Source code

core.getCellsMeta() ⇒ Array

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

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

getCellValidator

Source code

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

Returns the cell validator by row and column.

When the cell has a finite maxLength, the returned function also checks the length of the value, before it runs the validator that you configured.

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));
ParamTypeDescription
rowOrMetanumber
object
Visual row index or cell meta object (see Core#getCellMeta).
columnnumberVisual column index.

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

getChangeLoadGeneration

Source code

Core~getChangeLoadGeneration([source], [changes]) ⇒ number

Returns the validationLoadGeneration a change set made now addresses: the current one, or, for a validator’s correction (isValidatorCorrection()), the one of the validator call that writes it. A correction written while its validator runs takes runningValidatorLoadGeneration. One written later takes the oldest unanswered call on the cells it writes, found by the record the correction’s row holds now: when calls from before and after a load wait on one cell, the older one’s correction must not land in the loaded rows, and a newer call’s correction dropped by mistake loses a correction, which is the lesser harm. A correction for a cell no call waits on takes the current one.

ParamTypeDescription
[source]stringoptional The change source.
[changes]Arrayoptional The changes, in the form [row, prop, ...].

getColHeader

Source code

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:

// 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

ParamTypeDefaultDescription
[column]numberoptional A visual column index.
[headerLevel]number-1optional (Since 12.3.0) Header level index. Accepts positive (0 to n) and negative (-1 to -n) values. For positive values, 0 points to the topmost header. For negative values, -1 points to the bottom-most header (the header closest to the cells).

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

getColumnMeta

Source code

core.getColumnMeta(column) ⇒ object

Returns the meta information for the provided column.

The returned object reflects the column-level configuration after cascading configuration (grid and column levels). To read global grid settings only, use Core#getSettings. To read the effective configuration for a specific cell, use Core#getCellMeta.

Since: 14.5.0

ParamTypeDescription
columnnumberVisual column index.

getColWidth

Source code

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

Returns the width of the requested column.

Passing colWidths to updateSettings() discards the widths stored by ManualColumnResize, so the option applies again from that point on.

Emits: Hooks#event:modifyColWidth

ParamTypeDescription
columnnumberVisual column index.
[source]stringoptional The source of the call.

Returns: number - Column width.

getCoords

Source code

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.
ParamTypeDescription
elementHTMLTableCellElementThe HTML Element representing the cell.

Returns: CellCoords | null - Visual coordinates object.

getCopyableData

Source code

core.getCopyableData(row, column) ⇒ string

Returns the data’s copyable value at specified row and column index, as a string.

A value that is not already a string is converted: numbers and booleans to their text form, null and undefined to an empty string, and everything else through its toString(). A cell with copyable disabled returns an empty string.

The text copied to the clipboard can differ for an object with its own valueOf(), because the clipboard reads such an object through valueOf() first.

ParamTypeDescription
rownumberVisual row index.
columnnumberVisual column index.

getCopyableSourceData

Source code

core.getCopyableSourceData(row, column) ⇒ *

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

The value is returned as it is stored, so it can be a nested object or an array. The CopyPaste plugin serializes those to JSON when copying with source data. A cell with copyable disabled returns an empty string.

Since: 16.1.0

ParamTypeDescription
rownumberVisual row index.
columnnumberVisual column index.

getCopyableText

Source code

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.

ParamTypeDescription
startRownumberFrom visual row index.
startColnumberFrom visual column index.
endRownumberTo visual row index.
endColnumberTo visual column index.

getCurrentThemeName

Source code

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

Source code

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

Returns the current visual data as a 2D array.

Unlike the source data (which may be an array of objects), getData() always returns an array of arrays regardless of the original data format. The returned data reflects the current visual state of the grid: rows and columns are in their current visual order, after any sorting, filtering, or reordering.

To retrieve the data in its original source format, use the Core#getSourceData method instead.

Optionally you can provide a cell range by defining row, column, row2, column2 to get only a fragment of 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);
ParamTypeDescription
[row]numberoptional From visual row index.
[column]numberoptional From visual column index.
[row2]numberoptional To visual row index.
[column2]numberoptional To visual column index.

Returns: Array<Array> - A 2D array of cell values in the current visual order.

getDataAtCell

Source code

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.

ParamTypeDescription
rownumberVisual row index.
columnnumberVisual column index.

Returns: * - Data at cell.

getDataAtCol

Source code

core.getDataAtCol(column) ⇒ Array

Returns array of column values from the data source, one value per visual row. With the nestedRows option, the result includes the visible child rows and skips the children of collapsed parents. A grid with no rows returns [null], so the length is one more than countRows() there.

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

ParamTypeDescription
columnnumberVisual column index.

Returns: Array - Array of cell values.

getDataAtProp

Source code

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. The result holds one value per visual row. With the nestedRows option, it includes the visible child rows and skips the children of collapsed parents. For an existing column of a grid with no rows, it returns [null], so the length is one more than countRows() there.

ParamTypeDescription
propstring
number
Property name or physical column index.

Returns: Array - Array of cell values. An empty array when prop names no column – an index past the last column, a negative index, or a property name your data set does not use.

getDataAtRow

Source code

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.

ParamTypeDescription
rownumberVisual row index.

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

getDataAtRowProp

Source code

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.

ParamTypeDescription
rownumberVisual row index.
propstringProperty name.

Returns: * - Cell value.

getDataType

Source code

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.

ParamTypeDescription
rowFromnumberFrom visual row index.
columnFromnumberFrom visual column index.
rowTonumberTo visual row index.
columnTonumberTo visual column index.

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

getDirectionFactor

Source code

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

Source code

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

Returns: number | null - The index, or null when the grid has no view yet or has not been rendered.

getFirstFullyVisibleRow

Source code

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

Returns: number | null - The index, or null when the grid has no view yet or has not been rendered.

getFirstPartiallyVisibleColumn

Source code

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

Returns: number | null - The index, or null when the grid has no view yet or has not been rendered.

getFirstPartiallyVisibleRow

Source code

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

Returns: number | null - The index, or null when the grid has no view yet or has not been rendered.

getFirstRenderedVisibleColumn

Source code

core.getFirstRenderedVisibleColumn() ⇒ number | null

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

When the MergeCells plugin is enabled with its default virtualized: false setting, a merged cell that crosses the viewport edge extends the rendered column range, so this method can return a column index further from the viewport than usual. For the actual visible viewport, use Core#getFirstFullyVisibleColumn or Core#getFirstPartiallyVisibleColumn.

Since: 14.6.0

Returns: number | null - The index, or null when the grid has no view yet or has not been rendered.

getFirstRenderedVisibleRow

Source code

core.getFirstRenderedVisibleRow() ⇒ number | null

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

When the MergeCells plugin is enabled with its default virtualized: false setting, a merged cell that crosses the viewport edge extends the rendered row range, so this method can return a row index further from the viewport than usual. For the actual visible viewport, use Core#getFirstFullyVisibleRow or Core#getFirstPartiallyVisibleRow.

Since: 14.6.0

Returns: number | null - The index, or null when the grid has no view yet or has not been rendered.

getFocusManager

Source code

core.getFocusManager() ⇒ FocusManager

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

Since: 14.0.0

getFocusScopeManager

Source code

core.getFocusScopeManager() ⇒ FocusScopeManager

Returns the Focus Scope Manager. The module allows to register focus scopes for different parts of the grid e.g. for dialogs, pagination, and other plugins that have own UI elements and need separate context.

Since: 16.2.0
Example

hot.getFocusScopeManager().registerScope('myPluginName', containerElement, {
shortcutsContextName: 'plugin:myPluginName',
onActivate: (focusSource) => {
// Focus the internal focusable element within the plugin UI element
// depends on the activation focus source.
},
});

Returns: FocusScopeManager - Instance of FocusScopeManager

getInstance

Source code

core.getInstance() ⇒ Handsontable

Returns the Handsontable instance.

Returns: Handsontable - The Handsontable instance.

getLastColumnReadRow

Source code

Core~getLastColumnReadRow() ⇒ number

Returns the last visual row a whole-column read covers.

The read runs in visual rows, so it has to reach countRows(): under NestedRows the source array holds only the top-level records, and a modifySourceLength listener can report more rows than the array has, so its length stops the read short of every row past it. The source length stays in the max so a grid with no visual rows reads what it always did: with an empty data set the end is -1, so getRange() starts at the header row and returns [null], while a fully trimmed one returns []. When the source length wins, getRange() still stops at countRows() for two different reasons: a visual index past the not-trimmed rows maps to no physical row, so it skips it, and a row cut off by maxRows does map to one, but getRange() clamps the range to maxRows - 1.

Returns: number - Visual row index.

getLastFullyVisibleColumn

Source code

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

Returns: number | null - The index, or null when the grid has no view yet or has not been rendered.

getLastFullyVisibleRow

Source code

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

Returns: number | null - The index, or null when the grid has no view yet or has not been rendered.

getLastPartiallyVisibleColumn

Source code

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

Returns: number | null - The index, or null when the grid has no view yet or has not been rendered.

getLastPartiallyVisibleRow

Source code

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

Returns: number | null - The index, or null when the grid has no view yet or has not been rendered.

getLastRenderedVisibleColumn

Source code

core.getLastRenderedVisibleColumn() ⇒ number | null

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

When the MergeCells plugin is enabled with its default virtualized: false setting, a merged cell that crosses the viewport edge extends the rendered column range, so this method can return a column index further from the viewport than usual. For the actual visible viewport, use Core#getLastFullyVisibleColumn or Core#getLastPartiallyVisibleColumn.

Since: 14.6.0

Returns: number | null - The index, or null when the grid has no view yet or has not been rendered.

getLastRenderedVisibleRow

Source code

core.getLastRenderedVisibleRow() ⇒ number | null

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

When the MergeCells plugin is enabled with its default virtualized: false setting, a merged cell that crosses the viewport edge extends the rendered row range, so this method can return a row index further from the viewport than usual. For the actual visible viewport, use Core#getLastFullyVisibleRow or Core#getLastPartiallyVisibleRow.

Since: 14.6.0

Returns: number | null - The index, or null when the grid has no view yet or has not been rendered.

getLayoutManager

Source code

core.getLayoutManager() ⇒ LayoutManager

Returns the Layout Manager. The module manages the order of plugin UI elements within the user-orderable wrapper slots (top, bottom, start, end). Use it to add or remove custom UI and order it via weights or the layout setting. Only available for the main instance.

Since: 18.0.0
Example

hot.getLayoutManager().register('myToolbar', toolbarElement, { side: 'top', weight: 100 });
// Dock a side panel at the grid's inline-start edge (the right edge under RTL).
hot.getLayoutManager().register('myPanel', panelElement, { side: 'start' });

Returns: LayoutManager - Instance of LayoutManager

getPhysicalRowById

Source code

core.getPhysicalRowById(id) ⇒ number | null

Returns the physical index of the row that has the given id.

The id is defined by the rowId option (or dataProvider.rowId). Unlike getVisualRowById(), it also finds a row that is trimmed or filtered out.

Since: 19.0.0

ParamTypeDescription
id*The row’s id.

Returns: number | null - The physical row index, or null when no row has the id (for example, the row was removed).

getPhysicalRowOfChange

Source code

core.getPhysicalRowOfChange(change) ⇒ number | null

Returns the physical index of the row a change was written to.

Use it in the afterChange and beforeChangeRender hooks to find the record of a change whose row is null. A change to a cell with a validator is written to the record it was made on when the validator answers. When a filter or another trimming feature took that record out of the visual space in the meantime, the record has no visual index, so the hooks report row as null, and only the physical index still names the record. Pass the physical index to getSourceDataAtRow() to read the record, or to getRowIdAtPhysicalRow() to read its id.

The method answers for a change that waited for its validator until the afterChange hook that reports it has run: while the change waits, it returns the physical row of its record now (null once the record was removed), and in beforeChangeRender and afterChange it returns the physical row the change was written to. After the afterChange hook, the grid no longer follows the record, so read the physical index (or the row’s id) inside the hook, and keep it if you need it later. For any other change, and for a change after its afterChange hook, the method returns the physical index of the change’s visual row now, or null when row is null.

Since: 19.0.0
Example

hot.addHook('afterChange', (changes, source) => {
changes?.forEach((change) => {
const physicalRow = hot.getPhysicalRowOfChange(change);
if (physicalRow !== null) {
save(hot.getSourceDataAtRow(physicalRow));
}
});
});
ParamTypeDescription
changeArrayA change, as the afterChange or beforeChangeRender hook passes it: [row, prop, oldValue, newValue]. Pass the array the hook passes, not a copy.

Returns: number | null - The physical row index, or null when the change addresses no row.

getPhysicalRowOfExistingRow

Source code

Core~getPhysicalRowOfExistingRow(visualRow) ⇒ number | null

Returns the physical row of a visual row that exists, or null for a row past the last one, which a write creates and which therefore has no record to follow.

ParamTypeDescription
visualRownumberThe visual row index.

getPhysicalRowsByIds

Source code

core.getPhysicalRowsByIds(ids) ⇒ Array<(number|null)>

Returns the physical indexes of the rows that have the given ids.

Since: 19.0.0

ParamTypeDescription
idsArrayThe row ids.

Returns: Array<(number\|null)> - The physical row indexes, in the order of ids, with null for an id that no row has.

getPlugin

Source code

core.getPlugin(pluginName) ⇒ BasePlugin | undefined

Returns plugin instance by provided its name.

ParamTypeDescription
pluginNamestringThe plugin name.

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

getRowHeader

Source code

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, Hooks#event:modifyRowHeaderValue

ParamTypeDescription
[row]numberoptional Visual row index.

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

getRowHeight

Source code

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 rowHeights array and function are read by the physical index of row, so a height stays with its row when rows are moved, sorted, filtered, trimmed, or collapsed.

Passing rowHeights to updateSettings() discards the heights stored by ManualRowResize, so the option applies again from that point on.

A height set through rowHeights is returned as set, even when it is smaller than the default row height. A height set through minRowHeights, or through rowHeights while AutoRowSize is enabled, is never smaller than the default row height.

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

ParamTypeDescription
rownumberA visual row index.
[source]stringoptional The source of the call.

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

getRowId

Source code

core.getRowId(row) ⇒ *

Returns the id of a row, as the rowId option (or dataProvider.rowId) defines it.

A row’s id stays with the row’s record when you sort, filter, move, trim, insert, or remove rows, and when you undo or redo any of those actions.

Since: 19.0.0

ParamTypeDescription
rownumberVisual row index.

Returns: * - The row’s id, or null when the row does not exist, has no id, or no row ids are configured.

getRowIdAtPhysicalRow

Source code

core.getRowIdAtPhysicalRow(physicalRow) ⇒ *

Returns the id of a row, addressed by its physical index.

Unlike getRowId(), it also reads the id of a row that is trimmed or filtered out, which has no visual index. Use it with the physical row indexes that hooks such as beforeRemoveRow pass.

Since: 19.0.0

ParamTypeDescription
physicalRownumberPhysical row index.

Returns: * - The row’s id, or null when the row does not exist, has no id, or no row ids are configured.

getRowIds

Source code

core.getRowIds([rows]) ⇒ Array

Returns the ids of several rows at once.

Since: 19.0.0

ParamTypeDescription
[rows]Array<number>optional Visual row indexes. Without it, the method returns the ids of every row, in visual order.

Returns: Array - The ids, in the order of rows, with null for a row that does not exist or has no id.

getSchema

Source code

core.getSchema() ⇒ object

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

Returns: object - Schema object.

getSelected

Source code

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.

getSelectedActive

Source code

core.getSelectedActive() ⇒ Array<number> | undefined

Returns the range coordinates of the active selection layer as an array. Active selection layer is the layer that has visible focus highlight.

Since: 16.1.0

Returns: Array<number> | undefined - Selected range as an array of coordinates or undefined if there is no selection.

getSelectedLast

Source code

core.getSelectedLast() ⇒ Array | undefined

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

Since: 0.36.0

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

getSelectedRange

Source code

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 active selected area (as it was previously done by the method) you need to use getSelectedRangeActive() method.

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

getSelectedRangeActive

Source code

core.getSelectedRangeActive() ⇒ CellRange | undefined

Returns the range coordinates of the active selection layer. Active selection layer is the layer that has visible focus highlight.

Since: 16.1.0

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

getSelectedRangeLast

Source code

core.getSelectedRangeLast() ⇒ CellRange | undefined

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

Since: 0.36.0

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

getSettings

Source code

core.getSettings() ⇒ TableMeta

Returns the current global grid settings object.

The returned object contains the settings passed to the constructor or the most recent updateSettings() call. It reflects the grid-level configuration only.

It does not include merged per-cell or per-column values. Configuration options cascade from grid to column to cell (see Cascading configuration). To read the effective value for a specific cell, use Core#getCellMeta. To read column-level meta, use Core#getColumnMeta.

A hook removed through updateSettings({ <hook>: null }) reads back as null, so check a hook callback read from the returned object before you call it.

Example

const hot = new Handsontable(container, {
readOnly: false,
columns: (index) => ({
readOnly: index === 2 || index === 8,
}),
});
// returns `false` (global grid-level setting)
hot.getSettings().readOnly;
// returns `true` for column 2 (merged column and cell meta)
hot.getCellMeta(0, 2).readOnly;

Returns: TableMeta - Object containing the current global grid settings.

getShortcutManager

Source code

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

Source code

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

ParamTypeDescription
[row]numberoptional From physical row index.
[column]numberoptional From physical column index (or visual index, if data type is an array of objects).
[row2]numberoptional To physical row index.
[column2]numberoptional To physical column index (or visual index, if data type is an array of objects).

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

getSourceDataArray

Source code

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.

For an array of objects, each returned row holds a place for every column declared by the columns option (up to maxCols), in visual column order. A column declared without data keeps its place, and its value is undefined.

ParamTypeDescription
[row]numberoptional From physical row index.
[column]numberoptional From physical column index (or visual index, if data type is an array of objects).
[row2]numberoptional To physical row index.
[column2]numberoptional To physical column index (or visual index, if data type is an array of objects).

Returns: Array - An array of arrays.

getSourceDataAtCell

Source code

core.getSourceDataAtCell(row, column) ⇒ *

Returns a single value from the data source.

The row argument is a physical index. A numeric column is a visual index, so it follows moved and trimmed columns. A hidden column keeps its index. To read a column by its physical index, translate it first with Core#toVisualColumn, or, with an array of objects, pass the column’s prop name. A trimmed column has no visual index: read it by its prop name with an array of objects, or with Core#getSourceData and a physical range with an array of arrays. An index past the last visible column is read as a physical index.

Note: Core#setSourceDataAtCell takes a physical column index, so a read and a write at the same number can address different columns.

ParamTypeDescription
rownumberPhysical row index.
columnnumber
string
function
Visual column index, prop name, or a columns[].data accessor function (called as column(dataRow)).

Returns: * - Cell data.

getSourceDataAtCol

Source code

core.getSourceDataAtCol(column) ⇒ Array

Returns an array of column values from the data source.

The column argument is a visual index, so it follows moved and trimmed columns. A hidden column keeps its index. To read a column by its physical index, translate it first with Core#toVisualColumn. A trimmed column has no visual index, so this method cannot read it. For an array of arrays, read it with Core#getSourceData and a physical range.

Note: Core#setSourceDataAtCell takes a physical column index, so a read and a write at the same number can address different columns.

ParamTypeDescription
columnnumberVisual column index.

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

getSourceDataAtRow

Source code

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.

ParamTypeDescription
rownumberPhysical row index.

Returns: Array | object - Single row of data.

getTableHeight

Source code

core.getTableHeight() ⇒ number

Gets the table’s root container element height.

Since: 16.0.0

getTableWidth

Source code

core.getTableWidth() ⇒ number

Gets the table’s root container element width.

Since: 16.0.0

getTranslatedPhrase

Source code

core.getTranslatedPhrase(dictionaryKey, extraArguments) ⇒ string

Get language phrase for specified dictionary key.

Since: 0.35.0

ParamTypeDescription
dictionaryKeystringConstant which is dictionary key.
extraArguments*Arguments which will be handled by formatters.

getValue

Source code

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.

getValueToValidate

Source code

Core~getValueToValidate(row, column, [cellMeta]) ⇒ *

Returns the value validation outside an edit checks for a cell.

A cell type that brings its own valueGetter pairs it with a validator that checks the stored form: the choice types store a key/value entry or a multiselect array, which their getter turns into a label or a joined string, and an edit validates the stored form too. Such a cell is validated on its stored value. A valueGetter the cell configures itself only changes what the cell shows, and the validator was written against that, so the cell is validated on its Core#getDataAtCell value, the getter’s output included. The modifyRowData and modifyData hooks apply either way.

ParamTypeDescription
rownumberVisual row index.
columnnumberVisual column index.
[cellMeta]objectoptional The cell meta, when the caller already holds it.

getVisualRowById

Source code

core.getVisualRowById(id) ⇒ number | null

Returns the visual index of the row that has the given id.

The id is defined by the rowId option (or dataProvider.rowId).

Since: 19.0.0

ParamTypeDescription
id*The row’s id.

Returns: number | null - The visual row index, or null when no row has the id (for example, the row was removed), or the row is trimmed, filtered out, or past maxRows. A hidden row keeps its visual index.

getVisualRowsByIds

Source code

core.getVisualRowsByIds(ids) ⇒ Array<(number|null)>

Returns the visual indexes of the rows that have the given ids.

Since: 19.0.0

ParamTypeDescription
idsArrayThe row ids.

Returns: Array<(number\|null)> - The visual row indexes, in the order of ids, with null wherever getVisualRowById() returns null.

hasColHeaders

Source code

core.hasColHeaders() ⇒ boolean

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

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

hasHook

Source code

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');
ParamTypeDescription
keystringHook name.

hasRowHeaders

Source code

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.

initializeThemeManager

Source code

Core~initializeThemeManager(theme, [overrides])

Initializes the ThemeManager with the given theme configuration.

ParamTypeDescription
themeobject
boolean
The theme configuration object or true to use the default theme.
[overrides]objectoptional The per-instance color scheme and density overrides.

isColumnModificationAllowed

Source code

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

Source code

core.isEmptyCol(column) ⇒ boolean

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

ParamTypeDescription
columnnumberColumn index.

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

isEmptyRow

Source code

core.isEmptyRow(row) ⇒ boolean

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

ParamTypeDescription
rownumberVisual row index.

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

isExecutionSuspended

Source code

core.isExecutionSuspended() ⇒ boolean

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

Since: 8.3.0

isListening

Source code

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

Source code

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.

isRemovedColumnCorrection

Source code

Core~isRemovedColumnCorrection(prop, [source]) ⇒ boolean

Tells whether a write of a change to a null property is a validator’s correction for a column a removal took while its validator call waits. The validator writes it through this.prop, which is null then. A grid with a column declared { data: null } writes through that property, so it never counts there.

ParamTypeDescription
prop*The property of the change.
[source]stringoptional The change source.

isRenderSuspended

Source code

core.isRenderSuspended() ⇒ boolean

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

Since: 8.3.0

isRtl

Source code

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.

isUnplacedCorrection

Source code

Core~isUnplacedCorrection(visualRow, [source]) ⇒ boolean

Tells whether a write of a change to a null row is a validator’s correction for a record a filter or a trim took out of the visual space while its validator call waits. The validator writes it through this.visualRow, which is null then. It does not depend on a waiting validator call: a correction written after its own call answered has no change left to fold into, and is dropped the same way.

ParamTypeDescription
visualRownumber
null
The visual row of the change.
[source]stringoptional The change source.

isWriteBeforeRowsExist

Source code

Core~isWriteBeforeRowsExist(methodName) ⇒ boolean

Tells whether a write by visual coordinates has no row to land on yet, and warns when it has not.

Inside afterHideColumns and afterHideRows at init the source data is loaded but the grid has no visual row yet, so a write would see every row as past the end and append a record.

ParamTypeDescription
methodNamestringThe public method that was called.

Returns: boolean - true when the write must be skipped.

leaveValidatorAnswer

Source code

Core~leaveValidatorAnswer()

Leaves a validator answer. When the outermost one ends, its hold on the transaction of the change it answers is released, so the functions _runAfterValidatorAnswer() queued run as operations of their own. A grid a listener destroyed meanwhile runs none of them.

listen

Source code

core.listen()

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

Emits: Hooks#event:afterListen

loadData

Source code

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)
  • Resets sorting, filters, the rows you trimmed, and the rows and columns you moved, hid, or resized at runtime.
  • Applies again the state that these options declare: hiddenRows, hiddenColumns, trimRows, manualRowMove, manualColumnMove, manualRowResize, and manualColumnResize (for example hiddenRows: { rows: [2] }). Sorting that initialConfig of columnSorting or multiColumnSorting declares is not applied again.
  • Drops the cell metadata from the cell option, although getSettings().cell still lists it. Metadata from columns stays.
  • Clears the undo and redo history of the UndoRedo plugin.
  • Keeps the settings, the selection (limited to the size of the new data), and merged cells.

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

A change that still waits for its cell’s validator when you call loadData() is dropped: it isn’t written into the new data, also when the new data holds the same records, and afterChange never fires for it. A correction the validator writes for it is dropped too. Validators always answer after the call that made the change returns, so this includes a synchronous validator and a change made in the same function right before loadData(). An open editor that waits for that validator closes without saving. updateData() drops nothing.

Read more:

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

ParamTypeDescription
dataArrayAn array of arrays, or an array of objects, that contains Handsontable’s data.
[source]stringoptional The source of the loadData() call.

markAllCellsChanged

Source code

core.markAllCellsChanged()

Marks every cell as changed, so the next render paints all of them regardless of their renderMode. The method does not render; call render() afterwards.

Since: 19.0.0
Example

hot.markAllCellsChanged();
hot.render(); // repaints every rendered cell, as a render does under `renderMode: 'always'`

markCellChanged

Source code

core.markCellChanged(row, column)

Marks one cell as changed, so the next render paints it even when its renderMode is 'onChange' and neither its value nor its meta changed. Use it for a renderer that reads state outside the grid, after that state changes. The method does not render; call render() afterwards.

Under the default renderMode: 'always' every render paints every cell, so the call is a no-op.

Since: 19.0.0
Example

theme = 'dark'; // state the renderer of cell (0, 0) reads
hot.markCellChanged(0, 0);
hot.render();
ParamTypeDescription
rownumberVisual row index.
columnnumberVisual column index.

measureSideSlotsLayout

Source code

Core~measureSideSlotsLayout() ⇒ string

Describes where the side panels leave the grid: the combined side slot width and the start slot’s own width. Two panels that trade widths keep the combined width but move the grid.

observeRowShifts

Source code

Core~observeRowShifts(listener) ⇒ function

Tells a waiting change of a row past the last one about the rows alter(), a write past the last row or a spare-row option inserts or removes, by their visual rows, and about a change of the number of trimmed rows (read on every cacheUpdated of the row index mapper), see core/waitingRecords.ts.

ParamTypeDescription
listenerobjectThe listener.

Returns: function - Stops telling the listener.

onBeforeIndexMapperCacheUpdate

Source code

Core~onBeforeIndexMapperCacheUpdate(indexesChangesState, axis)

Snapshots the selection in PHYSICAL coordinates before an index mapper rebuilds its caches.

It has to happen here: IndexMapper#updateCache() rebuilds every cache before it fires cacheUpdated, so by then the pre-update visual space is gone and the records the selection was laid on cannot be recovered. Selection takes the physical snapshot only while an editor is open - a selection with no editor is repaired by repairSelection() below, on a different rule. The grid-tracking coverage the DEV-152 grow reads is recorded on every trimming update, editor or not, because that grow belongs to the no-editor repair.

ParamTypeDescription
indexesChangesStateobjectThe state object of the index mapper’s cache update.
axis'row'
'column'
The mapper axis that is about to be updated.

onIndexMapperCacheUpdate

Source code

Core~onIndexMapperCacheUpdate(indexesChangesState, axis) ⇒ boolean

Reacts to an index-map cache update, and reports whether an editor was open when it landed.

That answer is RETURNED rather than stored, because both axes share this function: a column update nested inside the row hooks would overwrite a shared flag, and by then EditorManager has discarded the stranded editor, so it would write false and the outer row repair would run the full record test instead of the narrower one - dropping a selection the editor deliberately kept. Returning it gives each axis its own value.

ParamTypeDescription
indexesChangesStateobjectThe state object of the index mapper’s cache update.
indexesChangesState.hiddenIndexesChangedbooleanWhether the hidden indexes changed.
indexesChangesState.trimmedIndexesChangedbooleanWhether the trimmed indexes changed.
axis'row'
'column'
The mapper axis that was updated.

persistValidationResult

Source code

Core~persistValidationResult(cellProperties, valid, structureVersion)

Writes a validation result onto the cell’s CURRENT stored meta object.

The object a validator is given is captured before it runs, and an updateSettings clearing the meta cache in that window detaches it - a write on it then reaches nothing. Both directions matter. A failure that never reaches the stored meta leaves the cell unmarked, which is the async half of GitHub issue #7553. A pass that never reaches it leaves behind the false that restoreInvalidCellMetas re-applied for a cell that was invalid when the clear happened, so a corrected value keeps its red mark - and the same holds for the allowInvalid: false cancel path, where the rejected edit is dropped but the cell would stay flagged.

The lookup is a peek, so a passing result never materializes a meta object on its own and _validateCells keeps its O(invalid cells) retention bound. A failure does materialize, because it has to be rendered. Physical coordinates come off the meta object itself rather than being re-derived from the visual ones, which a row insert or move in the same window would shift.

The coordinates are only usable while the grid’s structure has not moved. LazyFactoryMap re-keys stored meta objects when rows or columns are inserted or removed, but the row/col fields stamped on those objects are not rewritten - so a pair captured before such a change can name a different cell after it, and writing through would flag a cell the user never touched. structureVersion is captured when validation starts; when it has moved, the result is dropped rather than written somewhere it does not belong. The direct write on the captured object still happened, and that object follows the shift on its own.

ParamTypeDescription
cellPropertiesobjectThe cell meta object the validator was handed.
validbooleanThe validation result to persist.
structureVersionnumberThe structure version captured when validation started.

populateFromArray

Source code

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

ParamTypeDefaultDescription
rownumberStart visual row index.
columnnumberStart visual column index.
inputArray2d array.
[endRow]numberoptional End visual row index (use when you want to cut input when certain row is reached).
[endCol]numberoptional 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'. The input rows may differ in length. The widest row sets the width of the populated area, and a shorter row fills the positions it does not reach with the empty-cell value (null).

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

propToCol

Source code

core.propToCol(prop) ⇒ string | number | function | null

Returns column index that corresponds with the given property.

Returns null when the argument names no column that currently exists and is visible – an index past the last column, or one whose column is trimmed. Both forms answer the same way: a cached property and a bare physical index on array data now agree.

A property this data set does not use is handed back unchanged, so validate with Number.isInteger() rather than comparing against Core#countCols: null compares as 0 and would pass such a check.

The TypeScript declaration is narrower than what runs, at both ends. It narrows the result to number | null, so a returned property name is not visible to the type checker, and it narrows the parameter to string | number, so passing a columns[].data accessor function works at runtime but does not type-check.

ParamTypeDescription
propstring
number
function
Property name, physical column index, or a columns[].data accessor function.

Returns: string | number | function | null - Visual column index, null when the argument names no visible column, or the passed argument when it is a property this data set does not use.

queueValidators

Source code

Core~queueValidators(changes, [source], loadGeneration, waitingForValidator, pendingRowMetas, ledger, records, onRejected)

Starts the validator of every change that has one, and queues each until it answers. A change the validator rejects under allowInvalid: false is taken out of the list. Nothing is validated once the set’s load generation is not the current one: a loadData() landed in the loop (a beforeValidate listener can run one), or the set is a validator’s correction made after a load overtook the change it corrects. The set is dropped then, and validating it would read the loaded records’ meta, mark them for values never written, and count the call in _hasPendingValidation() under the new load.

ParamTypeDescription
changesArrayThe changes, in the form [row, prop, oldValue, newValue].
[source]stringoptional The change source.
loadGenerationnumberThe load generation the set was made on.
waitingForValidatorobjectThe queue.
pendingRowMetasArray<object>Collects the cell meta of the cells validated in rows that do not exist yet.
ledgerobject
null
Orders the writes to one cell, or null for a validator’s correction.
recordsobjectThe records of the set’s changes. Captured right before the first validator is called, so a set no validator waits on captures nothing.
onRejectedfunctionCalled with each rejected change, before it is taken out of the list.

readStoredThemeOverrides

Source code

Core~readStoredThemeOverrides() ⇒ object

Reads the color scheme and density currently configured on this instance.

Unlike readThemeOverrides(), this reads the effective values rather than only the keys that one payload carries. updateSettings() stores grid options on the global meta, which the table meta inherits through its prototype, so an own-property check would miss them. Use this when rebuilding a ThemeManager, which has to pick up options set by an earlier call.

Returns: object - The theme overrides object.

readThemeOverrides

Source code

Core~readThemeOverrides(settings) ⇒ object

Reads the per-instance color scheme and density overrides from a settings object.

Only the keys actually present are returned, so a missing key keeps the value already applied instead of resetting it to the theme default.

ParamTypeDescription
settingsobjectThe settings object to read the overrides from.

Returns: object - The theme overrides object.

recordValidatorGeneration

Source code

Core~recordValidatorGeneration(record, prop, generation)

Records an unanswered validator call made for a change, until releaseValidatorGeneration().

ParamTypeDescription
recordobjectThe tracked record of the row the validator checks.
prop*The property the validator checks.
generationnumberThe validationLoadGeneration of the call.

refreshAfterFontsLoad

Source code

Core~refreshAfterFontsLoad()

Re-measures the grid after the document finished loading a web font (DEV-199). The rows and columns were measured with the fallback font, and the new font changes the size of the text without changing the size of the container, so no resize observer sees it. Without this, the cells that grew stay out of line with their row headers and frozen columns, the grid keeps its old height, and columns sized from their content clip the wider text.

The handler fires afterFontsLoad, on which the sizing plugins re-measure, then drops the engine’s size caches and renders. refreshDimensions() is not enough: it skips the render when the container keeps its size, which is the case for a grid with a fixed height. On a hidden grid the re-measure waits until the grid is shown, and so does the render after a listener that hid the grid.

refreshAfterFontsLoadOnceShown

Source code

Core~refreshAfterFontsLoadOnceShown()

Runs refreshAfterFontsLoad() again once the hidden grid is shown.

refreshDimensions

Source code

core.refreshDimensions()

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

You rarely need to call this method. Handsontable already calls it for you on a window resize and through a ResizeObserver on the container. The case it does not cover is a container resized while the grid is hidden (for example inside a display: none tab or accordion): the observer callback is skipped, so call this method yourself once the grid becomes visible again. A web font that loads after the grid renders needs no call: Handsontable re-measures its rows and columns when the document finishes loading a font.

The method renders when the measured size changed. It also renders unconditionally when the grid scrolls with the window (no fixed height), so on such a grid it is not free even at an unchanged size. And it renders when a change of the browser zoom moved the border of the cells, which changes the height of every row even though the container kept its size: the afterRefreshDimensions hook then receives false for its stateChanged argument. To repaint the cells without re-measuring the container, use render() instead.

When the size changed while a cell editor is open, the editor moves onto its cell. If the cell was not fully in view, the grid first scrolls it into view and renders once more, which fires afterScroll. An editor that waits for an asynchronous validator moves after the validator answers, and with rendering suspended it moves after the next render.

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

releaseValidatorGeneration

Source code

Core~releaseValidatorGeneration(record, prop, generation)

Forgets one unanswered validator call recordValidatorGeneration() recorded.

ParamTypeDescription
recordobjectThe tracked record of the row the validator checks.
prop*The property the validator checks.
generationnumberThe validationLoadGeneration of the call.

removeCellMeta

Source code

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.

An index that lies outside the grid’s current range is not translated – it is used as the physical index as it is, the same way Core#setCellMeta writes one. With nothing trimmed, that keeps a coordinate captured before the data shrank (through updateData, which keeps the cell meta) addressing the record it was written to. With rows or columns trimmed (trimRows, a filter), the physical index the raw value names can be a live trimmed record, or a record the grid shows at a different visual index (when the trimmed records sit before it), so such a call removes the key from that record without an error – pass the visual index of the cell instead.

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

ParamTypeDescription
rownumberVisual row index.
columnnumberVisual column index.
keystringProperty name.

removeHook

Source code

core.removeHook(key, callback)

Removes the hook listener previously registered with Core#addHook.

See: Hooks#remove
Example

hot.removeHook('beforeInit', myCallback);
ParamTypeDescription
keystringHook name.
callbackfunctionReference to the function which has been registered using Core#addHook.

removeTrailingItems

Source code

Core~removeTrailingItems(axis, index, amount)

Removes the last rows or columns of the grid with the auto source, and keeps the editor and the selection on what is left.

It is not alter(): the rows and columns it removes were created without it (adjustRowsAndCols() calls the data map directly), so alter()’s bookkeeping would be one-sided here - it lowers fixedRowsBottom and splices colHeaders, neither of which the creation raised or extended.

ParamTypeDescription
axisstringThe axis to remove from, 'row' or 'column'.
indexnumberThe visual index of the first removed row or column.
amountnumberThe number of rows or columns to remove.

render

Source code

core.render()

Rerenders the table. Calling this method recalculates the layout, redraws the cells, and applies the changes to the DOM. Every redrawn cell runs its cell renderer and the cells function again. The data, the selection, and the scroll position are left as they are.

The render covers the cells that are currently rendered: the viewport plus the buffer set by viewportRowRenderingOffset and viewportColumnRenderingOffset. It does not cover the whole data set, unless you turn virtualization off with renderAllRows or renderAllColumns. The cost therefore scales with the number of rendered cells and with the work those functions do. The number of records you hold is not what drives it.

You rarely need to call this method. Handsontable renders itself after every CRUD operation and at other points in its lifecycle. Call it yourself when you change something Handsontable cannot detect on its own. The common case is setCellMeta(), which updates cell metadata without repainting the grid. Because that method never renders, a sequence of such calls followed by one render() already costs exactly one render.

When you mix metadata changes with CRUD operations, wrap the whole sequence in batch() and call render() inside the callback. batch() on its own only suppresses the renders the CRUD operations would have triggered; it does not add one, so a callback holding nothing but setCellMeta() calls leaves the grid unpainted.

There is no API for rendering a single cell or a single row.

To apply new configuration options, use updateSettings(). To react to a container that changed size, use refreshDimensions().

For the full rendering model, see the Understanding rendering guide.

Example

hot.setCellMeta(0, 0, 'className', 'my-highlight');
hot.render(); // without this, the class is stored but not visible
// several metadata changes, still a single render
hot.setCellMeta(0, 0, 'className', 'my-highlight');
hot.setCellMeta(1, 0, 'readOnly', true);
hot.render();
// mixed with CRUD operations: batch them, and render inside the callback
hot.batch(() => {
hot.alter('insert_row_above', 5, 45);
hot.setCellMeta(0, 0, 'className', 'my-highlight');
hot.render();
});

repairSelection

Source code

Core~repairSelection(isStructuralChange, indexesChangesState, hadOpenEditor, axis)

Drops a selection that a TRIMMING index map has left pointing at something other than the record it was put on.

A hidden row keeps its place in the visual space, so selection.commit() above is enough for it. A trimmed row leaves that space, so the highlight’s visual coordinate can outlive its record - and a write through such a coordinate makes applyChanges() APPEND records to the data set. Selection#deselectIfHighlightStranded() holds the rule and the reasoning.

TWO changes invalidate the captured record instead of stranding the selection, and both are answered by re-reading it from the visual coordinate, which came through them intact:

  • a STRUCTURAL change (a row or column insert or remove) renumbers the physical space. It raises trimmedIndexesChanged exactly as a filter does, so the flag cannot tell them apart
    • but the SIZE of that space can, since only an insert or a remove changes it. This is the same discrimination EditorManager makes for an open editor.
  • a PERMUTATION (a sort, a row move) rewrites which physical index each visual index maps to while trimming nothing. Left unhandled it does not merely blur the record test, it INVERTS it: after a sort the captured index names a different record, so a healthy selection is dropped and a genuinely stranded one is kept.

An editor changes what this may do, and WHICH editor state matters is the whole subtlety. Two readings are taken, because EditorManager acts between them inside the public hooks:

  • An editor STILL open afterwards was rebound onto its record, and it owns the selection - the pending commit goes through the editor’s own coordinates, and CopyPaste refuses to paste while an editor is open. Nothing here may interfere; moving the selection to follow that editor is a separate change.
  • An editor that was open BEFORE and is gone now was discarded, because the trim took its record away. Nothing owns the selection any more, and the corruption is live again: the highlight outlives the editor and the next paste appends records. So the repair runs - but only against a coordinate that addresses NOTHING. EditorManager deliberately leaves a still-addressable coordinate alone so the next keystroke re-prepares against the record now under the cursor, and a write there lands on a real record rather than appending.
ParamTypeDescription
isStructuralChangebooleanWhether that axis’s physical index count just changed.
indexesChangesStateobjectThe state object of the index mapper’s cache update.
indexesChangesState.trimmedIndexesChangedbooleanWhether the trimmed indexes changed.
indexesChangesState.indexesSequenceChangedbooleanWhether the indexes sequence changed.
hadOpenEditorbooleanWhether an editor was open when the update landed.
axis'row'
'column'
The mapper axis that was updated.

resolveRenderableScrollTarget

Source code

Core~resolveRenderableScrollTarget(row, col) ⇒ Object | false

Resolves renderable row and column indexes for scrolling, accounting for hidden indexes.

ParamTypeDescription
rownumber
undefined
Visual row index.
colnumber
undefined
Visual column index.

Returns: Object | false - Resolved renderable indexes, or false when scrolling target is not reachable.

resolveRowHeightByPhysicalIndex

Source code

Core~resolveRowHeightByPhysicalIndex(option, row) ⇒ number | undefined | null

Resolves one row’s value out of the rowHeights or minRowHeights setting. The function is called with the physical row index, and the array is read at the entry the row was declared at (the physical index at the time of the declaration, kept by RowSizeSettings across row inserts and removals), so a height stays with its row when rows are moved, sorted, trimmed, filtered, collapsed, inserted, or removed. Headers (negative indexes) have no physical index, so they keep the index they were given, and a row outside the index mapper gets no value. A number and a string apply to every row, so they skip the translation.

ParamTypeDescription
optionstringrowHeights or minRowHeights.
rownumberVisual row index.

resumeExecution

Source code

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.

Only the call that ends the outermost Core#suspendExecution call resumes the execution and fires the beforeResumeExecution and afterResumeExecution hooks. A forced nested call (forceFlushChanges) updates the index cache too, and the execution stays suspended. A nested call, a forced nested call, and a call while the execution is not suspended fire nothing. The execution resumes, and afterResumeExecution fires, even when a beforeResumeExecution listener throws. A beforeResumeExecution listener that leaves the execution suspended keeps it suspended: the hook fires again, with afterResumeExecution, on the call that ends it.

With the batchEvaluation setting of the formulas option, the Formulas plugin can batch HyperFormula’s recalculation too, until the execution resumes.

Emits: Hooks#event:beforeResumeExecution, Hooks#event:afterResumeExecution
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
ParamTypeDefaultDescription
[forceFlushChanges]booleanfalseoptional If true, the table internal data cache is recalculated after the execution of the batched operations. For nested Core#batchExecution calls, it can be desire to recalculate the table after each batch.

resumeRender

Source code

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

Source code

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');
ParamTypeDescription
keystringHook 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.

runOperation

Source code

core.runOperation(name, callback, [source]) ⇒ *

Runs the callback as one operation, so every change it makes is recorded as a single user action – for example, one undo step of the UndoRedo plugin. Operations nest: called inside another operation (a batch(), another runOperation(), or a change a hook makes while an edit is applied), the callback joins the outer operation instead of starting its own.

runOperation() neither suspends rendering nor batches the index recalculations. To do that as well, call batch(), which is one operation too.

Since: 19.0.0
Example

// Undoing restores both cells and the removed row in one step
hot.runOperation('import', () => {
hot.setDataAtCell(0, 0, 'A');
hot.setDataAtCell(1, 0, 'B');
hot.alter('remove_row', 5);
}, 'myImport');
ParamTypeDescription
namestringThe operation name. It becomes the actionType of the undo step when the operation is the outermost one.
callbackfunctionThe operation.
[source]stringoptional The operation source, passed to the undo stack hooks.

Returns: * - The value the callback returns.

scrollToFocusedCell

Source code

core.scrollToFocusedCell([callback]) ⇒ boolean

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

Emits: Hooks#event:afterScroll
Since: 14.0.0

ParamTypeDescription
[callback]functionoptional The callback function to call after the viewport is scrolled.

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

scrollViewportTo

Source code

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

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

The object-based signature was introduced in v14.0.0. The positional arguments form is retained for backward compatibility.

// 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
});
// scroll the viewport using the backward-compatible positional arguments form
hot.scrollViewportTo(50, 50, true, true);
ParamTypeDefaultDescription
optionsobjectA dictionary containing the following parameters:
[options.row]numberoptional Specifies the number of visual rows along the Y axis to scroll the viewport.
[options.col]numberoptional Specifies the number of visual columns along the X axis to scroll the viewport.
[options.verticalSnap]'top'
'bottom'
optional Determines to which edge of the table the viewport will be scrolled based on the passed coordinates. This option is a string which must take one of the following values: - top: The viewport will be scrolled to a row in such a way that it will be positioned on the top of the viewport; - bottom: The viewport will be scrolled to a row in such a way that it will be positioned on the bottom of the viewport; - If the property is not defined the vertical auto-snapping is enabled. Depending on where the viewport is scrolled from, a row will be positioned at the top or bottom of the viewport.
[options.horizontalSnap]'start'
'end'
optional Determines to which edge of the table the viewport will be scrolled based on the passed coordinates. This option is a string which must take one of the following values: - start: The viewport will be scrolled to a column in such a way that it will be positioned on the start (left edge or right, if the layout direction is set to rtl) of the viewport; - end: The viewport will be scrolled to a column in such a way that it will be positioned on the end (right edge or left, if the layout direction is set to rtl) of the viewport; - If the property is not defined the horizontal auto-snapping is enabled. Depending on where the viewport is scrolled from, a column will be positioned at the start or end of the viewport.
[options.considerHiddenIndexes]booleantrueoptional 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).
[callback]functionoptional The callback function to call after the viewport is scrolled. The callback runs once per call, unless the grid has no view yet. When nothing is scrolled, including when the row or col index cannot be resolved (it is out of range, or every row or column on that axis is hidden or trimmed), it runs in a microtask right after the call instead of after a scroll.

Returns: boolean - true if viewport was scrolled, false otherwise, including when the grid has no view yet (as inside a hook that fires during initialization).

selectAll

Source code

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

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);
// Select all cells without switching the keyboard focus to Handsontable.
hot.selectAll(true, true, { focusPosition: false }, false);

Since: 0.38.2

ParamTypeDefaultDescription
[includeRowHeaders]booleanfalseoptional If true, includes the row headers in the selection.
[includeColumnHeaders]booleanfalseoptional If true, includes the column headers in the selection.
[options]objectoptional Additional object with options. Since 14.0.0.
[options.focusPosition]Object
CellCoords
boolean
optional The argument allows changing the cell/header focus position. The value takes an object with a row and col properties from -N to N, where negative values point to the headers and positive values point to the cell range. If false, the focus position won’t be changed. When the Options#navigableHeaders option is disabled (the default), a focusPosition that points to a header is relocated to the nearest cell in the data set. Example: js hot.selectAll(0, 0, { focusPosition: { row: 0, col: 1 }, disableHeadersHighlight: true })
[options.disableHeadersHighlight]booleanoptional If true, disables highlighting the headers even when the logical coordinates points on them. This only suppresses the highlight shown on headers of a fully-selected row or column. It doesn’t affect the focus indicator on the individual cell or header that holds the focus, which stays visible even when Options#navigableHeaders moves the focus onto a header.
[changeListener]booleantrueoptional If true, the grid moves the browser focus to the selection’s highlighted cell, as before. Unlike selectCells(), the grid does not start listening. If false, the browser focus stays on an outside input, textarea, select, or contenteditable. A focused button, the document body, or an iframe still loses focus to the highlighted cell.

selectCell

Source code

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);
ParamTypeDefaultDescription
rownumberA visual row index.
columnnumber
string
A visual column index (number), or a column property’s value (string).
[endRow]numberoptional If selecting a range: the visual row index of the last cell in the range.
[endColumn]number
string
optional If selecting a range: the visual column index (or a column property’s value) of the last cell in the range.
[scrollToCell]booleantrueoptional If true, scrolls the viewport to the newly-selected cells. If false, keeps the previous viewport.
[changeListener]booleantrueoptional If true, switches the keyboard focus to Handsontable. If false, keeps the previous keyboard focus. If an element outside Handsontable (such as a custom input) currently owns the browser focus, it remains focused after the call.

Returns: boolean - true: the selection was successful, false: the selection failed, or the grid has no view yet (as inside a hook that fires during initialization).

selectCells

Source code

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

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

You can pass one of the below:

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);
ParamTypeDefaultDescription
coordsArray<Array>
Array<CellRange>
Visual coordinates, passed either as an array of arrays ([[rowStart, columnStart, rowEnd, columnEnd], ...]) or as an array of CellRange objects.
[scrollToCell]booleantrueoptional If true, scrolls the viewport to the newly-selected cells. If false, keeps the previous viewport.
[changeListener]booleantrueoptional If true, switches the keyboard focus to Handsontable. If false, keeps the previous keyboard focus. If an element outside Handsontable (such as a custom input) currently owns the browser focus, it remains focused after the call.

Returns: boolean - true: the selection was successful, false: the selection failed, or the grid has no view yet (as inside a hook that fires during initialization).

selectColumns

Source code

core.selectColumns(startColumn, [endColumn], [focusPosition], [changeListener]) ⇒ 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');
// Select a column without switching the keyboard focus to Handsontable.
hot.selectColumns(1, 1, 0, false);
ParamTypeDefaultDescription
startColumnnumber
string
The visual column index or column property from which the selection starts.
[endColumn]number
string
startColumnoptional The visual column index or column property to which the selection finishes. If endColumn is not defined the column defined by startColumn will be selected.
[focusPosition]number
Object
CellCoords
0optional The argument allows changing the cell/header focus position. The value can take visual row index from -N to N, where negative values point to the headers and positive values point to the cell range. An object with row and col properties also can be passed to change the focus position horizontally.
[changeListener]booleantrueoptional If true, the grid moves the browser focus to the selection’s highlighted cell, as before. Unlike selectCells(), the grid does not start listening. If false, the browser focus stays on an outside input, textarea, select, or contenteditable. A focused button, the document body, or an iframe still loses focus to the highlighted cell.

Returns: boolean - true if selection was successful, false otherwise, including when the grid has no view yet (as inside a hook that fires during initialization).

selectRows

Source code

core.selectRows(startRow, [endRow], [focusPosition], [changeListener]) ⇒ 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 });
// Select a row without switching the keyboard focus to Handsontable.
hot.selectRows(1, 1, 0, false);
ParamTypeDefaultDescription
startRownumberThe visual row index from which the selection starts.
[endRow]numberstartRowoptional The visual row index to which the selection finishes. If endRow is not defined the row defined by startRow will be selected.
[focusPosition]number
Object
CellCoords
0optional The argument allows changing the cell/header focus position. The value can take visual row index from -N to N, where negative values point to the headers and positive values point to the cell range. An object with row and col properties also can be passed to change the focus position vertically.
[changeListener]booleantrueoptional If true, the grid moves the browser focus to the selection’s highlighted cell, as before. Unlike selectCells(), the grid does not start listening. If false, the browser focus stays on an outside input, textarea, select, or contenteditable. A focused button, the document body, or an iframe still loses focus to the highlighted cell.

Returns: boolean - true if selection was successful, false otherwise, including when the grid has no view yet (as inside a hook that fires during initialization).

setCellMeta

Source code

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.

This method updates internal cell metadata only. It does not repaint the grid. To reflect visual changes (such as className, type, or readOnly), call render() afterward. Because this method never renders on its own, several such calls followed by one render() already cost exactly one render. Wrapping them in batch() alone does not repaint the grid: batch() only suppresses renders that other operations would have triggered, so it still needs a render() inside its callback. For why the repaint is a separate step, see the Understanding rendering guide.

An index that lies outside the grid’s current range is not translated – it is used as the physical index as it is. Core#removeCellMeta reads such an index the same way, so a key written past the current range can be removed again by the same coordinates. That holds with nothing trimmed. With rows or columns trimmed (trimRows, a filter), the physical index the raw value names can be a live trimmed record, or a record the grid shows at a different visual index (when the trimmed records sit before it), so such a call writes the key onto that record – pass the visual index of the cell instead.

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

ParamTypeDescription
rownumberVisual row index.
columnnumberVisual column index.
keystringProperty name.
valuestringProperty value.

setCellMetaObject

Source code

core.setCellMetaObject(row, column, prop)

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

ParamTypeDescription
rownumberVisual row index.
columnnumberVisual column index.
propobjectMeta object.

setDataAtCell

Source code

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.

Writing past the last column creates the missing columns only where the grid can create them: an array-of-arrays data source with no columns option and allowInsertColumn left on. With an array data source that cannot grow, the value is still written to the matching array index, so getSourceData() returns it while the grid never displays it.

On an object data source – including one whose dataSchema is a function – that write is deprecated as of 19.0.0 and will be ignored from 20.0.0 on: the value cannot become a column there, so it only adds a property the schema never declared. A one-time console warning says so. To write a field the grid shows no column for, address it by property name with setDataAtRowProp() instead. A grid that declares no columns at all is exempt – there every index is past the last column, and writing is how an empty dataset gets bootstrapped.

Avoid calling this method unconditionally from inside a renderer function. Changing a cell’s data triggers Handsontable to re-render, which can re-invoke the same renderer and create an infinite loop. If you need to update data from within a renderer, guard the call (for example, skip it when the new value already equals the current one), or, preferably, perform the update in a data-change hook such as Hooks#afterChange and keep the renderer display-only.

Emits: Hooks#event:beforeChange, Hooks#event:afterChange

ParamTypeDescription
rownumber
Array
Visual row index or array of changes in format [[row, col, value],...].
[column]numberoptional Visual column index.
[value]stringoptional New value.
[source]stringoptional String that identifies how this change will be described in the changes array (useful in Hooks#afterChange or Hooks#beforeChange callbacks). Set to ‘edit’ if left empty.

setDataAtCell

Source code

Core~setDataAtCell(row, [column], [value], [source])

The body of setDataAtCell, run inside its operation.

ParamTypeDescription
rownumber
Array
Visual row index or array of changes in format [[row, col, value],...].
[column]numberoptional Visual column index.
[value]stringoptional New value.
[source]stringoptional String that identifies how this change will be described in the changes array.

setDataAtRowIdProp

Source code

core.setDataAtRowIdProp(id, prop, value, [source]) ⇒ boolean

Sets a value in the row that has the given id, wherever the row is now. If no row has the id (for example, the row was removed), it does nothing.

For a visible row (one with a visual index, hidden rows included), it works like setDataAtRowProp(). For a row that is trimmed or filtered out, it writes to the source data with setSourceDataAtCell(), so the value is not validated and afterChange does not fire for it.

Since: 19.0.0

ParamTypeDescription
id*The row’s id.
propstring
number
The property name, or the physical column index of a row array.
value*The new value.
[source]stringoptional The source of the change, passed on to the hooks.

Returns: boolean - true when a row has the id and the value was set, false otherwise.

setDataAtRowProp

Source code

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.

Emits: Hooks#event:beforeChange, Hooks#event:afterChange

ParamTypeDescription
rownumber
Array
Visual row index or array of changes in format [[row, prop, value], ...].
propstringProperty name or the source string (e.g. 'first.name' or '0').
valuestringValue to be set.
[source]stringoptional String that identifies how this change will be described in changes array (useful in Hooks#afterChange or Hooks#beforeChange callbacks).

setDataAtRowProp

Source code

Core~setDataAtRowProp(row, prop, value, [source])

The body of setDataAtRowProp, run inside its operation.

ParamTypeDescription
rownumber
Array
Visual row index or array of changes in format [[row, prop, value], ...].
propstringProperty name or the source string.
valuestringValue to be set.
[source]stringoptional String that identifies how this change will be described in changes array.

setSourceDataAtCell

Source code

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

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

This method fires afterSetSourceDataAtCell. It doesn’t fire beforeChange or afterChange, so a custom source never reaches those two hooks. To pass a custom source to afterChange, use setDataAtCell() or setDataAtRowProp().

The hook also lists a change that the sourceDataValidator rejects. When allowInvalid is false, the grid doesn’t store that value, but the changes array of the hook still lists it.

An open editor keeps what the user typed, unless the call writes the edited cell itself: then the editor shows the new value.

Note: this method takes physical row and column indexes. Core#setDataAtCell takes a visual row and a visual column, and Core#setDataAtRowProp takes a visual row. Swapping one call for the other with the same numbers can write to a different row when the grid is sorted or filtered. To translate an index, use Core#toVisualRow or Core#toVisualColumn. A trimmed row has no visual index, so neither of those two methods can write it.

Emits: Hooks#event:afterSetSourceDataAtCell

ParamTypeDescription
rownumber
Array
Physical row index or array of changes in format [[row, prop, value], ...].
columnnumber
string
function
Physical column index, prop name, or a columns[].data accessor function (called as accessor(rowObject, value)).
value*The value to be set at the provided coordinates.
[source]stringoptional Source of the change as a string. The method passes it to the afterSetSourceDataAtCell hook. In the array form, pass it as the fourth argument (setSourceDataAtCell(changes, undefined, undefined, source)): a source in the second argument only reaches the undo step, and the hook gets undefined.

setSourceDataAtCell

Source code

Core~setSourceDataAtCell(row, column, value, [source])

The body of setSourceDataAtCell, run inside its operation.

ParamTypeDescription
rownumber
Array
Physical row index or array of changes in format [[row, prop, value], ...].
columnnumber
string
function
Physical column index, prop name, or a columns[].data accessor.
value*The value to be set at the provided coordinates.
[source]stringoptional Source of the change as a string.

shouldRestoreSelection

Source code

Core~shouldRestoreSelection(indexesChangesState) ⇒ boolean

Tells whether an update is a PURE TRIM, which is the only shape the physical selection snapshot can be restored across. Trimming only removes records, so the survivors of a rectangular range stay contiguous and a CellRange still describes them; a permutation can scatter them.

ParamTypeDescription
indexesChangesStateobjectThe state object of the index mapper’s cache update.
indexesChangesState.indexesSequenceChangedbooleanWhether the indexes sequence changed.
indexesChangesState.trimmedIndexesChangedbooleanWhether the trimmed indexes changed.

shrinkAxis

Source code

Core~shrinkAxis(axisState)

Gives back the filler rows or columns at the end of one axis that its lowered minimum sizes no longer require. Does nothing when neither of that axis’s two options was lowered.

ParamTypeDescription
axisStateobjectThe axis, its current state, and its minimum sizes before and after the update.
axisState.axisstringThe axis to shrink, 'row' or 'column'.
axisState.getCountfunctionGives the number of rows or columns on the axis.
axisState.getNotTrimmedCountfunctionGives the number of rows or columns left by the trimming maps.
axisState.isEmptyfunctionAnswers whether the row or column at a visual index is empty.
axisState.isRemovablefunctionAnswers whether the row or column at a visual index is a filler.
axisState.previousMinimumnumberThe minRows/minCols value before the update.
axisState.previousSparenumberThe minSpareRows/minSpareCols value before the update.
axisState.minimumnumberThe minRows/minCols value after the update.
axisState.sparenumberThe minSpareRows/minSpareCols value after the update.

spliceCellsMeta

Source code

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

ParamTypeDefaultDescription
visualIndexnumberA visual index that specifies at what position to add/remove items.
[deleteAmount]number0optional The number of items to be removed. If set to 0, no cell meta objects will be removed.
[…cellMetaRows]objectoptional The new cell meta row objects to be added to the cell meta collection.

spliceCol Deprecated

Source code

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

Deprecated. Adds/removes data from the column. This method works the same as Array.splice for arrays.
ParamTypeDescription
columnnumberIndex of the column in which do you want to do splice.
indexnumberIndex at which to start changing the array. If negative, will begin that many elements from the end.
amountnumberAn integer indicating the number of old array elements to remove. If amount is 0, no elements are removed.
[…elements]numberoptional 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 Deprecated

Source code

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

Deprecated. Adds/removes data from the row. This method works the same as Array.splice for arrays.
ParamTypeDescription
rownumberIndex of column in which do you want to do splice.
indexnumberIndex at which to start changing the array. If negative, will begin that many elements from the end.
amountnumberAn integer indicating the number of old array elements to remove. If amount is 0, no elements are removed.
[…elements]numberoptional The elements to add to the array. If you don’t specify any elements, spliceCol simply removes elements from the array.

Returns: Array - Returns removed portion of rows.

suspendExecution

Source code

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.

Calls nest. Only the outermost call suspends the execution and fires the beforeSuspendExecution and afterSuspendExecution hooks. When an afterSuspendExecution listener throws, the method resumes the execution (firing the resume hooks) and rethrows the error. A call a beforeSuspendExecution or beforeResumeExecution listener makes on the same instance fires no hooks.

With the batchEvaluation setting of the formulas option, the Formulas plugin can batch HyperFormula’s recalculation too, but a render in between still recalculates.

Emits: Hooks#event:beforeSuspendExecution, Hooks#event:afterSuspendExecution
Since: 8.3.0
Example

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

suspendRender

Source code

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

toCellMetaPhysicalCoords

Source code

Core~toCellMetaPhysicalCoords(row, column) ⇒ Array<number>

Translates the visual coordinates a cell meta mutator receives into the physical ones the meta manager stores under. An index inside the grid’s current range is translated through the index mappers; an index outside it is used as the physical index as it is, so a key written past the current range can be read and removed again by the same coordinates. Core#setCellMeta, Core#removeCellMeta and _setCellMetaDeclarative all resolve their coordinates here, so a change to the rule (for example for trimmed rows) reaches every one of them.

ParamTypeDescription
rownumberVisual row index, or a raw index past the current range.
columnnumberVisual column index, or a raw index past the current range.

Returns: Array<number> - The [physicalRow, physicalColumn] pair.

toHTML

Source code

core.toHTML() ⇒ string

Converts instance into outerHTML of HTMLTableElement.

Since: 7.1.0

toPhysicalColumn

Source code

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.

ParamTypeDescription
columnnumberVisual column index.

Returns: number - Returns physical column index.

toPhysicalRow

Source code

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.

ParamTypeDescription
rownumberVisual row index.

Returns: number - Returns physical row index.

toTableElement

Source code

core.toTableElement() ⇒ HTMLTableElement

Converts instance into HTMLTableElement.

Since: 7.1.0

toVisualColumn

Source code

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.

ParamTypeDescription
columnnumberPhysical column index.

Returns: number - Returns visual column index.

toVisualRow

Source code

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.

ParamTypeDescription
rownumberPhysical row index.

Returns: number - Returns visual row index.

unlisten

Source code

core.unlisten()

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

updateData

Source code

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) (updateSettings({ data, columns }) is the exception: it resets them when the columns changed, see Core#updateSettings)
  • Keeps the sorted row order and the trimmed rows. It does not sort or filter the new values again. To apply them, call sort(getSortConfig()) of the ColumnSorting or MultiColumnSorting plugin, or filter() of the Filters plugin.
  • Clears the undo and redo history of the UndoRedo plugin, unless data is what the grid shows already: the same array, a copy of it, or rows that hold the same values. Cells are compared with ===, so a nested object that was copied counts as another value, and a copy of the array clears the history when the NestedRows plugin is on.

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

A change that still waits for its cell’s validator is written at its row and column of the new data when the validator answers, so pass the same records the grid shows. A data update through updateSettings() runs updateData() too. To replace the records and drop such a change, use loadData().

Read more:

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

ParamTypeDescription
dataArrayAn array of arrays, or an array of objects, that contains Handsontable’s data.
[source]stringoptional The source of the updateData() call.

updateSettings

Source code

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

Passing columns inside the settings object resets the states corresponding to rows and columns (for example, row/column sequence, column width, row height, frozen columns etc.). Passing data does not reset these states, with one exception: when the same call changes the column layout through columns, the column states (width, hiding, order, sort) start over. Adding columns to the end, or removing them from the end, keeps the states of the other columns. Rows keep theirs.

After initialization, passing data calls updateData() internally. The resulting beforeUpdateData and afterUpdateData hooks receive "updateSettings" as their source, while afterChange receives null as its changes argument and "updateData" as its source. If you call updateSettings with data inside afterChange, check the hook’s source to prevent an infinite loop.

Cell meta is preserved across updateSettings, even when settings includes cell, cells, or columns. This covers both meta set imperatively through Core#setCellMeta (for example, by the user or the context menu) and meta applied from the declarative cell option on an earlier call. Preserved meta stays with its row, so it follows sorting and row moves.

Passing cell restates the option: it replaces every previously declared entry, so cell: [] removes them all. On a direct conflict, a value re-stated through cell takes precedence over the preserved value. Where cell is not passed, an imperative Core#setCellMeta made after the declaration wins.

A failed validation result is preserved as well, so a cell marked invalid keeps its htInvalid class across updateSettings. To reset the validation state, use loadData() or validate the cells again.

A hook function passed in settings replaces the function that earlier settings passed for the same hook. An array of callbacks is added beside the callbacks earlier settings passed. A hook set to null removes every callback that settings passed for it and leaves null in Core#getSettings. A hook set to undefined is left as it is. Listeners added with Core#addHook are not affected by either.

The legacy fixedColumnsLeft option is applied as fixedColumnsStart, while the settings object that afterUpdateSettings receives keeps the name you passed. Passing both names in one call throws an error. When you pass them in separate calls, the later value applies.

Four options can only be set at initialization: ariaTags, layoutDirection, renderAllColumns, and renderAllRows. A call whose settings names any of them throws an error, even when you didn’t set the option at initialization. The call is refused as a whole: it applies none of its other options. The check looks at the top-level keys only, so one of these options inside columns or cell throws only once it is written, after the options in front of it were applied.

This method reinitializes the affected plugins and then renders, so it does more work than a plain render(). When only cell metadata changed, call render() instead. See the Understanding rendering guide.

When settings includes data, loading the data does not paint the grid on its own. Rendering is held while the data loads, so afterUpdateData and afterChange run with isRenderSuspended() returning true. The grid paints after the settings are applied, so afterUpdateSettings also runs before that paint. Use afterRender to read the new cells.

When Hooks#hasExternalDataSource is true, Handsontable clears and rebinds the placeholder dataset only during initialization or when settings replaces dataProvider with another value. A data value is ignored with a warning and keeps the loaded rows, and so does the same dataProvider object passed again; to reload the rows, call fetchData(). Other keys alone (for example height) keep the loaded rows and send no request. pagination, columnSorting, filters, or columns, with or without dataProvider, reset the page, sort, or filters they hold, so the rows are fetched again; a columns value sent without dataProvider also clears the sort.

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

hot.updateSettings({
contextMenu: true,
colHeaders: true,
fixedRowsTop: 2
});
ParamTypeDefaultDescription
settingsobjectA settings object (see Options). Only provide the settings that are changed, not the whole settings object that was used for initialization.
[init]booleanfalseoptional Internally used during initialization.

useTheme

Source code

core.useTheme(themeName)

Use the theme specified by the provided name.

When the grid runs a theme object (the theme option set to a theme config or a ThemeBuilder instance) and you pass a different valid theme name, the grid stops using the theme object: its injected styles and icon mapping are removed, and later changes to the theme object no longer affect the grid. A value that is not a valid theme name (ht-theme-<theme-name>) is rejected with a warning, and the grid keeps its current theme, theme object included.

Since: 15.0.0

ParamTypeDescription
themeNamestring
boolean
undefined
The name of the theme to use.

validateAndApplyChanges

Source code

Core~validateAndApplyChanges(changes, [source], loadGeneration)

Validates the changes and applies the ones that pass. An asynchronous validator answers after the operation that made the change has returned, so the operation’s transaction is held until the changes land – they are part of the same user action. validateChanges calls back once every validator has answered, including when every change is rejected; when it throws before that (a beforeValidate listener that throws), it never calls back and the hold is released here.

The changes address the data the grid held when they were made. When a loadData() replaces that data before the last validator answers, the changes are dropped: written now, they would land in the loaded rows at the same coordinates, which usually hold other records. The generation is read by the caller before beforeChange, so a load from a listener of the write’s own hooks drops the set too, and a validator’s correction carries the generation of the validation that wrote it (getChangeLoadGeneration()). The validation hooks still fire for them, afterChange does not. updateData() does not count as a replacement, because the wrappers call it with the same records in a new array, often while an edit is waiting. The functions _addDroppedChangesListener() added are told about a dropped set, in the order they were added, with the same array the other change hooks received and the changes a validator rejected under allowInvalid: false, which were taken out of that array.

ParamTypeDescription
changesArrayThe processed changes.
[source]stringoptional The change source.
loadGenerationnumberThe validationLoadGeneration the changes were made against.

validateCell

Source code

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

Validate a single cell.

ParamTypeDescription
valuestring
number
The value to validate.
cellPropertiesobjectThe cell meta which corresponds with the value.
callbackfunctionThe callback function.
sourcestringThe string that identifies source of the validation.

validateCells

Source code

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 or filtered, as such cells are not included in the data set until you bring them back again.

Does validate rows hidden with HiddenRows and columns hidden with HiddenColumns. Those cells stay in the data set.

An autocomplete, dropdown, or multiselect cell is validated on the value it stores, the same value an edit validates. A valueGetter you configure yourself is applied first, as before.

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
}
})
ParamTypeDescription
[callback]functionoptional The callback function.

validateColumns

Source code

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.

An autocomplete, dropdown, or multiselect cell is validated on the value it stores, the same value an edit validates. A valueGetter you configure yourself is applied first, as before.

Example

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

validateRows

Source code

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.

An autocomplete, dropdown, or multiselect cell is validated on the value it stores, the same value an edit validates. A valueGetter you configure yourself is applied first, as before.

Example

hot.validateRows([3, 4, 5], (valid) => {
if (valid) {
// ... code for validated rows
}
})
ParamTypeDescription
[rows]Arrayoptional Array of validation target visual row indexes.
[callback]functionoptional The callback function.

writeCellMetaChange

Source code

Core~writeCellMetaChange(physicalRow, physicalColumn, key, write)

Runs one cell meta write and journals it when a transaction records. Only an imperative write is journaled – one made while a cell-option or plugin-declarative scope is open is configuration being applied, not a user action. The values are kept by reference: a meta value can be a function or a class instance (a renderer, an editor) whose identity matters, and meta values are replaced, not mutated in place.

ParamTypeDescription
physicalRownumberThe physical row index.
physicalColumnnumberThe physical column index.
keystringThe meta key.
writefunctionThe write.

writeChange

Source code

Core~writeChange(visualRow, prop, value, run, [recordRow])

Writes one change into the data set, and journals it when a transaction records.

ParamTypeDescription
visualRownumberThe visual row index.
propstring
number
The column property.
value*The value to write.
runReversedCellRunThe writeChangesToData() call the write belongs to.
[recordRow]numberoptional The physical row of the record a change that waited for its validator was resolved to. The write goes to that row, whatever visual row (or none, for a trimmed record) it has.

writeSourceChange

Source code

Core~writeSourceChange(row, prop, value, [byProp])

Writes one value into the source data, and journals it when a transaction records.

ParamTypeDefaultDescription
rownumber
string
The physical row index (a numeric string is accepted, as setAtCell does).
propnumber
string
function
The physical column index, the prop name, or a columns[].data accessor.
value*The value to write.
[byProp]booleanfalseoptional true to write a numeric prop as the key it names, past the columns the first row declares (see DataSource#setAtCell).

writeValue

Source code

Core~writeValue(visualRow, prop, value, [recordRow])

Writes one value into the data set: by the visual row, or by the physical row of the record a change that waited for its validator was resolved to.

ParamTypeDescription
visualRownumberThe visual row index.
propstring
number
The column property.
value*The value to write.
[recordRow]numberoptional The physical row of the record, for a change that waited for its validator.