Configuration options
Description
Setting options let you heavily customize your Handsontable instance. For example, you can:
- Enable and disable built-in features
- Enable and configure additional plugins
- Personalize Handsontable DataGrid’s look
- Adjust Handsontable’s behavior
- Implement your own custom features
settings = { data: [ ["A1", "B1", "C1", "D1", "E1"], ["A2", "B2", "C2", "D2", "E2"], ["A3", "B3", "C3", "D3", "E3"], ["A4", "B4", "C4", "D4", "E4"], ["A5", "B5", "C5", "D5", "E5"], ], width: 400, height: 300, colHeaders: true, rowHeaders: true, customBorders: true, dropdownMenu: true, multiColumnSorting: true, filters: true, manualRowMove: true,};<hot-table [settings]="settings" />Depending on your needs, you can apply configuration options to different elements of your grid:
- The entire grid
- Individual columns
- Individual rows
- Individual cells
- Individual grid elements, based on any logic you implement
Read more:
Members
activeHeaderClassName
Can be set at: grid
options.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:
currentRowClassNamecurrentColClassNamecurrentHeaderClassNameinvalidCellClassNamereadOnlyCellClassNamecommentedCellClassNamenoWordWrapClassNameTableClassNameclassName
Default: “ht__active_highlight”
Category: Core
Since: 0.38.2
Example
// add an `ht__active_highlight` CSS class name// to every currently-active, currently-selected headeractiveHeaderClassName: 'ht__active_highlight',allowEmpty
Can be set at: grid columns cells cell
options.allowEmpty : boolean
The allowEmpty option determines whether Handsontable accepts the following values:
nullundefined''
You can set the allowEmpty option to one of the following:
| Setting | Description |
|---|---|
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
Category: Core
Example
// allow empty values in each cell of the entire gridallowEmpty: true,
// orcolumns: [ { 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` optioncells(row, col) { if (col === 2) { return { allowEmpty: false }; }},allowHtml
Can be set at: grid columns cells cell
options.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:
| Setting | Description |
|---|---|
false (default) | The source data is not treated as HTML |
true | The 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
Category: Core
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
options.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_rightpasteModethe 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.
setDataAtCell()andsetDataAtRowProp()no longer create the missing columns when you write past the last column. The write still reaches the source data, sogetSourceData()returns the value while the grid never displays it. This bullet applies only when yourdatais an array of arrays and you do not set thecolumnsoption – 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
alter()method, including itsinsert_col_startandinsert_col_endactions. - The
minColsandminSpareColsoptions. Both are themselves skipped when thecolumnsoption is set, andminSpareColsalso requiresdatato be an array of arrays. - Undo and redo.
- Pressing Enter at the last column, when
minSpareColsis above0andenterMovesis set to move the column. The defaultenterMovesmoves 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
Category: Core
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
options.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_downpasteModethe 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
fillHandleoption’sautoInsertRowsetting has already appended rows to take it – see the next list. setDataAtCell()andsetDataAtRowProp()do not create the missing rows when you write below the last row. Both currently throw aTypeErrorin that case, so guard the call, or keep the row index withincountRows().
The option does not stop these ways of adding rows:
- The
alter()method, including itsinsert_row_aboveandinsert_row_belowactions. - The
minRowsandminSpareRowsoptions. - Undo and redo.
- The fill handle appending rows when you drag it below the last row. That is governed solely by the
fillHandleoption’sautoInsertRowsetting, which ignoresallowInsertRow. It applies only when you setfillHandleexplicitly – left unset, the grid does not append rows this way. - Pressing Enter at the last row, when
minSpareRowsis above0. 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
Category: Core
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
options.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:
| Setting | Description |
|---|---|
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
Category: Core
Example
// don't accept `invalid` values// don't allow the user to close the cell editor// don't save `invalid` values into the data sourceallowInvalid: false,allowRemoveColumn
Can be set at: grid
options.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
Category: Core
Example
// hide the 'Remove column' menu item from the context menu and the column menuallowRemoveColumn: false,allowRemoveRow
Can be set at: grid
options.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
Category: Core
Example
// hide the 'Remove row' menu item from the context menuallowRemoveRow: false,applyCellsToDataReads
Can be set at: grid columns
options.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
Category: Core
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
options.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
Category: Core
Since: 14.0.0
Example
// turn the ARIA roles and attributes off (default: true)ariaTags: false,asyncValues
Can be set at: grid
options.asyncValues : boolean | object
The asyncValues option configures the AsyncValues plugin, which
computes cell values asynchronously, from promises, and shows a pending and an error state per
cell.
You can set the asyncValues option to one of the following:
| Setting | Description |
|---|---|
false (default) | Disable the AsyncValues plugin |
true | Enable the AsyncValues plugin with the defaults |
| An object | Enable the AsyncValues plugin and configure it |
If you set the asyncValues option to an object, you can configure the following settings:
| Setting | Possible values | Description |
|---|---|---|
flush | 'microtask' (default), 'frame', or a number | When settled requests are written: right after the task they settled in, once per animation frame, or after a number of milliseconds that collects results |
concurrency | A number (default: 6), or Infinity | The maximum number of sources running at once (a batch counts as one); further requests stay pending until a slot frees |
copyPendingAs | 'previous' (default) or 'empty' | What copying a pending cell puts on the clipboard |
saveToDataProvider | false (default) or true | Saves each resolved value through the dataProvider onRowsUpdate callback, one updateRows() call per flush |
The plugin can’t be enabled together with the nestedRows option, because NestedRows
moves rows without keeping their physical indexes.
Read more:
Default: false
Category: AsyncValues
Since: 19.0.0
Example
// enable the `AsyncValues` pluginasyncValues: true,
// write results once per animation frame, and run at most four requests at onceasyncValues: { flush: 'frame', concurrency: 4,},autoColumnSize
Can be set at: grid
options.autoColumnSize : object | boolean
The autoColumnSize option configures the AutoColumnSize plugin.
You can set the autoColumnSize option to one of the following:
| Setting | Description |
|---|---|
false | Disable the AutoColumnSize plugin |
true | Enable the AutoColumnSize plugin with the default configuration |
| An object | Enable the AutoColumnSize plugin and modify the plugin options |
If you set the autoColumnSize option to an object, you can set the following AutoColumnSize plugin options:
| Property | Possible values | Description |
|---|---|---|
syncLimit | A number | A percentage string | The number/percentage of columns to keep in sync (default: 50) |
useHeaders | true | false | When calculating column widths:true: use column headersfalse: don’t use column headers |
samplingRatio | A number | The number of samples of the same length to be used in column width calculations |
allowSampleDuplicates | true | false | When calculating column widths:true: Allow duplicate samplesfalse: Don’t allow duplicate samples |
By default, the autoColumnSize option is set to undefined,
but the AutoColumnSize plugin acts as enabled.
To disable the AutoColumnSize plugin completely,
set the autoColumnSize option to false.
Using the colWidths option forcibly disables the AutoColumnSize plugin.
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
Category: AutoColumnSize
Example
autoColumnSize: { // keep 40% of columns in sync (the rest of columns: async) syncLimit: '40%', // when calculating column widths, use column headers useHeaders: true, // when calculating column widths, use 10 samples of the same length samplingRatio: 10, // when calculating column widths, allow duplicate samples allowSampleDuplicates: true},autoLink
Can be set at: grid columns cells cell
options.autoLink : boolean | object
The autoLink option configures the AutoLink plugin, which renders the
URLs found in cell values as clickable links.
You can set the autoLink option to one of the following:
| Setting | Description |
|---|---|
false (default) | Disable the AutoLink plugin |
true | Enable the AutoLink plugin with the default settings |
| An object | Enable the AutoLink plugin and configure its settings |
If you set the autoLink option to an object, you can configure the following settings:
| Option | Possible settings | Description |
|---|---|---|
target | '_blank' (default) | '_self' | Where the links open |
schemes | An array of 'http', 'https', 'mailto', 'tel' (default: all four) | The URL schemes to link. Narrows the fixed four-scheme allowlist, never widens it. A column or cell schemes replaces the grid-level list for those cells. |
inline | true (default) | false | true: link URLs inside longer textfalse: link only a cell whose whole value is one URL |
strict | true (default) | false | true: link only URLs that carry a schemefalse: also link bare domains (example.com) as https and bare email addresses as mailto, validated against the IANA top-level domain list bundled with Handsontable |
className | A string (default: '') | Extra class name(s) added to every link |
The full IANA top-level domain list is used, so a file name whose extension is also a
top-level domain, such as report.zip or README.md, links too. Keep the default unless your
data holds bare domains or email addresses, and keep strict: true or set autoLink: false on
columns that hold file names. The bundled list is fixed at build time - Handsontable makes no
network request to validate a bare domain, which keeps strict: false usable in an
air-gapped environment. Punycode top-level domains (xn--...) are skipped, since nobody types
those into a cell.
The cell keeps its own renderer and its value stays unchanged, so copying, autofill, sorting,
and export are unaffected. Every link element gets the ht-link and ht-auto-link classes,
and always carries rel="noopener noreferrer". Press Alt+Enter
to open the first link of the selected cell.
For mailto: and tel: links, the scheme prefix is wrapped in a ht-link-scheme element and
hidden, so the cell shows only the address or the number. The cell value and the link target
keep the prefix.
Only the http, https, mailto, and tel schemes are ever linked. A cell that already
contains a link element, such as a HYPERLINK cell rendered through
formulas.hyperlinks or an html cell holding an anchor, is left as it is.
The plugin is enabled at the grid level. Set autoLink: false for a column or a cell to opt it
out, or set an object to override the grid-level settings for that column or cell.
Read more:
Default: false
Category: AutoLink
Since: 19.0.0
Example
// link every URL, email address and phone number found in cell valuesautoLink: true,
// open links in the same tab, link web URLs only, and add a class to every linkautoLink: { target: '_self', schemes: ['http', 'https'], className: 'company-link',},
// also link bare domains (as `https`) and bare email addresses (as `mailto`)autoLink: { strict: false,},
// enable the plugin, but keep one column as plain textautoLink: true,columns: [ { data: 'website' }, { data: 'notes', autoLink: false },],autoRowHeaderSize
Can be set at: grid
options.autoRowHeaderSize : object | boolean
The autoRowHeaderSize option configures the AutoRowHeaderSize plugin.
The plugin sizes the row header column to its widest label, the way
AutoColumnSize sizes a data column to its widest cell. Turning it
on is all you need: it takes the row header’s width over, so any
rowHeaderWidth already set is ignored while the plugin is enabled.
You can set the autoRowHeaderSize option to one of the following:
| Setting | Description |
|---|---|
false | Disable the AutoRowHeaderSize plugin |
true | Enable the plugin with the default configuration |
| An object | Enable the plugin and modify its options |
If you set the autoRowHeaderSize option to an object, you can set the following options:
| Property | Possible values | Description |
|---|---|---|
samplingRatio | A number | The number of samples of the same label length used in the measurement (default: 3) |
allowSampleDuplicates | true | false | When two rows carry the same label:true: measure bothfalse: measure it once(default: false) |
syncLimit | A number | a percent string | How many rows are read before the first paint; the rest are read in idle time (default: 500) |
By default, the autoRowHeaderSize option is set to undefined, which disables the plugin.
Finding the longest label means reading every row header once. On a large grid that work is
split: the first syncLimit rows are read before the first paint, and the rest are read in
the browser’s idle time, so a header can widen a moment after the grid appears. While that is
running a header only ever widens, so its width never jumps back and forth. The result is
cached, so later draws cost nothing.
Editing a cell does not re-read the whole grid. Only the rows that changed are read, because
a row header label can be built from cell values, and that reading waits for an idle moment
too. It can make a header wider, but never narrower: a header shrinks again on the next full
pass, which is started by loading or replacing the data, adding or removing a row, sorting,
hiding or showing a row, switching the theme, or a recalculation by the
Formulas plugin.
A grid can render more than one row header, by pushing a renderer through the
afterGetRowHeaderRenderers hook. Every one of
them is measured on its own, so each gets exactly the width its own labels need.
The measured width leaves a little room around the longest label, so the text never sits flush
against the cell border. The grid’s own row header renderer wraps its label in a padded
element, but a renderer pushed through
afterGetRowHeaderRenderers writes straight into
the cell and has none of its own.
Two rows carrying the same label are measured once, since the same text renders to the same
width. Set allowSampleDuplicates to true when that is not true of your grid - a row header
that is indented per row, as nestedRows does, renders the same label at a
different width depending on its depth. Raise samplingRatio along with it: labels are
grouped by length and only samplingRatio of each group are measured, so with the default of
3 a fourth copy of the same label is still left out, however deep it sits.
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
Category: AutoRowHeaderSize
Since: 19.0.0
Example
// size the row header column to its longest labelautoRowHeaderSize: true,
// the same, with the measurement tunedautoRowHeaderSize: { // measure repeated labels too, for headers that render differently per row allowSampleDuplicates: true,},autoRowSize
Can be set at: grid
options.autoRowSize : object | boolean
The autoRowSize option configures the AutoRowSize plugin.
You can set the autoRowSize option to one of the following:
| Setting | Description |
|---|---|
false | Disable the AutoRowSize plugin |
true | Enable the AutoRowSize plugin with the default configuration |
| An object | Enable the AutoRowSize plugin and modify the plugin options |
To give Handsontable’s scrollbar a proper size, set the autoRowSize option to true.
If you set the autoRowSize option to an object, you can set the following AutoRowSize plugin options:
| Property | Possible values | Description |
|---|---|---|
syncLimit | A number | A percentage string | The number/percentage of rows to keep in sync (default: 500) |
samplingRatio | A number | The number of samples of the same length to be used in row height calculations |
allowSampleDuplicates | true | false | When calculating row heights:true: Allow duplicate samplesfalse: Don’t allow duplicate samples |
Unlike colWidths, which switches AutoColumnSize
off, the rowHeights option does not disable this plugin. A height set
through rowHeights acts as a minimum: the plugin still measures the row, and a row whose
content is taller than that keeps its measured height. A column can be narrower than its
content and clip it, but a row that is shorter than its content would hide the content, so
rows only ever grow.
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
Category: AutoRowSize
Example
autoRowSize: { // keep 40% of rows in sync (the rest of rows: async) syncLimit: '40%', // when calculating row heights, use 10 samples of the same length samplingRatio: 10, // when calculating row heights, allow duplicate samples allowSampleDuplicates: true},autoWrapCol
Can be set at: grid
options.autoWrapCol : boolean
| Setting | Description |
|---|---|
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. |
true | 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. |
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
Category: Core
Example
// when you select a bottom-most cell, pressing ⬇ doesn't do anything// when you select a top-most cell, pressing ⬆ doesn't do anythingautoWrapCol: 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 columnautoWrapCol: true,autoWrapRow
Can be set at: grid
options.autoWrapRow : boolean
| Setting | Description |
|---|---|
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. |
true | 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. |
* 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
Category: Core
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 anythingautoWrapRow: 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 belowautoWrapRow: true,bindRowsWithHeaders
Can be set at: grid
options.bindRowsWithHeaders : boolean | string
The bindRowsWithHeaders option configures the BindRowsWithHeaders plugin.
When enabled, each row stays permanently linked to its row header label, regardless of row sorting or row moving. Normally, row headers display the visual row index and update as rows are reordered; with this plugin enabled, the header travels with the data row it was originally assigned to.
You can set the bindRowsWithHeaders option to one of the following:
| Setting | Description |
|---|---|
false | Disable the the BindRowsWithHeaders plugin |
true | Enable the the BindRowsWithHeaders plugin |
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: undefined
Category: BindRowsWithHeaders
Example
// enable the `BindRowsWithHeaders` pluginbindRowsWithHeaders: truecell
Can be set at: grid
options.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: []
Category: Core
Example
// set the `cell` option to an array of objectscell: [ // make the cell with coordinates (0, 0) read-only { row: 0, col: 0, readOnly: true }],cells
Can be set at: grid
options.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:
- Any
updateSettings()call that carriescells,cell, orcolumns. In React, that happens when you passcellsas a new function. - A
loadData()call.updateData()andupdateSettings({ 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 thecelloption, and cells marked invalid, keep their meta. Horizontal scrolling doesn’t reset it.
cells takes the following parameters:
| Parameter | Required | Type | Description |
|---|---|---|---|
row | Yes | Number | A physical row index |
column | Yes | Number | A physical column index |
prop | No | String | Number | If 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
Category: Core
Example
// set the `cells` option to your custom functioncells(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
options.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:
| Setting | Description |
|---|---|
true (default) | If a checkbox cell is checked,the getDataAtCell method for this cell returns true |
| A string | If 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
Category: Core
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
options.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:
| Setting | Description |
|---|---|
| A string | Add a single CSS class name to every matching cell |
| An array of strings | Add 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:
| Level | Container element | Cells |
|---|---|---|
| Grid | Yes | Every cell |
columns | No | Cells of that column |
cells or cell | No | The 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:
- Setting options: Cascading configuration
currentRowClassNamecurrentColClassNamecurrentHeaderClassNameactiveHeaderClassNameinvalidCellClassNameplaceholderCellClassNamecommentedCellClassNamenoWordWrapClassNamereadOnlyCellClassNameTableClassName
Default: undefined
Category: Core
Example
// add a `your-class-name` CSS class name to every cellclassName: 'your-class-name',
// add `first-class-name` and `second-class-name` CSS class names to every cellclassName: ['first-class-name', 'second-class-name'],colHeaders
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
true | Enable the default column headers (‘A’, ‘B’, ‘C’, …) |
false | Disable column headers |
| An array | Define your own column headers (e.g. ['One', 'Two', 'Three', ...]) |
| A function | Define 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
Category: Core
Example
// enable the default column headerscolHeaders: true,
// set your own column headerscolHeaders: ['One', 'Two', 'Three'],
// set your own column headers, using a functioncolHeaders: function(physicalColumnIndex) { return `${physicalColumnIndex} + : AB`;},collapsibleColumns
Can be set at: grid
options.collapsibleColumns : boolean | Array<object>
The collapsibleColumns option configures the CollapsibleColumns plugin.
You can set the collapsibleColumns option to one of the following:
| Setting | Description |
|---|---|
false | Disable the CollapsibleColumns plugin |
true | Enable the CollapsibleColumns plugin |
| An array of objects | Enable the CollapsibleColumns plugin for selected column headers |
When using an array of objects, specify the header to make collapsible using row and col.
The row value is a negative integer that counts header levels from the bottom of the header area:
-1 is the header row closest to the data, -2 is one level above, and so on.
This option requires the nestedHeaders plugin to be configured.
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: undefined
Category: CollapsibleColumns
Example
// enable column collapsing for all headerscollapsibleColumns: true,
// enable column collapsing for selected headerscollapsibleColumns: [ {row: -4, col: 1, collapsible: true}, {row: -3, col: 5, collapsible: true}],colorScheme
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
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
Category: Core
Since: 18.1.0
Example
// Render the grid in dark mode, without declaring a themeconst hot = new Handsontable(container, { colorScheme: 'dark',});Example
// Switch the color scheme at runtimehot.updateSettings({ colorScheme: 'auto',});columnHeaderHeight
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
| A number | Set the same height for every column header |
| A string | Set the same height, written as a pixel size ('25', '25px') |
| An array | Set 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
Category: Core
Example
// set the same height for every column headercolumnHeaderHeight: 25,
// set the same height, written as a pixel sizecolumnHeaderHeight: '25px',
// set different heights for individual column headerscolumnHeaderHeight: [25, 30, 55],columns
Can be set at: grid
options.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
Category: Core
Example
// set the `columns` option to an array of objects// each object represents one columncolumns: [ { // 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 indexescolumns(index) { return { type: index > 0 ? 'numeric' : 'text', readOnly: index < 1 }}columnSorting
Can be set at: grid columns
options.columnSorting : boolean | object
The columnSorting option configures the ColumnSorting plugin.
You can set the columnSorting option to one of the following:
| Setting | Description |
|---|---|
true | Enable the ColumnSorting plugin with the default configuration |
false | Disable the ColumnSorting plugin |
| An object | - Enable the ColumnSorting plugin- Modify the ColumnSorting plugin options |
If you set the columnSorting option to an object,
you can set the following ColumnSorting plugin options:
| Option | Possible settings |
|---|---|
indicator | true: Display the arrow icon in the column header, to indicate a sortable columnfalse: Don’t display the arrow icon in the column header |
headerAction | true: Enable clicking on the column header to sort the columnfalse: Disable clicking on the column header to sort the column |
sortEmptyCells | true: Sort empty cells as wellfalse: Place empty cells at the end |
sortFixedRows | true: Sort the whole dataset, including the rows pinned by fixedRowsTop and fixedRowsBottomfalse: Keep the pinned rows in placeGrid-level only |
compareFunctionFactory | A custom compare function |
If you set the columnSorting option to an object,
you can also sort individual columns at Handsontable’s initialization.
In the columnSorting object, add an object named initialConfig,
with the following properties:
| Option | Possible settings | Description |
|---|---|---|
column | A number | The index of the column that you want to sort at initialization |
sortOrder | 'asc' | 'desc' | The sorting order:'asc': ascending'desc': descending |
Read more:
Default: undefined
Category: ColumnSorting
Example
// enable the `ColumnSorting` plugincolumnSorting: true
// enable the `ColumnSorting` plugin with custom configurationcolumnSorting: { // sort empty cells as well sortEmptyCells: true, // display the arrow icon in the column header indicator: true, // disable clicking on the column header to sort the column headerAction: false, // sort the pinned rows along with the rest of the dataset sortFixedRows: true, // add a custom compare function compareFunctionFactory(sortOrder, columnMeta) { return function(value, nextValue) { // some value comparisons which will return -1, 0 or 1... } }}
// enable the `ColumnSorting` plugin with an initial sort order:// sort column 1 in ascending order at initializationcolumnSorting: { initialConfig: { column: 1, sortOrder: 'asc' }}columnSummary
Can be set at: grid
options.columnSummary : Array<object> | function
The columnSummary option configures the ColumnSummary plugin.
You can set the columnSummary option to an array of objects.
Each object configures a single column summary, using the following properties:
| Property | Possible values | Description |
|---|---|---|
sourceColumn | A number | Column to summarize |
ranges | An array | Ranges of rows to summarize |
type | 'sum' | 'min' | 'max' | 'count' | 'average' | 'custom' | Summary function |
destinationRow | A number | Destination cell’s row coordinate |
destinationColumn | A number | Destination cell’s column coordinate |
forceNumeric | true | false | Treat non-numerics as numerics |
reversedRowCoords | true | false | Reverse row coordinates |
suppressDataTypeErrors | true | false | Suppress data type errors |
readOnly | true | false | Make summary cell read-only |
roundFloat | true | false | A number | Round summary result |
includeSummaryResults | true | false | Include other summary results |
customFunction | A function | Custom summary 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
Category: ColumnSummary
Example
columnSummary: [ { sourceColumn: 0, ranges: [ [0, 2], [4], [6, 8] ], type: 'custom', destinationRow: 4, destinationColumn: 1, forceNumeric: true, reversedRowCoords: true, suppressDataTypeErrors: false, readOnly: true, roundFloat: false, customFunction(endpoint) { return 100; } }],colWidths
Can be set at: grid
options.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:
| Setting | Description | Example |
|---|---|---|
| A number | Set the same width for every column | colWidths: 100 |
| A string | Set the same width for every column | colWidths: '100px' |
| An array | Set widths separately for each column, by physical column index | colWidths: [100, 120, undefined] |
| A function | Set column widths dynamically, on each render, by physical column index | colWidths(physicalColumnIndex) { return physicalColumnIndex * 10; } |
undefined | Used by the modifyColWidth hook, to detect column width changes. | colWidths: undefined |
null | Same 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
colWidthsfunction. It states no fixed width, so it is left alone. - A grid whose
manualColumnResizeoption is already a non-empty array. The plugin replays that array, so the stored widths stay. - The React, Angular and Vue wrappers, when the
colWidthsprop 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
Category: Core
Example
// set every column's width to 100pxcolWidths: 100,
// set every column's width to 100pxcolWidths: '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 functioncolWidths(physicalColumnIndex) { return physicalColumnIndex * 10;},commentedCellClassName
Can be set at: grid columns cells cell
options.commentedCellClassName : string
The commentedCellClassName option lets you add a CSS class name to cells
that have comments.
Read more:
- Comments
commentsreadOnlyCellClassNamecurrentRowClassNamecurrentHeaderClassNameactiveHeaderClassNameinvalidCellClassNameplaceholderCellClassNamereadOnlyCellClassNamenoWordWrapClassNameTableClassNameclassName
Default: “htCommentCell”
Category: Core
Example
// add a `has-comment` CSS class name// to each cell that has a commentcommentedCellClassName: 'has-comment',comments
Can be set at: grid
options.comments : boolean | Array<object>
The comments option configures the Comments plugin.
You can set the comments option to one of the following:
| Setting | Description |
|---|---|
true | - Enable the Comments plugin- Add comment menu items to the context menu |
false | Disable the Comments plugin |
| An object | - Enable the Comments plugin- Add comment menu items to the context menu - Configure comment settings |
If you set the comments option to an object, you can configure the following comment options:
| Option | Possible settings | Description |
|---|---|---|
displayDelay | A number (default: 250) | Display comments after a delay (in milliseconds) |
readOnly | true | false (default) | true: Make comments read-only |
style | An object | Set comment boxes’ width and height (in pixels) |
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
Category: Comments
Example
// enable the `Comments` plugincomments: true,
// enable the `Comments` plugin// and configure its settingscomments: { // display all comments with a 1-second delay displayDelay: 1000, // make all comments read-only readOnly: true, // set the default size of all comment boxes style: { width: 300, height: 100 }}contextMenu
Can be set at: grid
options.contextMenu : boolean | Array<string> | object
The contextMenu option configures the ContextMenu plugin.
You can set the contextMenu option to one of the following:
| Setting | Description |
|---|---|
false | Disable the ContextMenu plugin |
true | - Enable the ContextMenu plugin- Use the default context menu options |
| An array | - Enable the ContextMenu plugin- Modify individual context menu options |
| An object | - Enable the ContextMenu plugin- Apply a custom context menu configuration |
Read more:
- Context menu
- Context menu: Context menu with default options
- Context menu: Context menu with specific options
- Context menu: Context menu with fully custom configuration options
- Plugins:
ContextMenu
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
Category: ContextMenu
Example
// enable the `ContextMenu` plugin// use the default context menu optionscontextMenu: true,
// enable the `ContextMenu` plugin// and modify individual context menu optionscontextMenu: ['row_above', 'row_below', '---------', 'undo', 'redo'],
// enable the `ContextMenu` plugin// and apply a custom context menu configurationcontextMenu: { items: { 'option1': { name: 'Option 1' }, 'option2': { name: 'Option 2', submenu: { items: [ { key: 'option2:suboption1', name: 'Suboption 1', callback: function(key, options) { ... } }, ... ] } } }},copyable
Can be set at: grid columns cells cell
options.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:
| Setting | Description |
|---|---|
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
Category: Core
Example
// enable copying for each cell of the entire gridcopyable: true,
// enable copying for individual columnscolumns: [ { // enable copying for each cell of this column copyable: true }, { // disable copying for each cell of this column copyable: false }]
// enable copying for specific cellscell: [ { col: 0, row: 0, // disable copying for cell (0, 0) copyable: false, }],copyPaste
Can be set at: grid
options.copyPaste : object | boolean
The copyPaste option configures the CopyPaste plugin.
You can set the copyPaste option to one of the following:
| Setting | Description |
|---|---|
true (default) | Enable the CopyPaste plugin with the default configuration |
false | Disable the CopyPaste plugin |
| An object | - Enable the CopyPaste plugin- Modify the CopyPaste plugin options |
copyPaste: Additional options
If you set the copyPaste option to an object, you can set the following CopyPaste plugin options:
| Option | Possible settings | Description |
|---|---|---|
columnsLimit | A number (default: Infinity) | The maximum number of columns that can be copied |
rowsLimit | A number (default: Infinity) | The maximum number of columns that can be copied |
pasteMode | 'overwrite' | 'shift_down' | 'shift_right' | When pasting:'overwrite': overwrite the currently-selected cells'shift_down': move the currently-selected cells down'shift_right': move the currently-selected cells to the right |
copyColumnHeaders | Boolean (default: false) | true: add a context menu option for copying cells along with their nearest column headers |
copyColumnGroupHeaders | Boolean (default: false) | true: add a context menu option for copying cells along with all their related columns headers |
copyColumnHeadersOnly | Boolean (default: false) | true: add a context menu option for copying column headers nearest to the selected cells (without copying cells) |
uiContainer | An HTML element | The UI container for the secondary focusable 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: true
Category: CopyPaste
Example
// enable the plugin with the default configurationcopyPaste: true // set by default
// disable the plugincopyPaste: false,
// enable the plugin with a custom configurationcopyPaste: { // set a maximum number of columns that can be copied columnsLimit: 25,
// set a maximum number of rows that can be copied rowsLimit: 50,
// set the paste behavior pasteMode: 'shift_down',
// add the option to copy cells along with their nearest column headers copyColumnHeaders: true,
// add the option to copy cells along with all their related columns headers copyColumnGroupHeaders: true,
// add the option to copy just column headers (without copying cells) copyColumnHeadersOnly: true,
// set a UI container uiContainer: document.body,},currentColClassName
Can be set at: grid
options.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:
currentRowClassNamecurrentHeaderClassNameactiveHeaderClassNameinvalidCellClassNameplaceholderCellClassNamereadOnlyCellClassNamecommentedCellClassNamenoWordWrapClassNameTableClassNameclassName
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
Category: Core
Example
// add a `your-class-name` CSS class name// to each cell of the currently-visible, currently-selected columnscurrentColClassName: 'your-class-name',currentHeaderClassName
Can be set at: grid
options.currentHeaderClassName : string
The currentHeaderClassName option lets you add a CSS class name
to every currently-visible, currently-selected header.
Read more:
currentRowClassNamecurrentColClassNameactiveHeaderClassNameinvalidCellClassNamereadOnlyCellClassNamecommentedCellClassNamenoWordWrapClassNameTableClassNameclassName
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”
Category: Core
Example
// add an `ht__highlight` CSS class name// to every currently-visible, currently-selected headercurrentHeaderClassName: 'ht__highlight',currentRowClassName
Can be set at: grid
options.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:
currentColClassNamecurrentHeaderClassNameactiveHeaderClassNameinvalidCellClassNameplaceholderCellClassNamereadOnlyCellClassNamecommentedCellClassNamenoWordWrapClassNameTableClassNameclassName
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
Category: Core
Example
// add a `your-class-name` CSS class name// to each cell of the currently-visible, currently-selected rowscurrentRowClassName: 'your-class-name',customBorders
Can be set at: grid
options.customBorders : boolean | Array<object>
The customBorders option configures the CustomBorders plugin.
To enable the CustomBorders plugin
(and add its menu items to the context menu),
set the customBorders option to true.
To enable the CustomBorders plugin
and add a predefined border around a particular cell,
set the customBorders option to an array of objects.
Each object represents a border configuration for one cell, and has the following properties:
| Property | Sub-properties | Types | Description |
|---|---|---|---|
row | - | row: Number | The cell’s row coordinate. |
col | - | col: Number | The cell’s column coordinate. |
start | widthcolorstyle | width: Numbercolor: Stringstyle: String | If the layout direction is LTR (default): start sets the width (width), color (color) and style (style) of the left-hand border.If the layout direction is RTL: start sets the width (width), color (color) and style (style) of the right-hand border. |
end | widthcolorstyle | width: Numbercolor: Stringstyle: String | If the layout direction is LTR (default): end sets the width (width), color (color) and style (style) of the right-hand border.If the layout direction is RTL: end sets the width (width), color (color) and style (style) of the left-hand border. |
top | widthcolorstyle | width: Numbercolor: Stringstyle: String | Sets the width (width), color (color) and style (style) of the top border. |
bottom | widthcolorstyle | width: Numbercolor: Stringstyle: String | Sets the width (width), color (color) and style (style) of the bottom border. |
To enable the CustomBorders plugin
and add a predefined border around a range of cells,
set the customBorders option to an array of objects.
Each object represents a border configuration for a single range of cells, and has the following properties:
| Property | Sub-properties | Types | Description |
|---|---|---|---|
range | from {row, col}to {row, col} | from: Objectto: Objectrow: Numbercol: Number | If the layout direction is LTR (default): - from selects the range’s top-left corner.- to selects the range’s bottom-right corner.If the layout direction is RTL: - from selects the range’s top-right corner.- to selects the range’s bottom-left corner. |
start | widthcolorstyle | width: Numbercolor: Stringstyle: String | If the layout direction is LTR (default): start sets the width (width), color (color) and style (style) of the left-hand border.If the layout direction is RTL: start sets the width (width), color (color) and style (style) of the right-hand border. |
end | widthcolorstyle | width: Numbercolor: Stringstyle: String | If the layout direction is LTR (default): end sets the width (width), color (color) and style (style) of the right-hand border.If the layout direction is RTL: end sets the width (width), color (color) and style (style) of the left-hand border. |
top | widthcolorstyle | width: Numbercolor: Stringstyle: String | Sets the width (width), color (color) and style (style) of the top border. |
bottom | widthcolorstyle | width: Numbercolor: Stringstyle: String | Sets the width (width), color (color) and style (style) of the bottom border. |
Read more:
- Formatting cells: Custom cell borders
- Context menu
- Plugins:
CustomBorders - Layout direction
layoutDirection
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
Category: CustomBorders
Example
// enable the `CustomBorders` plugincustomBorders: true,
// enable the `CustomBorders` plugin// and add a predefined border for a particular cellcustomBorders: [ // add an object with a border configuration for one cell { // set the cell's row coordinate row: 2, // set the cell's column coordinate col: 2, // set the left/right border's width and color start: { width: 2, color: 'red' }, // set the right/left border's width, color and style end: { width: 1, color: 'green', style: 'dashed' }, // add the default top border (1px solid black) top: true, // hide the bottom border bottom: false }],
// enable the `CustomBorders` plugin// and add a predefined border for a range of cellscustomBorders: [ // add an object with a border configuration for one range of cells { // select a range of cells range: { // set the range's top-left corner from: { row: 1, col: 1 }, // set the range's bottom-right corner to: { row: 3, col: 4 } }, // set the left/right border's width, color and style start: { width: 2, color: 'red', style: 'dashed' }, // set the right/left border's width and color end: {}, // set the top border's width and color top: {}, // set the bottom border's width and color bottom: {} }],customBordersProgressive
Can be set at: grid
options.customBordersProgressive : boolean | object
The customBordersProgressive option controls how a large customBorders
configuration is applied at initialization.
By default (false), all custom borders are built synchronously before the first render, which
can block the initial paint when the configuration contains a very large number of borders.
Set it to true to apply the borders in background batches after the grid has rendered: the
grid becomes interactive immediately and the borders fill in progressively. Pass an object to
tune the batch size, for example { chunkSize: 5000 }.
When enabled, getBorders() and the borders’ cell meta
are populated incrementally, so they may be incomplete until the
afterCustomBordersUpdate hook fires.
When you replace customBorders with updateSettings(), the borders that are
already drawn stay visible until the new ones are applied. A border missing from the new
configuration disappears when the load ends.
Default: false
Category: CustomBorders
Since: 18.1.0
Example
// apply a large custom-borders config in background batchescustomBorders: [ / * ...many borders... * / ],customBordersProgressive: true,
// tune the batch sizecustomBordersProgressive: { chunkSize: 5000 },data
Can be set at: grid columns
options.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:
- Either to an array of arrays.
- Or to an array of objects.
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
Category: Core
Example
// as an array of arraysdata: [ ['A', 'B', 'C'], ['D', 'E', 'F'], ['G', 'H', 'J']]
// as an array of objectsdata: [ {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
options.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
Category: Core
Since: 14.4.0
Example
// All dots are interpreted as nested object pathsdataDotNotation: 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 keysdataDotNotation: 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
options.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
Category: Core
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
options.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:
- Binding to data: Array of objects with custom data schema
- Binding to data: Function data source and schema
data
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
Category: Core
Example
// with `dataSchema`, you can start with an empty griddata: 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: 1dateFormat
Can be set at: grid columns cells cell
options.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:
| Property | Possible values | Description |
|---|---|---|
dateStyle | 'full', 'long', 'medium', 'short' | Date formatting style (expands to weekday, day, month, year, era) |
Date-time component options:
| Property | Possible values | Description |
|---|---|---|
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 |
fractionalSecondDigits | 1, 2, 3 | Fraction-of-second digits |
timeZoneName | 'long', 'short', 'shortOffset', 'longOffset', 'shortGeneric', 'longGeneric' | Time zone display |
Locale and other options:
| Property | Possible values | Description |
|---|---|---|
localeMatcher | 'best fit' (default), 'lookup' | Locale matching algorithm |
calendar | 'chinese', 'gregory', 'persian', etc. | Calendar to use |
numberingSystem | 'latn', 'arab', 'hans', etc. | Numbering system |
timeZone | IANA time zone (e.g. 'UTC', 'America/New_York') | Time zone for formatting |
hour12 | true, false | Use 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’ }
Category: Core
Example
columns: [ { type: 'date', locale: 'en-US', dateFormat: { dateStyle: 'short' } }]dateTimeFormat
Can be set at: grid columns cells cell
options.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 }
Category: Core
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
options.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
Category: Core
Example
columns: [ { type: 'date', defaultDate: '2015-02-02' }],density
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
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
Category: Core
Since: 18.1.0
Example
// Render the grid with tighter spacing, without declaring a themeconst hot = new Handsontable(container, { density: 'compact',});Example
// Change the density at runtimehot.updateSettings({ density: 'comfortable',});dialog
Can be set at: grid
options.dialog : boolean | object
The dialog option configures the Dialog plugin.
You can set the dialog option to one of the following:
dialog: Additional options
| Option | Possible settings | Description |
|---|---|---|
template | Object with the template configuration (default: null). | The template of the dialog allows to use prebuild templates |
template.type | The type of the template (‘confirm’) | The type of the template |
template.title | The title of the template | The title of the template |
template.description | The description of the template | The description of the template |
template.buttons | Array of objects with the buttons configuration (default: []) | The buttons of the template |
template.buttons.text | The text of the button | The text of the button |
template.buttons.type | The type of the button ('primary' | 'secondary') | The type of the button |
template.buttons.callback | The callback function to trigger when the button is clicked | The callback function to trigger when the button is clicked |
content | A string, HTMLElement or DocumentFragment (default: '') | The content of the dialog |
customClassName | A string (default: '') | The custom class name of the dialog |
background | One of the options: 'solid' or 'semi-transparent' (default: 'solid') | The background of the dialog |
contentBackground | Boolean (default: false) | Whether to show the content background |
animation | Boolean (default: true) | Whether to show the animation |
closable | Boolean (default: false) | Whether to make the dialog closable |
a11y | Object with accessibility options (default: { role: 'dialog', ariaLabel: 'Dialog', ariaLabelledby: '', ariaDescribedby: '' }) | Accessibility options for the dialog |
a11y.role | The role of the dialog ('dialog' | 'alertdialog') | The role of the dialog |
a11y.ariaLabel | The label of the dialog | The label of the dialog |
a11y.ariaLabelledby | The ID of the element that labels the dialog | The ID of the element that labels the dialog |
a11y.ariaDescribedby | The ID of the element that describes the dialog | The ID of the element that describes the dialog |
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.
The dialog is available on the main grid only. In a grid nested in a cell, that is a cell of the
handsontable,
autocomplete, or
dropdown cell type, this
option has no effect.
Default: false
Category: Dialog
Since: 16.1.0
Example
settings = { dialog: { content: 'Dialog content', customClassName: 'custom-dialog', background: 'semi-transparent', contentBackground: false, animation: false, closable: true, a11y: { role: 'dialog', ariaLabel: 'Dialog', ariaLabelledby: 'titleID', ariaDescribedby: 'descriptionID', } }};
// enable the Dialog plugin using a templatesettings = { dialog: { template: { type: 'confirm', title: 'Confirm', description: 'Do you want change the value?', } }};<hot-table [settings]="settings" />disableVisualSelection
Can be set at: grid columns cells cell
options.disableVisualSelection : boolean | string | Array<string>
The disableVisualSelection option configures how
selection is shown.
You can set the disableVisualSelection option to one of the following:
| Setting | Description |
|---|---|
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 array | A 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
Category: Core
Example
// don't show single-cell selection// don't show range selection// don't show header selectiondisableVisualSelection: true,
// don't show single-cell selection// show range selection// show header selectiondisableVisualSelection: 'current',
// don't show single-cell selection// don't show range selection// show header selectiondisableVisualSelection: ['current', 'area'],dragToScroll
Can be set at: grid
options.dragToScroll : boolean | object
The dragToScroll option configures the DragToScroll plugin.
You can set the dragToScroll option to one of the following:
| Setting | Description |
|---|---|
true (default) | Enable with default auto-scroll settings |
false | Disable the plugin entirely |
| Object | Enable with custom auto-scroll settings (see below) |
When passing an object, the following properties control the auto-scroll speed:
dragToScroll: { interval: { min: 20, // Fastest scroll interval in ms (reached at rampDistance) max: 500, // Slowest scroll interval in ms (applied at the viewport edge) }, rampDistance: 120, // Pixels outside the edge over which speed ramps up},The viewport scrolls periodically while the mouse pointer stays outside the viewport edge. Speed follows a logarithmic curve: slow at the edge, fast when far outside. The active selection (regular drag-select or autofill drag) extends to follow the scroll.
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
Category: DragToScroll
Example
// Enable with default settingsdragToScroll: true,
// Enable with custom scroll speeddragToScroll: { interval: { min: 60, max: 300 }, rampDistance: 60,},
// DisabledragToScroll: false,dropdownMenu
Can be set at: grid
options.dropdownMenu : boolean | object | Array<string>
The dropdownMenu option configures the DropdownMenu plugin.
You can set the dropdownMenu option to one of the following:
| Setting | Description |
|---|---|
false | Disable the DropdownMenu plugin |
true | - Enable the DropdownMenu plugin- Use the default context menu options |
| An array | - Enable the DropdownMenu plugin- Modify individual context menu options |
| An object | - Enable the DropdownMenu plugin- Apply a custom dropdown menu configuration |
This option can only be set at the grid level. It is not possible to show or hide the dropdown menu icon for individual columns using this option.
Read more:
Default: undefined
Category: DropdownMenu
Example
// enable the `DropdownMenu` plugin// use the default context menu optionsdropdownMenu: true,
// enable the `DropdownMenu` plugin// and modify individual context menu optionsdropdownMenu: ['---------', 'undo', 'redo'],
// enable the `DropdownMenu` plugin// and apply a custom dropdown menu configurationdropdownMenu: { items: { 'option1': { name: 'Option 1' }, 'option2': { name: 'Option 2', submenu: { items: [ { key: 'option2:suboption1', name: 'Suboption 1', callback(key, options) { ... } }, ... ] } } }},editableHeaders
Can be set at: grid columns
options.editableHeaders : boolean | object
The editableHeaders option configures the EditableHeaders plugin, which lets
users rename column headers, and optionally row headers, the way they edit cells.
You can set the editableHeaders option to one of the following:
| Setting | Description |
|---|---|
true | Enable the EditableHeaders plugin for column headers |
false | Disable the EditableHeaders plugin |
| An object | Enable the EditableHeaders plugin and choose the header axes |
The object form accepts the following properties:
| Property | Type | Default | Description |
|---|---|---|---|
columnHeaders | boolean | true | Whether users can rename column headers |
rowHeaders | boolean | false | Whether users can rename row headers |
To keep one column’s header from being renamed, set editableHeaders: false for that column in the
columns option.
Read more:
Default: undefined
Category: EditableHeaders
Since: 19.0.0
Example
// let users rename column headerseditableHeaders: true,
// let users rename column headers and row headerseditableHeaders: { columnHeaders: true, rowHeaders: true,},
// keep the first column's header from being renamedcolumns: [ { editableHeaders: false }, {},],editor
Can be set at: grid columns cells cell
options.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:
| Alias | Cell editor function |
|---|---|
| A custom alias | Your 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:
| Shortcut | Action |
|---|---|
Delete / Backspace | Clear the contents of the selected cells |
Ctrl + Enter / Cmd + Enter | Fill 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 numericeditor: 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 editablehot.updateSettings({ editor: false });
// the numeric column becomes non-editable toohot.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
Category: Core
Example
// use the `numeric` editor for each cell of the entire grideditor: 'numeric',
// apply the `editor` option to individual columnscolumns: [ { // 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 }]emptyDataState
Can be set at: grid
options.emptyDataState : boolean | object
The emptyDataState option configures the EmptyDataState plugin.
You can set the emptyDataState option to one of the following:
| Setting | Description |
|---|---|
false | Disable the EmptyDataState plugin |
true | Enable the EmptyDataState plugin |
| An object | Enable the EmptyDataState plugin with custom settings |
If you set the emptyDataState option to an object, you can configure the following settings:
| Property | Possible values | Description |
|---|---|---|
message | string | object | function | Message to display in the empty data state overlay. |
If you set the message option to an object, it have following properties:
| Property | Possible values | Description |
|---|---|---|
title | string | Title to display in the empty data state overlay. |
description | string | Description to display in the empty data state overlay. |
buttons | array | Buttons to display in the empty data state overlay. |
loading | boolean | When true, shows a loading spinner (used for server fetch state). |
If you set the message option to a function, the source argument can be "unknown", "filters", or "loading".
With Options#dataProvider, the "loading" branch follows DataProvider fetch hooks (beforeDataProviderFetch,
afterDataProviderFetch, and related hooks) using the same rules as server-backed loading in the DataProvider plugin.
Internal refetches (for example after column sort or CRUD) set skipLoading on Hooks#beforeDataProviderFetch so the
EmptyDataState plugin can omit the loading overlay for those requests.
If you set the buttons option to an array, each item requires following properties:
| Property | Possible values | Description |
|---|---|---|
text | string | Text to display in the button. |
type | ’primary’ | ‘secondary’ | Type of the button. |
callback | function | Callback function to call when the button is clicked. |
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.
The empty data state is available on the main grid only. In a grid nested in a cell, that is a
cell of the
handsontable,
autocomplete, or
dropdown cell type, this
option has no effect.
Default: false
Category: EmptyDataState
Since: 16.2.0
Example
// Enable empty data state plugin with default messagesemptyDataState: true,
// Enable empty data state plugin with custom messageemptyDataState: { message: 'No data available',},
// Enable empty data state plugin with custom message and buttons for any sourceemptyDataState: { message: { title: 'No data available', description: 'There’s nothing to display yet.', buttons: [{ text: 'Reset filters', type: 'secondary', callback: () => {} }], },},
// Enable empty data state plugin with custom message and buttons for specific sourceemptyDataState: { message: (source) => { switch (source) { case "filters": return { title: 'No data available', description: 'There’s nothing to display yet.', buttons: [{ text: 'Reset filters', type: 'secondary', callback: () => {} }], }; case "loading": return { title: 'Loading data', description: 'Please wait.', }; default: return { title: 'No data available', description: 'There’s nothing to display yet.', }; } },},emptyValue
Can be set at: grid columns cells cell
options.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.
| Setting | Description |
|---|---|
'' (default) | Leave an emptied cell as the empty string the write produced |
null | Store null instead |
undefined | Same as the default — the option counts as unset |
| Any other value | Store 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: ”
Category: Core
Since: 18.3.0
Example
// store `null` in every emptied cell of the gridemptyValue: null,
// or per column: keep text columns storing `''`, and store `null` in the typed onescolumns: [ { data: 'name' }, { data: 'amount', type: 'numeric', emptyValue: null }, { data: 'due', type: 'date', emptyValue: null }]enterBeginsEditing
Can be set at: grid
options.enterBeginsEditing : boolean
The enterBeginsEditing option configures the action of the Enter key.
You can set the enterBeginsEditing option to one of the following:
| Setting | Description |
|---|---|
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
Category: Core
Example
// press Enter once to start editing// press Enter twice to move to another cellenterBeginsEditing: true,
// press Enter once to move to another cellenterBeginsEditing: false,enterCommits
Can be set at: grid columns cells cell
options.enterCommits : boolean
The enterCommits option configures whether the Enter key closes the multiSelect editor.
Default: true
Category: Core
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
options.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):
| Property | Type | Description |
|---|---|---|
col | Number | - On pressing Enter, move selection col columns right- On pressing Shift+Enter, move selection col columns left |
row | Number | - 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}
Category: Core
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 upenterMoves: {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+EnterenterMoves(event) { return {col: 1, row: 1};},exportFile
Can be set at: grid
options.exportFile : boolean | object
The exportFile option configures the ExportFile plugin.
You can set the exportFile option to one of the following:
| Setting | Description |
|---|---|
undefined | Use the ExportFile plugin with the default configuration, with the context-menu entry hidden |
true | Use the plugin with the default configuration (built-in xlsx engine), with the context-menu entry shown |
false | The same as true: the plugin stays enabled, its API keeps working, and the context-menu entry is shown. To hide the entry, leave the option undefined |
| An object | Enable the ExportFile plugin and modify the plugin options |
If you set the exportFile option to an object, you can configure the following options:
| Option | Type | Default | Description |
|---|---|---|---|
engines | Object | – | Optional. A map of format keys to engine modules. Pass { xlsx: ExcelJS } to export through ExcelJS instead of the built-in engine. |
Read more:
Default: undefined
Category: ExportFile
Since: 17.1.0
Example
// XLSX and CSV export with the built-in engineexportFile: true,
// or export XLSX through ExcelJSimport ExcelJS from 'exceljs';
exportFile: { engines: { xlsx: ExcelJS },},fillHandle
Can be set at: grid
options.fillHandle : boolean | string | object
The fillHandle option configures the Autofill plugin.
You can set the fillHandle option to one the following:
| Setting | Description |
|---|---|
true | - Enable autofill in all directions - Add the fill handle |
false | Disable 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:
| Option | Possible settings | Description |
|---|---|---|
autoInsertRow | true (default) | false | true: When you reach the grid’s bottom, add new rowsfalse: 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 }
Category: Core
Example
// enable autofill in all directions// with `autoInsertRow` enabledfillHandle: true,
// enable vertical autofill// with `autoInsertRow` enabledfillHandle: 'vertical',
// enable horizontal autofill// with `autoInsertRow` enabledfillHandle: 'horizontal',
// enable autofill in all directions// with `autoInsertRow` disabledfillHandle: { autoInsertRow: false,},
// enable vertical autofill// with `autoInsertRow` disabledfillHandle: { autoInsertRow: false, direction: 'vertical'},filter
Can be set at: grid columns cells cell
options.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:
| Setting | Description |
|---|---|
true (default) | When the end user types into the input area, only options matching the input are displayed |
false | When the end user types into the input area, all options are displayed (options matching the input are put in bold |
Read more:
Default: true
Category: Core
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
options.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:
| Setting | Description |
|---|---|
false (default) | autocomplete cells’ input is not case-sensitive |
true | autocomplete cells’ input is case-sensitive |
Read more:
Default: false
Category: Core
Example
columns: [ { type: 'autocomplete', source: [ ... ], // match case while searching autocomplete options filteringCaseSensitive: true }, { type: 'multiselect', source: [ ... ], // match case while searching multiSelect options filteringCaseSensitive: true }],filters
Can be set at: grid columns
options.filters : boolean | object
The filters option configures the Filters plugin.
The option takes different values at the two levels it works at, so they are listed
separately below. At the grid level it switches the plugin on and carries its settings. Inside
columns, false takes that column out of filtering, and an object can set the
column’s own availableConditions.
At the grid level:
| Setting | Description |
|---|---|
false | Disable the Filters plugin |
true | Enable the Filters plugin |
| An object | Enable the Filters plugin with custom settings |
If you set the filters option to an object, you can configure the following settings.
searchMode and filterFixedRows are read once, for the whole grid, so they cannot be set per
column. availableConditions can be set at both levels:
| Property | Possible values | Default | Description |
|---|---|---|---|
searchMode | 'show' | 'apply' | 'show' | Enable filtering only visible elements |
filterFixedRows | true | false | true | true: Filter the whole dataset, including the rows pinned by fixedRowsTop and fixedRowsBottomfalse: Leave the pinned rows out of the filter |
availableConditions | An array | An object | undefined | The operators the Filter by condition lists offer. See below. |
availableConditions takes one of three shapes:
| Shape | Description |
|---|---|
| An array of condition names | Offer only these conditions, in this order. '---------' adds a separator. |
{ exclude: [...] } | Offer the default list for the column’s data type, minus these conditions. |
| An object keyed by data type | One of the two shapes above per data type: text, numeric, date, intl-date, intl-time, intl-datetime. |
The condition names are the ones addCondition() takes, for
example 'eq', 'gt', 'between', or 'not_between'. A column whose type has no list of its
own (for example dropdown) uses the text list. A checkbox column uses the text list with
'checked' and 'unchecked' added (unless a data provider backs the grid), and follows the
text key of a per-type object. There is no checkbox key: to offer a checkbox column only
'empty', 'not_empty', 'checked', and 'unchecked', set availableConditions on that column.
None always stays first. A name the column’s data type does not offer is left out. The
setting changes the lists only: a condition added through addCondition() still filters, and its select
still shows it.
When the grid is created, and when the setting changes, a console warning names each condition that no data type offers, each listed condition a column’s data type does not offer, and each data type key without a list of its own. Such a key is ignored; the other entries still apply.
A column’s own availableConditions replaces the grid-level one for that column. The two are
not merged. A column whose own value is undefined uses the grid-level value.
Updating the filters option through updateSettings()
clears the filters that are applied. A filters object that leaves out availableConditions
keeps the previous value, and setting filters to false does not clear it either. Pass
availableConditions: undefined or filters: true to go back to the default lists.
availableConditions changes what the condition lists contain, not which parts the menu
shows. The dropdownMenu option decides that, so if its configuration leaves
out or hides filter_by_condition, the setting has nothing to act on.
Set filterFixedRows to false when the pinned rows hold totals or headings rather than data.
Those rows are then never hidden by a filter, and their values are not offered in the
Filter by value list.
filterFixedRows has no effect while the DataProvider plugin is
active: filtering then happens on the server, which knows nothing about frozen rows.
With filterFixedRows: false and a filter applied, the grid works out again which rows are
exempt when the rows change, on the next render. Inserting or removing a row (including through
updateData()) always does it. Moving a row, sorting, or changing
fixedRowsTop or fixedRowsBottom does it only when a different row ends up frozen, so a sort
that keeps the frozen rows in place (the columnSorting default) costs
nothing. This is not a new filter: the conditions stay the same, the
beforeFilter and afterFilter
hooks do not fire, the selection does not move, and no undo step is recorded. Inside a
batch(), data read before the batch ends still reflects the previous
frozen rows.
Inside columns:
| Setting | Description |
|---|---|
false | Hide the filter controls in this column’s dropdown menu |
{ availableConditions: ... } | Choose the operators this column’s Filter by condition lists offer |
| Anything else | No effect – the column keeps whatever the grid-level setting gave it |
The column’s dropdown menu still opens, so entries such as Clear column stay available.
The plugin’s API is not affected either: addCondition()
still filters such a column, the same way columnSorting’s headerAction
leaves sorting through the API working.
Inside columns, an object is read for availableConditions only. Any other key in it, such
as searchMode or filterFixedRows, is ignored, and logs a warning once per grid. Since
19.0, TypeScript rejects it too: a column’s filters is typed boolean or
{ availableConditions }, and the grid-level object accepts only searchMode,
filterFixedRows, and availableConditions.
The switch is read from the column meta, which the cells and cell
options do not reach, so filtering cannot be turned off for a single cell. Filtering works on
whole columns, so there would be nothing for a per-cell value to mean.
Read more:
- Column filter
- Plugins:
Filters dropdownMenufilterValueComparator– order the values in the Filter by value list
Default: undefined
Category: Filters
Example
// enable the `Filters` pluginfilters: true,
// enable it, and keep the frozen rows out of the filterfilters: { filterFixedRows: false,},
// turn filtering off for the second column onlyfilters: true,columns: [ {}, { filters: false },],
// remove "Is not between" from every numeric columnfilters: { availableConditions: { numeric: { exclude: ['not_between'] }, },},
// offer only a few operators in one column, in this orderfilters: true,columns: [ { filters: { availableConditions: ['eq', 'neq', '---------', 'empty', 'not_empty'] } }, {},],
// WRONG: `filterFixedRows` is grid-level, so it is ignored here, warns, and does not compilecolumns: [ { filters: { filterFixedRows: false } },],filterSelectedItems
Can be set at: grid columns cells cell
options.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
Category: Core
Example
// filter out the selected items from the dropdownfilterSelectedItems: true,
// keep the selected items in the dropdownfilterSelectedItems: false,
### filterValueComparator<p class="tag-config-scope-list"><span class="tag-config-scope-label">Can be set at:</span> <span class="tag-config-scope">grid</span> <span class="tag-config-scope">columns</span></p>
<button type="button" class="ask-about-api-btn" data-option="filterValueComparator" data-plugin="Options" aria-label="Ask AI about filterValueComparator">Ask AI</button>
<a href="https://github.com/handsontable/handsontable/blob/2ecb8ba3f3d6fe761b9a6ddd011a9743405396b2/handsontable/handsontable/tmp/dataMap/metaManager/metaSchema.ts#L3668" target="_blank" rel="noopener noreferrer" class="source-code-link">Source code</a>
_options.filterValueComparator : function_
The `filterValueComparator` option sets the order of the values in the **Filter by value**list of the [`Filters`](/docs/angular-data-grid/api/filters/) dropdown.
By default the list places blank cells first and then sorts the values with a built-incomparator: numbers by value, text by character code, and `date`, `intl-date`, and`intl-datetime` cells chronologically. Set `filterValueComparator` to a function to replacethat order. The function takes two cell values and returns a negative number, zero, or apositive number, like the callback of `Array.prototype.sort()`.
The option cascades: set it at the grid level to order every column's list the same way,or inside [`columns`](#columns) to order one column. A column value overrides the grid value.A custom comparator also overrides the cell type's own comparator.
Two details to know when you write the function:- A blank cell (`null`, `undefined`, or `''`) reaches the comparator as an empty string `''`.- The comparator only orders the list. It cannot add, hide, or remove a value, so it never changes which rows the filter keeps.
A value that is not a function is ignored, and the built-in order applies.
The list is built once per column, and the comparator is read from the cell meta of thefirst row the list is built from. A per-cell value set through [`cells`](#cells) or[`cell`](#cell) is therefore not a reliable way to configure it. Set it at the grid level orinside `columns`.
Read more:- [Column filter: Change the order of values in the filter list](/docs/angular-data-grid/column-filter/#change-the-order-of-values-in-the-filter-list)- [Plugins: `Filters`](/docs/angular-data-grid/api/filters/)- [`filters`](#filters)
**Default**: <code>undefined</code>**Category**: [Filters](/docs/angular-data-grid/api/filters/)**Since**: 19.0.0**Example**```js// order the "Priority" column by severity rather than alphabeticallyconst priority = ['Critical', 'High', 'Medium', 'Low'];
filters: true,columns: [ { data: 'priority', filterValueComparator: (a, b) => priority.indexOf(a) - priority.indexOf(b), },],
// order every column's list with a locale-aware text comparisonfilters: true,filterValueComparator: (a, b) => String(a).localeCompare(String(b), 'de'),fixedColumnsEnd
Can be set at: grid
options.fixedColumnsEnd : number
The fixedColumnsEnd option sets the number of frozen columns at the end edge of the grid.
If your grid’s 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.
Use fixedColumnsEnd together with fixedColumnsStart, fixedRowsTop,
and fixedRowsBottom to freeze all four edges.
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
Category: Core
Since: 19.0.0
Example
// 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
options.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
Category: Core
Example
// freeze the first 3 columns from the leftfixedColumnsLeft: 3,fixedColumnsStart
Can be set at: grid
options.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
Category: Core
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` attributelayoutDirection: 'inherit',fixedColumnsStart: 3,
// when `layoutDirection` is set to `rtl`// freeze the first 3 columns from the right// regardless of your HTML document's `dir` attributelayoutDirection: 'rtl',fixedColumnsStart: 3,
// when `layoutDirection` is set to `ltr`// freeze the first 3 columns from the left// regardless of your HTML document's `dir` attributelayoutDirection: 'ltr',fixedColumnsStart: 3,fixedRowsBottom
Can be set at: grid
options.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
Category: Core
Example
// freeze the bottom 3 rowsfixedRowsBottom: 3,fixedRowsTop
Can be set at: grid
options.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
Category: Core
Example
// freeze the top 3 rowsfixedRowsTop: 3,formulaBuilder
Can be set at: grid
options.formulaBuilder : object | boolean
The formulaBuilder option configures the FormulaBuilder plugin.
The FormulaBuilder plugin adds spreadsheet-style formula
editing (a formula bar, an inline formula editor with colored references, reference
picking, and formula error indicators) on top of the Formulas plugin,
which must be enabled with a configured engine.
You can set the formulaBuilder option to false (the plugin is off) or to an object with the
following properties. There is no true: the plugin needs the builder module to run. The plugin
logs a warning and stays disabled for true, for {}, and for an object without builder,
although validateSettings() accepts all three.
| Property | Possible values |
|---|---|
builder | The hyperformula-ui module namespace (import * as FormulaBuilderModule from 'hyperformula-ui'). Required. |
showFormulaBar | A boolean. Renders the formula bar above the grid when true. Default: false. |
popups | An object with the popup options: showClose, suggestions, fnHelp, and error. |
direction | 'ltr' or 'rtl'. The layout direction of the editor and its popups. Default: the grid’s layout direction. |
Formula editing is opt-in per cell: set editor to 'formula' on the cells,
columns, or grid that use the formula editor.
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
Category: FormulaBuilder
Since: 19.0.0
Example
import * as FormulaBuilderModule from 'hyperformula-ui';import { HyperFormula } from 'hyperformula';
// the formula editor on every celleditor: 'formula',formulas: { engine: HyperFormula,},formulaBuilder: { builder: FormulaBuilderModule, showFormulaBar: true,},formulas
Can be set at: grid
options.formulas : object
The formulas option configures the Formulas plugin.
The Formulas plugin uses the HyperFormula calculation engine.
To install HyperFormula, read the following:
You can set the formulas option to an object with the following properties:
| Property | Possible values |
|---|---|
engine | HyperFormula |A HyperFormula instance | A HyperFormula configuration object |
sheetId | A number |
sheetName | A string |
language | A HyperFormula language pack, imported from hyperformula/es/i18n/languages |
hyperlinks | true |false (default) |An object with target and schemes |
batchEvaluation | true |false (default) |
Set batchEvaluation to true to make HyperFormula recalculate once for the writes the grid makes while
its execution is suspended. batch() is the way to get that saving, because it
suspends rendering too. Without the setting, every write recalculates.
A read of a formula cell through the grid, such as getDataAtCell(), recalculates first, so it never
returns a stale value. Each render recalculates too. For that reason
batchExecution(), or a
suspendExecution() and
resumeExecution() pair, saves nothing when each write renders.
After a write, and until the next grid read or the end of the batch, a direct HyperFormula read
(engine.getCellValue()) throws “Computations are suspended”. That includes another grid that shares the
engine. Read through the grid inside the batch, or read the engine after it.
Set hyperlinks to true to render a cell whose formula is HYPERLINK() as a link. The cell
keeps its own renderer, and the link label is the value the formula returns. Only a cell whose
root expression is HYPERLINK() becomes a link, so a nested call such as
=CONCATENATE("see ", HYPERLINK("https://example.com")) renders as plain text.
Set hyperlinks to an object to configure the links: target is '_blank' (default) or
'_self', and schemes narrows the allowed URL schemes to a subset of 'http', 'https',
'mailto', and 'tel'.
A link is created only for the http, https, mailto and tel schemes. Any other scheme,
javascript: included, renders the label as plain text instead. Press
Alt+Enter to open the link of the selected cell. Each link
element gets the ht-link and ht-hyperlink classes. To link plain URLs in cell values, see
autoLink.
Read more:
- Plugins:
Formulas - Formula calculation
- HyperFormula documentation: Client-side installation
- HyperFormula documentation: Configuration options
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
Category: Formulas
Example
// either add the `HyperFormula` classformulas: { // set `engine` to `HyperFormula` engine: HyperFormula, sheetId: 1, sheetName: 'Sheet 1'}
// or, render `HYPERLINK()` formulas as linksformulas: { engine: HyperFormula, hyperlinks: true}
// or, recalculate once for all writes made inside `batch()`formulas: { engine: HyperFormula, batchEvaluation: true}
// or, open `HYPERLINK()` links in the same tab and link only web URLsformulas: { engine: HyperFormula, hyperlinks: { target: '_self', schemes: ['http', 'https'] }}
// or, add a HyperFormula instance// initialized with the `'internal-use-in-handsontable'` license keyconst hyperformulaInstance = HyperFormula.buildEmpty({ licenseKey: 'internal-use-in-handsontable',});
formulas: { // set `engine` to a HyperFormula instance engine: hyperformulaInstance, sheetId: 1, sheetName: 'Sheet 1'}
// or, add a HyperFormula configuration objectformulas: { // set `engine` to a HyperFormula configuration object engine: { hyperformula: HyperFormula // or `engine: hyperformulaInstance` leapYear1900: false, // this option comes from HyperFormula // add more HyperFormula configuration options }, sheetId: 1, sheetName: 'Sheet 1'}
// use the same HyperFormula instance in multiple Handsontable instances
// a Handsontable instance `hot1`formulas: { engine: HyperFormula, sheetId: 1, sheetName: 'Sheet 1'}
// a Handsontable instance `hot2`formulas: { engine: hot1.getPlugin('formulas').engine, sheetId: 1, sheetName: 'Sheet 1'}
// set a language pack for the built-in function names and formula syntaximport plPL from 'hyperformula/es/i18n/languages/plPL';
formulas: { engine: HyperFormula, sheetName: 'Sheet 1', language: plPL}
// update the language at runtimehot.updateSettings({ formulas: { language: plPL }});fragmentSelection
Can be set at: grid
options.fragmentSelection : boolean | string
The fragmentSelection option configures text selection settings.
You can set the fragmentSelection option to one of the following:
| Setting | Description |
|---|---|
false (default) | Disable text selection |
true | Enable 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
Category: Core
Example
// enable text selection in multiple cells at a timefragmentSelection: true,
// enable text selection in one cell a timefragmentSelection: 'cell',freezeBar
Can be set at: grid
options.freezeBar : boolean | object
The freezeBar option configures the FreezeBar plugin.
The plugin draws a bar on each edge of the frozen area. You drag the bar, or focus it and press the arrow keys, to change how many rows or columns are frozen. An edge with nothing frozen has a short handle on a corner of the headers, so users can start freezing from there.
You can set the freezeBar option to one of the following:
| Setting | Description |
|---|---|
true | Enable the FreezeBar plugin for rows and columns |
false | Disable the FreezeBar plugin |
| An object | Enable the FreezeBar plugin and choose the axes |
The object form accepts the following properties:
| Property | Type | Default | Description |
|---|---|---|---|
rows | boolean | true | Show the bar for frozen rows |
columns | boolean | true | Show the bar for frozen columns |
The plugin changes the frozen counts on the grid only. It does not write them back to the settings you passed
in, so an application that keeps the counts in its own state copies them in the
afterFreezeChange hook.
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
Category: FreezeBar
Since: 19.0.0
Example
// enable the `FreezeBar` pluginfreezeBar: true,
// enable the `FreezeBar` plugin for columns onlyfreezeBar: { rows: false,},hashLength
Can be set at: grid columns cells cell
options.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
Category: Core
Example
columns: [ { type: 'password', hashLength: 10, },],hashRevealDelay
Can be set at: grid columns cells cell
options.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
Category: Core
Since: 17.2.0
Example
columns: [ { type: 'password', hashRevealDelay: 1000, },],hashSymbol
Can be set at: grid columns cells cell
options.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: ”*“
Category: Core
Example
columns: [ { type: 'password', hashSymbol: '•', },],headerCheckbox
Can be set at: grid columns
options.headerCheckbox : boolean | object
The headerCheckbox option adds a “check all” checkbox to the header of a
checkbox column. A click on it checks every
checkbox in the column, or unchecks them when all of them are checked, and writes the values into
the data in one undo step. When only some cells are checked, the header checkbox shows the mixed
state. Read-only cells are skipped.
You can set the headerCheckbox option to one of the following:
| Setting | Description |
|---|---|
false or unset (default) | No header checkbox |
true | A header checkbox that writes to the rows that pass the filters (all pages) |
{ scope: 'filtered' } | The same as true |
{ scope: 'all' } | Also writes to the rows the filters hide |
{ scope: 'currentPage' } | Writes only to the rows on the current page of the Pagination plugin |
The option works only on columns whose type is 'checkbox'. Rows hidden with the
HiddenRows plugin and rows trimmed with the TrimRows
plugin are never written.
Read more:
Default: undefined
Category: CheckboxHeader
Since: 19.0.0
Example
columns: [ { data: 'name' }, // a "check all" checkbox in the header of the `active` column { data: 'active', type: 'checkbox', headerCheckbox: true },],headerClassName
Can be set at: grid columns
options.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
Category: Core
Since: 14.5.0
Example
// Adding class names to all column headersheaderClassName: '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
options.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:
| Setting | Example |
|---|---|
| A number of pixels | height: 500 |
| A string with a number of pixels | height: '500', height: '500px' |
| A string with a CSS unit | height: '50%', height: '75vh' |
'auto' | height: 'auto' |
| A function that returns a valid number or string | height() { 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
Category: Core
Example
// set the grid's height to 500pxheight: 500,
// set the grid's height to 75vhheight: '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 functionheight() { return 500;},hiddenColumns
Can be set at: grid
options.hiddenColumns : boolean | object
The hiddenColumns option configures the HiddenColumns plugin.
You can set the hiddenColumns option to one of the following:
| Setting | Description |
|---|---|
false | Disable the HiddenColumns plugin |
true | Enable the HiddenColumns plugin with the default plugin options |
| An object | - Enable the HiddenColumns plugin- Modify the plugin options |
If you set the hiddenColumns to an object, you can set the following HiddenColumns plugin options:
| Property | Possible values | Description |
|---|---|---|
columns | An array of indexes | An array of indexes of columns that are hidden at initialization |
copyPasteEnabled | true | false | true: when copying or pasting data, take hidden columns into accountfalse: when copying or pasting data, don’t take hidden columns into account |
indicators | true | false | true: display UI markers to indicate the presence of hidden columnsfalse: display UI markers |
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
Category: HiddenColumns
Example
// enable the `HiddenColumns` pluginhiddenColumns: true,
// enable `HiddenColumns` plugin, and modify the plugin optionshiddenColumns: { // set columns that are hidden by default columns: [5, 10, 15], // when copying or pasting data, take hidden columns into account copyPasteEnabled: true, // show where hidden columns are indicators: true}hiddenRows
Can be set at: grid
options.hiddenRows : boolean | object
The hiddenRows option configures the HiddenRows plugin.
You can set the hiddenRows option to one of the following:
| Setting | Description |
|---|---|
false | Disable the HiddenRows plugin |
true | Enable the HiddenRows plugin with the default plugin options |
| An object | - Enable the HiddenRows plugin- Modify the plugin options |
If you set the hiddenRows to an object, you can set the following HiddenRows plugin options:
| Property | Possible values | Description |
|---|---|---|
rows | An array of indexes | An array of indexes of rows that are hidden at initialization |
copyPasteEnabled | true | false | true: when copying or pasting data, take hidden rows into accountfalse: when copying or pasting data, don’t take hidden rows into account |
indicators | true | false | true: display UI markers to indicate the presence of hidden rowsfalse: display UI markers |
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
Category: HiddenRows
Example
// enable the `HiddenRows` pluginhiddenRows: true,
// enable `HiddenRows` plugin, and modify the plugin optionshiddenRows: { // set rows that are hidden by default rows: [5, 10, 15], // when copying or pasting data, take hidden rows into account copyPasteEnabled: true, // show where hidden rows are indicators: true}imeFastEdit
Can be set at: grid
options.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.
Category: Core
Since: 14.0.0
importFile
Can be set at: grid
options.importFile : boolean | object
The importFile option configures the ImportFile plugin.
You can set the importFile option to one of the following:
| Setting | Description |
|---|---|
undefined | Use the ImportFile plugin with the default configuration |
true | Use the ImportFile plugin with the default configuration |
false | Disable the ImportFile plugin |
| An object | Enable the ImportFile plugin and modify the plugin options |
If you set the importFile option to an object, you can configure the following options:
| Option | Type | Default | Description |
|---|---|---|---|
engines | Object | – | Optional. A map of format keys to engine modules. Pass { xlsx: ExcelJS } to import through ExcelJS instead of the built-in engine. |
false disables the plugin. Any other value, including leaving the option out, enables it.
Read more:
Default: undefined
Category: ImportFile
Since: 19.0.0
Example
// XLSX import with the built-in engineimportFile: true,
// or import XLSX through ExcelJSimport ExcelJS from 'exceljs';
importFile: { engines: { xlsx: ExcelJS },},initialState
Can be set at: grid
options.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
Category: Core
Since: 16.1.0
Example
initialState: { // configure initial column order manualColumnMove: [1, 0],},injectCoreCss
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
true (default) | Inject core styles into the document head |
false | Do 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
Category: Core
Since: 17.0.0
Example
// inject core CSS (default)injectCoreCss: true,
// skip injection when you load Handsontable CSS yourselfinjectCoreCss: false,invalidCellClassName
Can be set at: grid columns cells cell
options.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:
- Cell validator
currentRowClassNamecurrentHeaderClassNameactiveHeaderClassNamecurrentColClassNamereadOnlyCellClassNamecommentedCellClassNamenoWordWrapClassNameTableClassNameclassName
Default: “htInvalid”
Category: Core
Example
// add a `highlight-error` CSS class name// to every `invalid` cell`invalidCellClassName: 'highlight-error',label
Can be set at: grid columns cells cell
options.label : object
The label option configures checkbox cells` labels.
You can set the label option to an object with the following properties:
| Property | Possible values | Description |
|---|---|---|
position | 'after' (default) | 'before' | 'after': place the label to the right of the checkbox'before': place the label to the left of the checkbox |
value | A string | A function | The label’s text |
separated | false (default) | true | false: don’t separate the label from the checkboxtrue: separate the label from the checkbox |
property | A 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
Category: Core
Example
columns: [{ type: 'checkbox', // add 'My label:' after the checkbox label: { position: 'before', value: 'My label: ', separated: true }}],language
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
'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”
Category: Core
Example
// set Handsontable's language to Polishlanguage: 'pl-PL',layout
Can be set at: grid
options.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
Category: Core
Since: 18.0.0
Example
// render pagination above a custom 'summary' element registered in the bottom slotlayout: { bottom: ['pagination', 'summary'],},
// in the start side slot, render a custom 'filters' panel at the outer edge, before a custom 'notes' panellayout: { start: ['filters', 'notes'],},layoutDirection
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
inherit (default) | Set Handsontable’s layout direction automatically, based on the value of your HTML document’s dir attribute |
rtl | Render Handsontable from the right to the left, even when your HTML document’s dir attribute is set to ltr |
ltr | Render 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”
Category: Core
Example
// inherit Handsontable's layout direction// from the value of your HTML document's `dir` attributelayoutDirection: '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
options.licenseKey : string
The licenseKey option sets your Handsontable license key.
You can set the licenseKey option to one of the following:
| Setting | Description |
|---|---|
| A string with your commercial license key | For 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
Category: Core
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 literallicenseKey: `This is a Handsontable license key for Acme Corp, ... for the "Acme Portal" project. ... [eyJwcm9kdWN0cyI6...3a4f8361]`,limitFixedToViewport
Can be set at: grid
options.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:
getSettings()still returns the values offixedColumnsStart,fixedColumnsEnd,fixedRowsTop, andfixedRowsBottom.- 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
FreezeBarplugin, 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 itsafterColumnFreezehook 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
Category: Core
Since: 19.0.0
Example
// draw only the frozen columns and rows that fit the gridlimitFixedToViewport: true,loading
Can be set at: grid
options.loading : boolean | object
The loading option configures the Loading plugin.
The Loading plugin depends on the Dialog plugin and turns it
on while loading is enabled, so you don’t need to set dialog: true. The dialog
option itself keeps its value. When you turn loading off, the Dialog plugin turns off too, unless
the dialog option is set.
You can set the loading option to one of the following:
| Setting | Description |
|---|---|
false | Disable the Loading plugin |
true | Enable the Loading plugin with default configuration |
| An object | - Enable the Loading plugin- Apply custom configuration |
If you set the loading option to an object, you can configure the following loading options:
| Option | Possible settings | Description |
|---|---|---|
icon | A string | Custom loading icon to display (default: <svg />) |
title | A string | Custom loading title to display (default: 'Loading...') |
description | A string | Custom loading description to display (default: '') |
title and description render as text. Markup passed in them shows up literally rather
than being interpreted, so use icon for the one slot that takes markup.
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.
The loading indicator is available on the main grid only. In a grid nested in a cell, that is a
cell of the
handsontable,
autocomplete, or
dropdown cell type, this
option has no effect.
Default: false
Category: Loading
Since: 16.1.0
Example
// enable the `Loading` plugin with default configurationloading: true,
// enable the `Loading` plugin with custom configurationloading: { icon: 'A custom loading icon in SVG format', title: 'Custom loading title', description: 'Custom loading description',}locale
Can be set at: grid columns cells cell
options.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”
Category: Core
Example
// set the entire grid's locale to Polishlocale: 'pl-PL',
// set individual columns' localescolumns: [ { // set the first column's locale to Polish locale: 'pl-PL', }, { // set the second column's locale to German locale: 'de-DE', },],manualColumnFreeze
Can be set at: grid
options.manualColumnFreeze : boolean | object
The manualColumnFreeze option configures the ManualColumnFreeze plugin.
You can set the manualColumnFreeze option to one of the following:
| Setting | Description |
|---|---|
true | Enable the ManualColumnFreeze plugin |
false | Disable the ManualColumnFreeze plugin |
| An object | Enable the ManualColumnFreeze plugin and configure it |
The object form accepts the following property:
| Property | Type | Default | Description |
|---|---|---|---|
restoreColumnPosition | boolean | false | When true, an unfrozen column goes back among the scrollable columns by its data source order: right after the last scrollable column that comes before it in the data source. When false, it stays right after the frozen columns. Available since 19.0.0. |
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
Category: ManualColumnFreeze
Example
// enable the `ManualColumnFreeze` pluginmanualColumnFreeze: true,
// enable the `ManualColumnFreeze` plugin, and move an unfrozen column back by its data source ordermanualColumnFreeze: { restoreColumnPosition: true,},manualColumnMove
Can be set at: grid
options.manualColumnMove : boolean | Array<number>
The manualColumnMove option configures the ManualColumnMove plugin.
You can set the manualColumnMove option to one of the following:
| Setting | Description |
|---|---|
true | Enable the ManualColumnMove plugin |
false | Disable the ManualColumnMove plugin |
| An array | - Enable the ManualColumnMove plugin- Move individual columns 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: undefined
Category: ManualColumnMove
Example
// enable the `ManualColumnMove` pluginmanualColumnMove: true,
// enable the `ManualColumnMove` plugin// at initialization, move column 0 to 1// at initialization, move column 1 to 4// at initialization, move column 2 to 6manualColumnMove: [1, 4, 6],manualColumnResize
Can be set at: grid
options.manualColumnResize : boolean | Array<number>
The manualColumnResize option configures the ManualColumnResize plugin.
You can set the manualColumnResize option to one of the following:
| Setting | Description |
|---|---|
true | Enable the ManualColumnResize plugin |
false | Disable the ManualColumnResize plugin |
| An array | - Enable the ManualColumnResize plugin- Set initial widths of individual columns |
Read more:
When you set initial widths through the array form, those columns are excluded from
stretchH redistribution. Only the columns without a pre-defined width are stretched.
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
Category: ManualColumnResize
Example
// enable the `manualColumnResize` pluginmanualColumnResize: true,
// enable the `manualColumnResize` plugin// set the initial width of column 0 to 40 pixels// set the initial width of column 1 to 50 pixels// set the initial width of column 2 to 60 pixelsmanualColumnResize: [40, 50, 60],manualRowMove
Can be set at: grid
options.manualRowMove : boolean | Array<number>
The manualRowMove option configures the ManualRowMove plugin.
You can set the manualRowMove option to one of the following:
| Setting | Description |
|---|---|
true | Enable the ManualRowMove plugin |
false | Disable the ManualRowMove plugin |
| An array | - Enable the ManualRowMove plugin- Move individual rows 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: undefined
Category: ManualRowMove
Example
// enable the `ManualRowMove` pluginmanualRowMove: true,
// enable the `ManualRowMove` plugin// at initialization, move row 1 to 0// at initialization, move row 4 to 1// at initialization, move row 6 to 2manualRowMove: [1, 4, 6],manualRowResize
Can be set at: grid
options.manualRowResize : boolean | Array<number>
The manualRowResize option configures the ManualRowResize plugin.
You can set the manualRowResize option to one of the following:
| Setting | Description |
|---|---|
true | Enable the ManualRowResize plugin |
false | Disable the ManualRowResize plugin |
| An array | - Enable the ManualRowResize plugin- Set initial heights of individual 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: undefined
Category: ManualRowResize
Example
// enable the `ManualRowResize` pluginmanualRowResize: true,
// enable the `ManualRowResize` plugin// set the initial height of row 0 to 40 pixels// set the initial height of row 1 to 50 pixels// set the initial height of row 2 to 60 pixelsmanualRowResize: [40, 50, 60],maxCols
Can be set at: grid
options.maxCols : number
The maxCols option sets a maximum number of columns.
The maxCols option is used:
- At initialization: if the
maxColsvalue 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
Category: Core
Example
// set the maximum number of columns to 300maxCols: 300,maxLength
Can be set at: grid columns cells cell
options.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
texteditor, and any custom editor that extends it, stops the user from typing or pasting more characters than the limit allows. Theautocomplete,dropdown, andhandsontableeditors 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 asnumeric,date, andpassword, don’t limit input. - In the cell validator, which marks a
value that is too long as invalid. Use
allowInvalidto decide whether the grid keeps such a value. The validator checks the values that you type, paste into the grid, or write withsetDataAtCell(), and the values thatvalidateCells()checks. It doesn’t check the values that you load withloadData(),updateData(), orsetSourceDataAtCell(), or that a data provider fetches. Such a value stays unmarked until you callvalidateCells().
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
numericcell, 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
maxLengthat the grid level, it also applies to the text ofdate,time,dropdown, andautocompletecells, so a date such as'2026-10-02'is invalid withmaxLength: 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, andgetDataAtCell()returns the previous value until then. Use theafterChangehook to react to the new value. - The editor and the validator both count the value after
trimWhitespaceis applied, so the leading and trailing spaces of a pasted text don’t count. - With the
Formulasplugin, the editor counts the formula that the user types, but the validator counts the calculated result. WithmaxLength: 5, the editor cuts=SUM(A1:A10)to=SUM(, although the result55fits. - If your app already uses
maxLengthas 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
Category: Core
Since: 19.0.0
Example
// limit the free-text columns, and leave the others unlimitedcolumns: [ { data: 'code', maxLength: 10 }, { data: 'comment', maxLength: 140, allowInvalid: false }, { data: 'quantity', type: 'numeric' },],
// let a single cell hold more than its column allowscell: [ { row: 0, col: 0, maxLength: 20 },],maxRows
Can be set at: grid
options.maxRows : number
The maxRows option sets a maximum number of rows.
The maxRows option is used:
- At initialization: if the
maxRowsvalue 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
Category: Core
Example
// set the maximum number of rows to 300maxRows: 300,maxSelections
Can be set at: grid columns cells cell
options.maxSelections : number
The maxSelections option sets a maximum number of selections for the multiSelect-typed cells.
Default: undefined
Category: Core
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,}],mergeCells
Can be set at: grid
options.mergeCells : boolean | Array<object>
The mergeCells option configures the MergeCells plugin.
You can set the mergeCells option to one of the following:
| Setting | Description |
|---|---|
true | Enable the MergeCells plugin |
false | Disable the MergeCells plugin |
| An array of objects | - Enable the MergeCells plugin- Merge specific cells at initialization |
| { virtualized: true } | Enable the MergeCells plugin with enabled virtualization mode |
To merge specific cells at Handsontable’s initialization,
set the mergeCells option to an array of objects, with the following properties:
| Property | Description |
|---|---|
row | The visual row index of the merged section’s beginning |
col | The visual column index of the merged section’s beginning |
rowspan | The width (as a number of rows) of the merged section |
colspan | The height (as a number of columns ) of the merged section |
This option can only be set at the grid level.
It has no effect when set in the columns, cells, or cell options.
A merged range clears the cells it covers. Re-applying the same value through
updateSettings() clears only the cells that still hold a
value, so a range that is already empty fires no beforeChange or afterChange event. Values
that come back into a covered range — through new data, a sort, a filter, or a row move — are
cleared on the next re-apply, as before. This assumes the clearing write reaches the data:
cancel it (a beforeChange returning false, or a validator rejecting null) and every
re-apply tries again.
While a filter hides rows, a re-applied range that fits the rows on screen is applied to those rows. A range that reaches past them can’t be applied, so if it was applied before and its merged cell still covers the rows it was merged on, that merged cell is kept, with its values, until the filter is cleared.
Read more:
Default: false
Category: MergeCells
Example
// enable the `MergeCells` pluginmergeCells: true,
// enable the `MergeCells` plugin// and merge specific cells at initializationmergeCells: [ // merge cells from cell (1,1) to cell (3,3) {row: 1, col: 1, rowspan: 3, colspan: 3}, // merge cells from cell (3,4) to cell (2,2) {row: 3, col: 4, rowspan: 2, colspan: 2}, // merge cells from cell (5,6) to cell (3,3) {row: 5, col: 6, rowspan: 3, colspan: 3}],
// enable the `MergeCells` plugin with enabled virtualization mode// and merge specific cells at initializationmergeCells: { virtualized: true, cells: [ // merge cells from cell (1,1) to cell (3,3) {row: 1, col: 1, rowspan: 3, colspan: 3}, // merge cells from cell (3,4) to cell (2,2) {row: 3, col: 4, rowspan: 2, colspan: 2}, // merge cells from cell (5,6) to cell (3,3) {row: 5, col: 6, rowspan: 3, colspan: 3} ],},minCols
Can be set at: grid
options.minCols : number
The minCols option sets a minimum number of columns.
The minCols option is used:
- At initialization: if the
minColsvalue 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:
- The first data row
- The
dataSchemaoption - The
columnsoption
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
Category: Core
Example
// set the minimum number of columns to 10minCols: 10,minRowHeights
Can be set at: grid
options.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
Category: Core
Since: 16.2.0
Example
// set every row's minimum height to 100pxminRowHeights: 100,
// set every row's minimum height to 100pxminRowHeights: '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 valueminRowHeights: [100, 120],
// set each row's minimum height individually, using a functionminRowHeights(physicalRowIndex) { return physicalRowIndex * 10;},minRows
Can be set at: grid
options.minRows : number
The minRows option sets a minimum number of rows.
The minRows option is used:
- At initialization: if the
minRowsvalue 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
Category: Core
Example
// set the minimum number of rows to 10minRows: 10,minSpareCols
Can be set at: grid
options.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:
- The first data row
- The
dataSchemaoption - The
columnsoption
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
Category: Core
Example
// at Handsontable's initialization, add at least 3 empty columns on the rightminSpareCols: 3,minSpareRows
Can be set at: grid
options.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
Category: Core
Example
// at Handsontable's initialization, add at least 3 empty rows at the bottomminSpareRows: 3,moveCells
Can be set at: grid
options.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
Category: Core
Since: 18.1.0
Example
// enable drag-to-move for selectionsmoveCells: true,multiColumnSorting
Can be set at: grid columns
options.multiColumnSorting : boolean | object
The multiColumnSorting option configures the MultiColumnSorting plugin.
You can set the multiColumnSorting option to one of the following:
| Setting | Description |
|---|---|
true | Enable the MultiColumnSorting plugin with the default configuration |
false | Disable the MultiColumnSorting plugin |
| An object | - Enable the MultiColumnSorting plugin- Modify the MultiColumnSorting plugin options |
If you set the multiColumnSorting option to an object,
you can set the following MultiColumnSorting plugin options:
| Option | Possible settings |
|---|---|
indicator | true: Display the arrow icon in the column header, to indicate a sortable columnfalse: Don’t display the arrow icon in the column header |
headerAction | true: Enable clicking on the column header to sort the columnfalse: Disable clicking on the column header to sort the column |
sortEmptyCells | true: Sort empty cells as wellfalse: Place empty cells at the end |
sortFixedRows | true: Sort the whole dataset, including the rows pinned by fixedRowsTop and fixedRowsBottomfalse: Keep the pinned rows in placeGrid-level only |
compareFunctionFactory | A custom compare function |
If you set the multiColumnSorting option to an object,
you can also sort individual columns at Handsontable’s initialization.
In the multiColumnSorting object, add an object named initialConfig,
with the following properties:
| Option | Possible settings | Description |
|---|---|---|
column | A number | The index of the column that you want to sort at initialization |
sortOrder | 'asc' | 'desc' | The sorting order:'asc': ascending'desc': descending |
Read more:
Default: undefined
Category: MultiColumnSorting
Example
// enable the `MultiColumnSorting` pluginmultiColumnSorting: true
// enable the `MultiColumnSorting` plugin with custom configurationmultiColumnSorting: { // sort empty cells as well sortEmptyCells: true, // display the arrow icon in the column header indicator: true, // disable clicking on the column header to sort the column headerAction: false, // sort the pinned rows along with the rest of the dataset sortFixedRows: true, // add a custom compare function compareFunctionFactory(sortOrder, columnMeta) { return function(value, nextValue) { // some value comparisons which will return -1, 0 or 1... } }}
// enable the `MultiColumnSorting` plugin with a multi-column initial sort order:// sort column 1 ascending first, then column 2 descendingmultiColumnSorting: { initialConfig: [ { column: 1, sortOrder: 'asc' }, { column: 2, sortOrder: 'desc' } ]}navigableHeaders
Can be set at: grid
options.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
Category: Core
Since: 14.0.0
Example
// you can navigate row and column headers with the keyboardnavigableHeaders: true,
// default behavior: you can't navigate row and column headers with the keyboardnavigableHeaders: false,nestedHeaders
Can be set at: grid
options.nestedHeaders : boolean | Array<Array>
The nestedHeaders option configures the NestedHeaders plugin.
You can set the nestedHeaders option to one of the following:
| Setting | Description |
|---|---|
false (default) | Disable the NestedHeaders plugin |
true | - Enable the NestedHeaders plugin- Don’t configure any nested headers |
| Array of arrays | - Enable the NestedHeaders plugin- Configure headers that are nested on Handsontable’s initialization |
If you set the nestedHeaders option to an array of arrays, each array configures one row of
nested headers (top row first). Within a row, headers are listed left to right.
Each array element configures one header, and can be one of the following:
| Array element | Description |
|---|---|
| A string | The header’s label |
| An object | A header configuration object (see the properties below) |
A header configuration object accepts the following properties:
| Property | Type | Description |
|---|---|---|
label | string | The header’s label. |
colspan | number | The number of data columns the header spans (an integer greater than 1). Groups the columns it covers. |
rowspan | number | The number of header rows the header spans (an integer greater than 1). |
headerClassName | string | One or more space-separated CSS class names added to the header element (for example, 'htRight'). |
visibleWhen | string | For a header inside a collapsible group, sets in which collapse state the header (and its columns) stays visible: 'collapsed' (visible only while the group is collapsed), 'expanded' (visible only while the group is expanded), or 'always' (visible in both states). When omitted, a header in such a group defaults to 'expanded' - it is hidden when the group collapses. At least one column of a group always stays visible. |
columnDropMode | string | Controls what a group does when a column move (with the ManualColumnMove plugin) drops a foreign column (one belonging to another group) into its span. With 'adopt' (default), the group adopts that column as a child and stays one banner. With 'split', the group keeps its identity and renders as several same-label banners around the foreign column (it splits). A group always reclaims its own columns when they move back into its span, regardless of this setting. Meaningful only on a header that spans columns. |
Read more:
- Plugins:
NestedHeaders - Security: Content sanitizing
- Column groups: Nested headers
- Column groups: Choose which columns stay visible when collapsed
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
Category: NestedHeaders
Example
// group headers with `label` and `colspan`nestedHeaders: [ ['A', {label: 'B', colspan: 8}, 'C'], ['D', {label: 'E', colspan: 4}, {label: 'F', colspan: 4}, 'G'], ['H', 'I', 'J', 'K', 'L', 'M', 'N', 'R', 'S', 'T']],
// choose which columns stay visible when a collapsible group is collapsed:// unmarked headers (Jan, Feb, Mar) are hidden on collapse; `Total` appears only when collapsednestedHeaders: [ ['Region', {label: 'Q1 2025', colspan: 4}], ['Region', 'Jan', 'Feb', 'Mar', {label: 'Total', visibleWhen: 'collapsed'}]],collapsibleColumns: true,nestedRows
Can be set at: grid
options.nestedRows : boolean
The nestedRows option configures the NestedRows plugin.
You can set the nestedRows option to one of the following:
| Setting | Description |
|---|---|
false (default) | Disable the NestedRows plugin |
true | Enable the NestedRows plugin |
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
Category: NestedRows
Example
// enable the `NestedRows` pluginnestedRows: true,notification
Can be set at: grid
options.notification : boolean | object
The notification option configures the Notification plugin.
You can set the notification option to one of the following:
| Setting | Description |
|---|---|
false | Disable the Notification plugin |
true | Enable the plugin with default options |
| An object | Enable the plugin and set stackLimit and animation |
notification: Additional options
| Option | Type | Default | Description |
|---|---|---|---|
stackLimit | number | 10 | Maximum visible toasts per corner. Extra requests are queued. |
animation | boolean | true | Fade and slide animation when toasts appear. |
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.
Notifications are available on the main grid only. In a grid nested in a cell, that is a cell of
the handsontable,
autocomplete, or
dropdown cell type, this
option has no effect.
Default: false
Category: Notification
Since: 17.1.0
Example
notification: true,noWordWrapClassName
Can be set at: grid columns cells cell
options.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:
wordWrapcurrentRowClassNamecurrentColClassNamecurrentHeaderClassNameinvalidCellClassNamereadOnlyCellClassNamecommentedCellClassNamenoWordWrapClassNameTableClassNameclassName
Default: “htNoWrap”
Category: Core
Example
// add an `is-noWrapCell` CSS class name// to each cell that doesn't wrap contentnoWordWrapClassName: 'is-noWrapCell',numericFormat
Can be set at: grid columns cells cell
options.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:
| Property | Possible values | Description |
|---|---|---|
style | 'decimal' (default), 'currency', 'percent', 'unit' | The formatting style to use |
currency | ISO 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 |
unit | Unit identifiers (e.g., 'kilometer', 'liter') | Required when style is 'unit' |
unitDisplay | 'short' (default), 'narrow', 'long' | How to display the unit |
Notation options:
| Property | Possible values | Description |
|---|---|---|
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:
| Property | Possible values | Description |
|---|---|---|
signDisplay | 'auto' (default), 'never', 'always', 'exceptZero', 'negative' | When to display the sign |
useGrouping | true, false (default), 'always', 'auto', 'min2' | Whether to use grouping separators (e.g., 1,000) |
Digit options:
| Property | Possible values | Description |
|---|---|---|
minimumIntegerDigits | 1 to 21 | Minimum number of integer digits (pads with zeros) |
minimumFractionDigits | 0 to 100 | Minimum number of fraction digits |
maximumFractionDigits | 0 to 100 | Maximum number of fraction digits |
minimumSignificantDigits | 1 to 21 | Minimum number of significant digits |
maximumSignificantDigits | 1 to 21 | Maximum number of significant digits |
Rounding options:
| Property | Possible values | Description |
|---|---|---|
roundingMode | 'halfExpand' (default), 'ceil', 'floor', 'expand', 'trunc', 'halfCeil', 'halfFloor', 'halfTrunc', 'halfEven' | Rounding algorithm |
roundingPriority | 'auto' (default), 'morePrecision', 'lessPrecision' | Priority between fraction and significant digits |
roundingIncrement | 1, 2, 5, 10, 20, 25, 50, 100, 200, 250, 500, 1000, 2000, 2500, 5000 | Increment for rounding (e.g., nickel rounding) |
trailingZeroDisplay | 'auto' (default), 'stripIfInteger' | Whether to strip trailing zeros for integers |
Locale options:
| Property | Possible values | Description |
|---|---|---|
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
Category: Core
Since: 0.35.0
Example
columns: [ { type: 'numeric', locale: 'en-US', numericFormat: { style: 'currency', currency: 'USD', } }],observeDOMVisibility
Can be set at: grid
options.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
Category: Core
Example
// don't rerender the grid on visibility changesobserveDOMVisibility: false,outsideClickDeselects
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
true (default) | On a mouse click outside of the grid, clear the current selection |
false | On a mouse click outside of the grid, keep the current selection |
| A function | A 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
Category: Core
Example
// on a mouse click outside of the grid, clear the current selectionoutsideClickDeselects: true,
// on a mouse click outside of the grid, keep the current selectionoutsideClickDeselects: 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;}pagination
Can be set at: grid
options.pagination : boolean
The pagination option configures the Pagination plugin.
You can set the pagination option to one of the following:
| Setting | Description |
|---|---|
false | Disable the Pagination plugin |
true | Enable the Pagination plugin |
pagination: Additional options
If you set the pagination option to an object, you can set the following Pagination plugin options:
| Option | Possible settings | Description |
|---|---|---|
pageSize | A number or auto (default: 10) | Sets the number of rows displayed per page. If 'auto' is set, the page size will be calculated to match all rows to the currently set table’s viewport height |
pageSizeList | An array (default: ['auto', 5, 10, 20, 50, 100]) | Defines the selectable values for page size in the UI |
initialPage | A number (default: 1) | Specifies which page to display on initial load. The plugin applies the value when it first enables and when you change it. Passing the same number again does not reset the current page. |
showPageSize | Boolean (default: true) | Controls visibility of the “page size” section |
showCounter | Boolean (default: true) | Controls visibility of the “page counter” section (e.g., “1 - 10 of 50”); |
showNavigation | Boolean (default: true) | Controls visibility of the “page navigation” section |
uiContainer | An HTML element (default: null) | The container element where the pagination UI will be installed. If not provided, the pagination container will be injected below the root table 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.
Pagination is available on the main grid only. In a grid nested in a cell, that is a cell of the
handsontable,
autocomplete, or
dropdown cell type, this
option has no effect.
Default: undefined
Category: Pagination
Since: 16.1.0
Example
// enable the `Pagination` pluginpagination: true,parsePastedValue
Can be set at: grid columns cells cell
options.parsePastedValue : boolean
The parsePastedValue option determines how pasted content is written to cells when the user pastes
from the clipboard into Handsontable (e.g. from another Handsontable instance or between cells in the same table).
It does not affect how other applications read or process the clipboard.
When set to false, pasted content is written as plain strings. Non-scalar values (e.g. objects) are coerced
to string, so an object becomes "[object Object]".
When set to true, pasted text is parsed so that JSON-like (or other supported) values are converted to
JavaScript values and written to the data source. This allows copying and pasting more sophisticated JavaScript
structures (e.g. objects, arrays) between cells and between Handsontable instances. Cells then store the resulting
object (e.g. { id: 1, value: 'A1' }). Schema validation is relaxed so object-based values can be pasted into
cells that would normally expect a scalar.
You can set the parsePastedValue option to one of the following:
| Setting | Description |
|---|---|
false (default) | Write pasted content as plain strings |
true | Parse pasted text and write JavaScript values |
Default: false
Category: CopyPaste
Since: 17.0.0
Example
// write pasted content as strings (objects become "[object Object]")parsePastedValue: false,Example
// parse pasted text so cells receive JavaScript objects when pasted content is object-likeparsePastedValue: true,placeholder
Can be set at: grid columns cells cell
options.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:
| Setting | Example | Description |
|---|---|---|
| A non-empty string | 'Empty cell' | Display Empty cell text in empty cells |
| A non-string value | 000 | Display 000 text in empty cells (non-string values get stringified) |
Read more:
Default: undefined
Category: Core
Example
// display 'Empty cell' text// in every empty cell of the entire gridplaceholder: 'Empty cell',
// orcolumns: [ { 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
options.placeholderCellClassName : string
The placeholderCellClassName option lets you add a CSS class name to cells
that contain placeholder text.
Read more:
- Cell validator
placeholdercurrentRowClassNamecurrentHeaderClassNameactiveHeaderClassNamecurrentColClassNamereadOnlyCellClassNamecommentedCellClassNamenoWordWrapClassNameTableClassNameclassName
Default: “htPlaceholder”
Category: Core
Example
// add a `has-placeholder` CSS class name// to each cell that contains `placeholder` textplaceholderCellClassName: 'has-placeholder',preserveNumericLiteral
Can be set at: grid columns cells cell
options.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
Category: Core
Since: 18.1.0
Example
columns: [ { type: 'numeric', // keep `9.0` and very large numbers as typed in the editor preserveNumericLiteral: true, }],preserveTextValue
Can be set at: grid columns cells cell
options.preserveTextValue : boolean
The preserveTextValue option configures whether the Formulas
plugin passes values of text-type cells
to the calculation engine as strings. This protects them from number coercion.
By default, the engine parses number-like strings into numbers. A text cell that
holds 0123456 reaches formulas as 123456 – the leading zero is lost. With
preserveTextValue enabled, the value stays a string: =LEN(A1) returns 7, and
concatenation keeps the leading zero.
You can set the preserveTextValue option to one of the following:
| Setting | Description |
|---|---|
false (default) | The engine parses values of text cells (number coercion) |
true | Values of text cells reach the engine as strings |
The option takes effect only for cells of the text type – the default cell
type, so setting preserveTextValue at the grid level affects every cell that doesn’t
declare another type – and only when the Formulas plugin is
enabled. Custom cell types aren’t supported, even when they reuse the text editor or
renderer.
Set the option globally, per column, or per cell (through the cell option or
the cells function).
Read more:
Default: false
Category: Formulas
Since: 18.1.0
Example
columns: [ { type: 'text', // keep leading zeros of number-like strings in formula results preserveTextValue: true, },],preventOverflow
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
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
Category: Core
Example
// prevent horizontal overflowingpreventOverflow: 'horizontal',readOnly
Can be set at: grid columns cells cell
options.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:
| Setting | Description |
|---|---|
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
Category: Core
Example
// make the entire grid read-onlyconst configurationOptions = { columnSorting: true,};
// make the third column read-onlyconst configurationOptions = { columns: [ {}, {}, { readOnly: true, }, ],};
// make a specific cell read-onlyconst configurationOptions = { cell: [ { row: 0, col: 0, readOnly: true, },};readOnlyCellClassName
Can be set at: grid columns cells cell
options.readOnlyCellClassName : string
The readOnlyCellClassName option lets you add a CSS class name to read-only cells.
Read more:
currentRowClassNamecurrentColClassNamecurrentHeaderClassNameactiveHeaderClassNameinvalidCellClassNameplaceholderCellClassNamecommentedCellClassNamenoWordWrapClassNamereadOnlyCellClassNameTableClassName
Default: “htDimmed”
Category: Core
Example
// add a `is-readOnly` CSS class name// to every read-only cellreadOnlyCellClassName: 'is-readOnly',readOnlyStyling
Can be set at: grid columns cells cell
options.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:
| Setting | Description |
|---|---|
true (default) | Read-only cells are dimmed, through the readOnlyCellClassName CSS class |
false | Read-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
Category: Core
Since: 19.0.0
Example
// make the whole grid read-only, but keep it looking like a normal tablereadOnly: true,readOnlyStyling: false,
// apply the option to individual columnscolumns: [ { readOnly: true, // this column is read-only, and is not dimmed readOnlyStyling: false }]renderAllColumns
Can be set at: grid
options.renderAllColumns : boolean
The renderAllColumns option configures Handsontable’s column virtualization.
You can set the renderAllColumns option to one of the following:
| Setting | Description |
|---|---|
false (default) | Enable column virtualization, rendering only visible columns for better performance with many columns. |
true | Disable 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
Category: Core
Since: 14.1.0
Example
// disable column virtualizationrenderAllColumns: true,renderAllRows
Can be set at: grid
options.renderAllRows : boolean
The renderAllRows option controls Handsontable’s row virtualization.
You can configure it as follows:
| Setting | Description |
|---|---|
false (default) | Enable row virtualization, rendering only the visible rows for optimal performance with large datasets. |
true | Disable 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
Category: Core
Example
// disable row virtualizationrenderAllRows: true,renderer
Can be set at: grid columns cells cell
options.renderer : string | function
The renderer option sets a cell renderer for a cell.
You can set the renderer option to one of the following:
- A custom renderer function
- One of the following cell renderer aliases:
| Alias | Cell renderer function |
|---|---|
| A custom alias | Your 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
Category: Core
Example
// use the `numeric` renderer for each cell of the entire gridrenderer: `'numeric'`,
// add a custom renderer functionrenderer(hotInstance, td, row, column, prop, value, cellProperties) { // your custom renderer's logic ...}
// apply the `renderer` option to individual columnscolumns: [ { // 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
options.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:
| Setting | Description |
|---|---|
'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 thebeforeGetCellMetaandafterGetCellMetahooks), - 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”
Category: Core
Since: 19.0.0
Example
// paint every cell on every render (default)renderMode: 'always',
// paint only the cells that changedrenderMode: 'onChange',
// skip unchanged cells in one slow column onlycolumns: [ { data: 'chart', renderer: chartRenderer, renderMode: 'onChange' }, { data: 'name' },],rowHeaders
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
true | Enable the default row headers (‘1’, ‘2’, ‘3’, …) |
false | Disable row headers |
| An array | Define your own row headers (e.g. ['One', 'Two', 'Three', ...]) |
| A function | Define 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
Category: Core
Example
// enable the default row headersrowHeaders: true,
// set your own row headersrowHeaders: ['One', 'Two', 'Three'],
// set your own row headers, using a functionrowHeaders: function(visualRowIndex) { return `${visualRowIndex}: AB`;},rowHeaderWidth
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
| A number | Set the same width for every row header |
| A string | Set the same width, written as a pixel size ('25', '25px') |
| An array | Set 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
Category: Core
Example
// set the same width for every row headerrowHeaderWidth: 25,
// set the same width, written as a pixel sizerowHeaderWidth: '25px',
// set different widths for individual row headersrowHeaderWidth: [25, 30, 55],rowHeights
Can be set at: grid
options.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:
| Setting | Description | Example |
|---|---|---|
| A number | Set the same height for every row | rowHeights: 100 |
| A string | Set the same height for every row | rowHeights: '100px' |
| An array | Set heights separately for each row, by physical row index | rowHeights: [100, 120, undefined] |
| A function | Set row heights dynamically, on each render, by physical row index | rowHeights(physicalRowIndex) { return physicalRowIndex * 10; } |
undefined | Used 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
rowHeightsfunction. It states no fixed height, so it is left alone. - A grid whose
manualRowResizeoption is already a non-empty array. The plugin replays that array, so the stored heights stay. - The React, Angular and Vue wrappers, when the
rowHeightsprop 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
Category: Core
Example
// set every row's height to 100pxrowHeights: 100,
// set every row's height to 100pxrowHeights: '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 valuerowHeights: [100, 120, undefined],
// set each row's height individually, using a functionrowHeights(physicalRowIndex) { return physicalRowIndex * 10;},rowId
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
| A string | The 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 function | A function that receives the source row and returns its id |
true | Handsontable generates the ids: a number for each row, never reused within the instance |
false | No 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
Category: Core
Since: 19.0.0
Example
// read the id from the `id` property of each row objectrowId: '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 idsrowId: true,rowSelection
Can be set at: grid
options.rowSelection : boolean | object
The rowSelection option configures the RowSelection plugin, which
lets the user select rows with checkboxes, including a “select all” checkbox.
The row selection is a state of its own. It is not the cell selection, and the plugin never writes it into the data.
You can set the rowSelection option to one of the following:
| Setting | Description |
|---|---|
false | Disable the RowSelection plugin |
true | Enable the RowSelection plugin with its defaults |
| An object | Enable the plugin and configure it |
If you set the rowSelection option to an object, you can configure the following options:
| Option | Possible settings | Default |
|---|---|---|
mode | 'multiRow' | 'singleRow' | 'multiRow' |
checkboxes | A boolean, or a function (rowData, physicalRow) => boolean | true |
headerCheckbox | A boolean | true |
selectAll | 'all' | 'filtered' | 'currentPage' | 'all' |
enableClickSelection | true | false | 'enableSelection' | 'enableDeselection' | false |
isRowSelectable | A function (rowData, physicalRow) => boolean | - |
hideDisabledCheckboxes | A boolean | false |
checkboxLocation | 'rowHeader' | 'firstColumn' | { column } | 'rowHeader' |
groupSelects | 'descendants' | 'self' | 'topLevel' | 'descendants' |
With the NestedRows plugin, groupSelects sets how the rows of the tree are
selected. With 'descendants', selecting a parent row selects every row under it, and a parent shows a
mixed state while only some of the rows under it are selected. With 'self', every row is selected on its
own. With 'topLevel', only the top-level rows can be selected. The 'singleRow' mode and a bound
checkbox column (checkboxLocation: { column }) use 'self' in place of 'descendants'.
With checkboxLocation: { column: 'selected' }, the values of a checkbox column (its data property,
or its physical index) are the selection: selecting a row checks its cell, and checking a cell
selects its row.
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
Category: RowSelection
Since: 19.0.0
Example
// enable the `RowSelection` plugin with its defaultsrowSelection: true,
// "select all" acts on the filtered rows, and archived rows cannot be selectedrowSelection: { selectAll: 'filtered', isRowSelectable: (rowData) => rowData.status !== 'archived',},sanitizer
Can be set at: grid
options.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:
- cells rendered by the
passwordcell type - column and row headers, including
nestedHeaderslabels - context menu and dropdown menu item labels
selecteditor options- dialog and notification content
- HTML pasted from the clipboard, and Handsontable’s own clipboard payload carrying the source data behind copied cells
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
Category: Core
Since: 17.0.0
Example
// Allowlist-based sanitization using a custom librarysanitizer: (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, '&') .replace(/</g, '<') .replace(/>/g, '>') .replace(/"/g, '"') .replace(/'/g, ''');},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),search
Can be set at: grid columns cells cell
options.search : boolean | object
The search option enables and configures the Search plugin.
| Setting | Description |
|---|---|
false (default) | Disable the Search plugin |
true | Enable the Search plugin with the default configuration |
| An object | Enable the Search plugin and apply a custom configuration |
When set to an object, the following properties are supported:
| Property | Type | Default | Description |
|---|---|---|---|
searchResultClass | string | 'htSearchResult' | CSS class name applied to every cell where isSearchResult === true. |
queryMethod | Function | Case-insensitive substring match | Tests whether the query string matches a cell value. Signature: (queryStr: string, value: string|number|null, cellProperties: object) => boolean. |
callback | Function | Sets isSearchResult on cell metadata | Called for every cell after each test. Signature: (instance: Handsontable, row: number, col: number, data: string|number|null, testResult: boolean) => void. |
Default queryMethod behavior: case-insensitive, locale-aware substring match using toLocaleLowerCase() with cellProperties.locale.
Default callback behavior: sets instance.getCellMeta(row, col).isSearchResult = testResult on every cell.
Per-cell overrides: queryMethod and callback can also be set on individual cells, columns, or rows
using the cascading configuration model. A cell-level search.queryMethod or search.callback takes
precedence over the plugin-level setting for that cell. searchResultClass does not support per-cell overrides.
Read more:
Default: false
Category: Search
Example
// Enable with the default configurationsearch: true,
// Enable with a custom configurationsearch: { // Apply a custom CSS class to matching cells instead of 'htSearchResult' searchResultClass: 'customClass', // Replace the built-in substring match with exact matching queryMethod(queryStr, value, cellProperties) { if (!queryStr || queryStr.length === 0) return false; if (value === undefined || value === null) return false;
return queryStr.toString() === value.toString(); }, // Count results while preserving default highlighting callback(instance, row, col, data, testResult) { // Preserve the default isSearchResult flag so highlighting still works instance.getCellMeta(row, col).isSearchResult = testResult;
if (testResult) { // Custom logic: e.g., increment a result counter } }},
// Override queryMethod for a specific column only (per-cell via cascading config)columns: [ {}, { search: { queryMethod(queryStr, value) { return queryStr.toString() === value.toString(); // exact match for column 1 } } }],searchInput
Can be set at: grid columns cells cell
options.searchInput : boolean
The searchInput option configures whether the multiSelect editor’s search input is visible.
Default: true
Category: Core
Since: 17.0.0
Example
columns: [{ type: 'multiselect', // hide the `multiSelect` editor's search input searchInput: false,}],selectionHandles
Can be set at: grid
options.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
Category: Core
Since: 18.1.0
Example
// enable draggable selection-edge handlesselectionHandles: true,selectionMode
Can be set at: grid
options.selectionMode : string
The selectionMode option configures how selection works.
You can set the selectionMode option to one of the following:
| Setting | Description |
|---|---|
'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”
Category: Core
Example
// you can only select one cell at at a timeselectionMode: 'single',
// you can select one range of cells at a timeselectionMode: 'range',
// you can select multiple ranges of cells at a timeselectionMode: 'multiple',selectOptions
Can be set at: grid columns cells cell
options.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:
| Setting | Description |
|---|---|
| An array of strings | Each 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 function | A function that returns an object with key-string pairs |
Read more:
Default: undefined
Category: Core
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', }; },],sheetsBar
Can be set at: grid
options.sheetsBar : boolean | object
The sheetsBar option configures the SheetsBar plugin, which renders a tab bar
below the grid — or above it, with the position option — and lets the user
switch between the sheets of a multi-sheet workbook.
You can set the sheetsBar option to one of the following:
| Setting | Description |
|---|---|
undefined (default) | Disable the SheetsBar plugin |
false | Disable the SheetsBar plugin |
true | Enable the SheetsBar plugin |
sheetsBar: Additional options
If you set the sheetsBar option to an object, you can set the following SheetsBar plugin options:
| Option | Possible settings | Description |
|---|---|---|
sheets | An array of { name, data, settings } objects, or null | Defines the workbook. When omitted, the grid’s own data becomes a single Sheet1. When omitted and the formulas option’s engine is a HyperFormula instance that holds sheets, the bar shows one tab per engine sheet instead, plus one tab for the grid’s data when it is set. Like the data option, the plugin writes into the array: renames, added and duplicated sheets, and removals. Tab order and updateSheetSettings() changes aren’t written. Keep the array, its entries, and their data mutable and stable: the same array passed again keeps the workbook, while an array that describes other sheets rebuilds it. On a frozen array or entry, those changes are refused with a console warning |
activeSheet | A number (default: 0) | The position, within sheets (not in the tab order), of the sheet to activate on initialization. To switch sheets later, call setActiveSheet(). With sheetsBar: true, which declares no sheets, it counts in the tab order |
controls | Boolean (default: true) | Controls visibility of the add-sheet and all-sheets menu controls |
paging | Boolean (default: true) | Controls visibility of the tab-scrolling controls, shown when tabs overflow the bar’s width |
position | 'top' | 'bottom' (default: 'bottom') | The edge of the grid the bar renders on |
uiContainer | An HTML element (default: null) | An element of your page to render the bar in, instead of the grid’s edge. position and the layout option then don’t apply to the bar. If not provided, the bar renders on the edge of the grid that position names |
animation | Boolean, or an object of booleans (default: true) | Turns the tab animations on or off. false makes every tab change instant. An object turns single animations off: switch (the active tab marker’s slide), add (a new or duplicated tab’s entrance), remove (a removed tab’s exit and the tabs closing the gap), and move (the tabs sliding to new places after a move, and the tabs a drag pushes aside). A key you leave out stays on. Reduced motion and a theme with --ht-table-transition: 0s make every tab change instant whatever this option says. The hover color fade is CSS only and is not affected. An invalid value is ignored with a console warning, and the previous value stays in force |
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
Category: SheetsBar
Since: 19.0.0
Example
// enable the `SheetsBar` pluginsheetsBar: true,
// or, with a predefined workbooksheetsBar: { sheets: [ { name: 'Budget', data: [['Item', 'Cost'], ['Rent', 1200]] }, { name: 'Notes', data: [['Draft']] }, ], activeSheet: 0,},
// animate every tab change (the default)sheetsBar: { animation: true,},
// make every tab change instantsheetsBar: { animation: false,},
// keep the tab animations, except the slide after a movesheetsBar: { animation: { switch: true, add: true, remove: true, move: false },},skipColumnOnPaste
Can be set at: grid columns cells cell
options.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:
| Setting | Description |
|---|---|
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
Category: Core
Example
columns: [ { // disable pasting data into this column skipColumnOnPaste: true }],skipRowOnPaste
Can be set at: grid columns cells cell
options.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:
| Setting | Description |
|---|---|
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
Category: Core
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
options.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:
| Setting | Description |
|---|---|
true (default) | Sort options in the same order as provided in the source option |
false | Sort options alphabetically |
Read more:
Default: true
Category: Core
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
options.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
keyandvalueproperties - 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
Category: Core
Example
// set `source` to an array of string valuescolumns: [{ // 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` propertiescolumns: [{ // 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 functioncolumns: [{ // 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
options.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
Category: Core
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
options.sourceDataWarningMessage : string
The sourceDataWarningMessage option sets the message used when
a value fails sourceDataValidator. When not set, no message is logged.
Default: undefined
Category: Core
Since: 17.0.0
Example
sourceDataWarningMessage: 'The source data is invalid.',sourceLabel
Can be set at: grid columns cells cell
options.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:
| Setting | Description |
|---|---|
undefined | (Default) Display the value as it is |
| A string | Display the property of the value object at that path, for example 'name', 'address.city', or 'aliases.0' |
| A function | Display 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
Category: Core
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
options.sourceSortFunction : function
The sourceSortFunction option sets a function to sort the options available in multiSelect-typed cells.
Default: undefined
Category: Core
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
options.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
Category: Core
Example
// start with 15 empty columnsstartCols: 15,startRows
Can be set at: grid
options.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
Category: Core
Example
// start with 15 empty rowsstartRows: 15,stretchH
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
'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”
Category: Core
Example
// fit the grid to the container// by stretching all columns evenlystretchH: 'all',strict
Can be set at: grid columns cells cell
options.strict : boolean
The strict option configures the behavior of autocomplete cells.
You can set the strict option to one of the following:
| Setting | Mode | Description |
|---|---|---|
true | Strict mode | The end user: - Can only choose one of suggested values - Can’t enter a custom value |
false | Flexible mode | The 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
Category: Core
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
options.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:
| Setting | Description |
|---|---|
| A string | Add a single CSS class name to every Handsontable instance inside the container element |
| An array of strings | Add multiple CSS class names to every Handsontable instance inside the container element |
Read more:
currentRowClassNamecurrentColClassNamecurrentHeaderClassNameactiveHeaderClassNameinvalidCellClassNameplaceholderCellClassNamereadOnlyCellClassNamenoWordWrapClassNamecommentedCellClassNameclassName
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
Category: Core
Example
// add a `your-class-name` CSS class name// to every Handsontable instance inside the `container` elementtableClassName: 'your-class-name',
// add `first-class-name` and `second-class-name` CSS class names// to every Handsontable instance inside the `container` elementtableClassName: ['first-class-name', 'second-class-name'],tabMoves
Can be set at: grid
options.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):
| Property | Type | Description |
|---|---|---|
row | Number | - On pressing Tab, move selection row rows down- On pressing Shift+Tab, move selection row rows up |
col | Number | - 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}
Category: Core
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 lefttabMoves: {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+TabtabMoves(event) { return {row: 2, col: 2};},tabNavigation
Can be set at: grid
options.tabNavigation : boolean
The tabNavigation option decides what the Tab and Shift+Tab
keys do while the grid has the focus.
| Setting | Description |
|---|---|
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). |
false | The 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
Category: Core
Since: 14.0.0
Example
// Tab leaves the grid: one tab stop, the arrow keys move between cellstabNavigation: false,
// default behavior: Tab and Shift+Tab move between cellstabNavigation: true,textEllipsis
Can be set at: grid columns cells cell
options.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:
| Setting | Description |
|---|---|
false (default) | Don’t truncate text content with an ellipsis |
true | Keep text content on one line and truncate it with an ellipsis |
A number, 2 or greater | Wrap 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
Category: Core
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
options.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:
sanitizerdecides how content is written to the screen (HTML in, HTML out).textExtractordecides 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 & 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
Category: Core
Since: 19.0.0
Example
// Export headers as the text the grid displaystextExtractor: true,Example
// Keep row headers as they are, reduce column headers to texttextExtractor: (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
options.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:
| Setting | Description |
|---|---|
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 object | Apply a theme with default settings (import and pass the config, e.g. horizonTheme) |
A ThemeBuilder object | Apply a theme with runtime configuration (recommended) |
When using a ThemeBuilder object, you can configure the theme at runtime using these methods:
| Method | Description |
|---|---|
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
Category: Core
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 objectimport { 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
options.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
Category: Core
Since: 15.0.0
Example
themeName: 'ht-theme-name',timeFormat
Can be set at: grid columns cells cell
options.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:
| Property | Possible values | Description |
|---|---|---|
timeStyle | 'full', 'long', 'medium', 'short' | Time formatting style (expands to hour, minute, second, timeZoneName) |
Time component options:
| Property | Possible values | Description |
|---|---|---|
hour | 'numeric', '2-digit' | Representation of the hour |
minute | 'numeric', '2-digit' | Representation of the minute |
second | 'numeric', '2-digit' | Representation of the second |
fractionalSecondDigits | 1, 2, 3 | Fraction-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:
| Property | Possible values | Description |
|---|---|---|
localeMatcher | 'best fit' (default), 'lookup' | Locale matching algorithm |
timeZone | IANA time zone (e.g. 'UTC', 'America/New_York') | Time zone for formatting |
hour12 | true, false | Use 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’ }
Category: Core
Example
columns: [ { type: 'intl-time', locale: 'en-US', timeFormat: { timeStyle: 'medium' } }]title
Can be set at: columns
options.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
Category: Core
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
options.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:
| Setting | Description |
|---|---|
true (default) | Make the dropdown/autocomplete list’s width the same as the edited cell’s width |
false | Expand 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
Category: Core
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, }],trimRows
Can be set at: grid
options.trimRows : boolean | Array<number>
The trimRows option configures the TrimRows plugin.
You can set the trimRows option to one of the following:
| Setting | Description |
|---|---|
false | Disable the TrimRows plugin |
true | Enable the TrimRows plugin |
| An array of physical row indexes | - Enable the TrimRows plugin- Trim selected rows 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: undefined
Category: TrimRows
Example
// enable the `TrimRows` plugintrimRows: true,
// enable the `TrimRows` plugin// at Handsontable's initialization, trim rows 5, 10, and 15trimRows: [5, 10, 15],trimWhitespace
Can be set at: grid columns cells cell
options.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:
| Setting | Description |
|---|---|
true (default) | Remove whitespace at the beginning and at the end of each cell |
false | Don’t remove whitespace |
Default: true
Category: Core
Example
columns: [ { // don't remove whitespace // from any cell of this column trimWhitespace: false }]type
Can be set at: grid columns cells cell
options.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 type | Renderer, editor & validator |
|---|---|
| A custom cell type | Renderer: your custom cell renderer Editor: your custom cell editor Validator: your custom cell validator |
'autocomplete' | Renderer: AutocompleteRendererEditor: AutocompleteEditorValidator: AutocompleteValidator |
'checkbox' | Renderer: CheckboxRendererEditor: CheckboxEditorValidator: - |
'date' | Renderer: DateRendererEditor: DateEditorValidator: DateValidator |
'intl-date' | Renderer: IntlDateRendererEditor: IntlDateEditorValidator: IntlDateValidator |
'dropdown' | Renderer: DropdownRendererEditor: DropdownEditorValidator: DropdownValidator |
'handsontable' | Renderer: AutocompleteRendererEditor: HandsontableEditorValidator: - |
'numeric' | Renderer: NumericRendererEditor: NumericEditorValidator: NumericValidator |
'password' | Renderer: PasswordRendererEditor: PasswordEditorValidator: - |
'text' | Renderer: TextRendererEditor: TextEditorValidator: - |
'time’ | Renderer: TimeRendererEditor: TimeEditorValidator: TimeValidator |
'intl-time' | Renderer: IntlTimeRendererEditor: IntlTimeEditorValidator: IntlTimeValidator |
'intl-datetime' | Renderer: IntlDatetimeRendererEditor: IntlDatetimeEditorValidator: 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:
- Cell type
- Cell renderer
- Cell editor
- Cell validator
- Setting options: Cascading configuration
renderereditorvalidatorvalueParservalueFormatter
Default: “text”
Category: Core
Example
// set the `numeric` cell type for each cell of the entire gridtype: `'numeric'`,
// apply the `type` option to individual columnscolumns: [ { // 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
options.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:
| Setting | Description |
|---|---|
false (default) | If a checkbox cell is unchecked,the getDataAtCell method for this cell returns false |
| A string | If 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
Category: Core
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', }],undo
Can be set at: grid
options.undo : boolean | object
The undo option configures the UndoRedo plugin.
You can set the undo option to one of the following:
| Setting | Description |
|---|---|
true | Enable the UndoRedo plugin |
false | Disable the UndoRedo plugin |
{ maxHistory: <number> } | Enable the plugin, and keep at most maxHistory steps on the undo stack |
By default, the undo option is set to true, and the undo stack has no size limit.
To disable the UndoRedo plugin completely,
set the undo option to false. With false, nothing is recorded, so calling undo() through the
API undoes nothing either.
With maxHistory, the oldest step is dropped once the stack grows past the limit. maxHistory takes
a whole number from 0 up, or Infinity (no limit, the default); 0 keeps no steps. Lowering it
with updateSettings() drops the oldest steps at once. Any other value is ignored with a warning,
and the previous limit stays. The object form is available since 19.0.0.
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
Category: UndoRedo
Example
// enable the `UndoRedo` pluginundo: true,
// enable the `UndoRedo` plugin, and keep the last 100 stepsundo: { maxHistory: 100,},validator
Can be set at: grid columns cells cell
options.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:
| Setting | Description |
|---|---|
| A string | A cell validator alias |
| A function | Your custom cell validator function |
| A regular expression | A 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:
| Alias | Cell validator function |
|---|---|
| A custom alias | Your 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
Category: Core
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
options.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 case | Recommended option |
|---|---|
| Transform displayed value (add prefix, units) | valueFormatter |
| Custom date/number/text formatting | valueFormatter |
| 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| Parameter | Type | Description |
|---|---|---|
value | * | The raw cell value |
cellProperties | object | The cell’s meta object (see Core#getCellMeta) |
| Returns | * | The formatted value to display |
Read more:
Default: undefined
Category: Core
Since: 17.0.0
Example
// add a currency symbol to numeric valuesvalueFormatter(value, cellProperties) { if (value === null || value === undefined) { return ''; }
return `$${value}`;}
// format dates in a custom formatvalueFormatter(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 columnscolumns: [ { // 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
options.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
Category: Core
Since: 16.1.0
Example
// use the `label` property of the value object with a fallback to the value itselfvalueGetter: (value, row, column, cellMeta) => { return value?.label ?? value;}| Param | Type | Description |
|---|---|---|
| value | * | The value to be displayed in the cell. |
| row | number | The visual row index of the cell. |
| column | number | The visual column index of the cell. |
| cellMeta | object | The cell meta object. |
valueParser
Can be set at: grid columns cells cell
options.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 case | Option |
|---|---|
| Display: raw value -> shown text | valueFormatter |
| Edit: editor value -> source data | valueParser |
Function signature:
valueParser(value, cellProperties) => sourceValue| Parameter | Type | Description |
|---|---|---|
value | * | The value produced by the editor |
cellProperties | object | The cell’s meta object (see Core#getCellMeta) |
| Returns | * | The value to store in the source data |
Read more:
- Cell editor
editorrenderervalueFormattersourceDataValidator- Setting options: Cascading configuration
Default: undefined
Category: Core
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 numbervalueParser(value, cellProperties) { if (value == null || value === '') { return null; }
const num = Number(value.replace(/[^\d.-]/g, ''));
return Number.isNaN(num) ? value : num;}
// apply valueParser per columncolumns: [ { 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
options.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
Category: Core
Since: 16.1.0
Example
// Modify the value of a cell before it is savedvalueSetter: (value, row, column, cellMeta) => { return { id: value?.id ?? value, value: `${value?.value ?? value} at ${row}, ${column}` }},| Param | Type | Description |
|---|---|---|
| value | * | The value to be set to a cell. |
| row | number | The visual row index of the cell. |
| column | number | The visual column index of the cell. |
| cellMeta | object | The cell meta object. |
viewportColumnRenderingOffset
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
auto (default) | Use the offset calculated automatically by Handsontable |
| A number | Set 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’
Category: Core
Example
// render 70 columns outside of the grid's viewportviewportColumnRenderingOffset: 70,viewportColumnRenderingThreshold
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
auto | Triggers rendering at half the offset defined by viewportColumnRenderingOffset option |
| A number | Sets 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
Category: Core
Since: 1.14.7
Example
// render 12 columns outside of the grid's viewportviewportColumnRenderingOffset: 12,// the columns outside of the viewport will be rendered when the user scrolls to the 8th column from/toviewportColumnRenderingThreshold: 8,viewportRowRenderingOffset
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
auto (default) | Use the offset calculated automatically by Handsontable |
| A number | Set 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’
Category: Core
Example
// render 70 rows outside of the grid's viewportviewportRowRenderingOffset: 70,viewportRowRenderingThreshold
Can be set at: grid
options.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:
| Setting | Description |
|---|---|
auto | Triggers rendering at half the offset defined by viewportRowRenderingOffset option |
| A number | Sets 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
Category: Core
Since: 1.14.7
Example
// render 12 rows outside of the grid's viewportviewportRowRenderingOffset: 12,// the rows outside of the viewport will be rendered when the user scrolls to the 8th row from/toviewportRowRenderingThreshold: 8,visibleRows
Can be set at: grid columns cells cell
options.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
Category: Core
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
options.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:
| Setting | Example |
|---|---|
| A number of pixels | width: 500 |
| A string with a number of pixels | width: '500', width: '500px' |
| A string with a CSS unit | width: '50%', width: '75vw' |
'auto' | width: 'auto' |
| A function that returns a valid number or string | width() { 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
Category: Core
Example
// set the grid's width to 500pxwidth: 500,
// set the grid's width to 75vwwidth: '75vw',
// let the grid follow its parent container's widthwidth: 'auto',
// set the grid's width to 500px, using a functionwidth() { return 500;},wordWrap
Can be set at: grid columns cells cell
options.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:
| Setting | Description |
|---|---|
true (default) | If content exceeds the column’s width, wrap the content |
false | Don’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
Category: Core
Example
// set column width for every column of the entire gridcolWidths: 100,
columns: [ { // don't wrap content in this column wordWrap: false, }, { // if content exceeds this column's width, wrap the content wordWrap: true, }],Methods
isEmptyCol
Can be set at: grid
options.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.
Category: Core
Example
// overwrite the built-in `isEmptyCol` methodisEmptyCol(visualColumnIndex) { // your custom method ...},| Param | Type | Description |
|---|---|---|
| col | number | Visual column index. |
isEmptyRow
Can be set at: grid
options.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.
Category: Core
Example
// overwrite the built-in `isEmptyRow` methodisEmptyRow(visualRowIndex) { // your custom method ...},| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |