Constructor options.
Constructor options are applied using an object literal passed as a second argument to the Handsontable constructor.
const container = document.getElementById('example');
const hot = new Handsontable(container, {
data: myArray,
width: 400,
height: 300
});
Cascading configuration.
Handsontable is using Cascading Configuration, which is a fast way to provide configuration options
for the entire table, including its columns and particular cells.
Consider the following example:
const container = document.getElementById('example');
const hot = new Handsontable(container, {
readOnly: true,
columns: [
{readOnly: false},
{},
{},
],
cells: function(row, col, prop) {
var cellProperties = {};
if (row === 0 && col === 0) {
cellProperties.readOnly = true;
}.
return cellProperties;
}
});
The above notation will result in all TDs being read only, except for first column TDs which will be editable, except for the TD in top left corner which will still be read only.
The Cascading Configuration model
1. Constructor
Configuration options that are provided using first-level handsontable(container, {option: "value"})
and updateSettings
method.
2. Columns
Configuration options that are provided using second-level object handsontable(container, {columns: {option: "value"}]})
3. Cells
Configuration options that are provided using third-level function handsontable(container, {cells: function: (row, col, prop){ }})
Architecture performance
The Cascading Configuration model is based on prototypical inheritance. It is much faster and memory efficient
compared to the previous model that used jQuery extend. See: http://jsperf.com/extending-settings.
Important notice: In order for the data separation to work properly, make sure that each instance of Handsontable has a unique id
.
Members
-
activeHeaderClassNamestring
-
Class name for all active headers in selections. The header will be marked with this class name
only when a whole column or row will be selected.- Since: 0.38.2
- Default Value: 'ht__active_highlight'
Example
// this will add a 'ht__active_highlight' class name to appropriate table headers. activeHeaderClassName: 'ht__active_highlight',
-
allowEmptyboolean
-
If set to
true
, Handsontable will accept values that are empty (null
,undefined
or''
). If set
tofalse
, Handsontable will not accept the empty values and mark cell as invalid.- Default Value: true
Example
// allow empty values for all cells (whole table) allowEmpty: true, // or columns: [ { data: 'date', dateFormat: 'DD/MM/YYYY', // allow empty values only for the 'date' column allowEmpty: true } ],
-
allowHtmlboolean
-
If set to
true
, data defined insource
of the autocomplete or dropdown cell will be treated as HTML.Warning: Enabling this option can cause serious XSS vulnerabilities.
Note, this option only works for autocomplete-typed cells.
- Default Value: false
Example
columns: [{ type: 'autocomplete', // use HTML in the source list allowHtml: true, source: ['<strong>foo</strong>', '<strong>bar</strong>'] }],
-
allowInsertColumnboolean
-
If set to
false
, there won't be an option to insert new columns in the Context Menu.- Default Value: true
Example
// hide "Insert column left" and "Insert column right" options from the Context Menu allowInsertColumn: false,
-
allowInsertRowboolean
-
If set to
false
, there won't be an option to insert new rows in the Context Menu.- Default Value: true
Example
// hide "Insert row above" and "Insert row below" options from the Context Menu allowInsertRow: false,
-
allowInvalidboolean
-
If set to
true
, Handsontable will accept values that were marked as invalid by the cellvalidator
. It will
result with invalid cells being treated as valid (will save the invalid value into the Handsontable data source).
If set tofalse
, Handsontable will not accept the invalid values and won't allow the user to close the editor.
This option will be particularly useful when used with the Autocomplete'sstrict
mode.- Default Value: true
Example
// don't save the invalid values allowInvalid: false,
-
allowRemoveColumnboolean
-
If set to
false
, there won't be an option to remove columns in the Context Menu.- Default Value: true
Example
// hide "Remove column" option from the Context Menu allowRemoveColumn: false,
-
allowRemoveRowboolean
-
If set to
false
, there won't be an option to remove rows in the Context Menu.- Default Value: true
Example
// hide "Remove row" option from the Context Menu allowRemoveRow: false,
-
autoColumnSizeobject boolean
-
Enables or disables the
AutoColumnSize
plugin. Default value isundefined
, which has the same effect astrue
,
meaning, thesyncLimit
is set to 50.
Disabling this plugin can increase performance, as no size-related calculations would be done.Column width calculations are divided into sync and async part. Each of those parts has their own advantages and
disadvantages. Synchronous calculations are faster but they block the browser UI, while the slower asynchronous
operations don't block the browser UI.To configure the sync/async distribution, you can pass an absolute value (number of columns) or a percentage value.
You can also use the
useHeaders
option to take the column headers width into calculation.- Default Value: {syncLimit: 50}
Example
// as a number (300 columns in sync, rest async) autoColumnSize: {syncLimit: 300}, // as a string (percent) autoColumnSize: {syncLimit: '40%'}, // use headers width while calculating the column width autoColumnSize: {useHeaders: true},
-
autoRowSizeobject boolean
-
Enables or disables
AutoRowSize
plugin. Default value isundefined
, which has the same effect asfalse
(disabled). Enabling this plugin can decrease performance, as size-related calculations would be performed.Note: the default
syncLimit
value is set to 500 when the plugin is manually enabled by declaring it as:autoRowSize: true
.Row height calculations are divided into sync and async stages. Each of these stages has their own advantages and
disadvantages. Synchronous calculations are faster but they block the browser UI, while the slower asynchronous
operations don't block the browser UI.To configure the sync/async distribution, you can pass an absolute value (number of columns) or a percentage value.
- Default Value: undefined
Example
// as a number (300 columns in sync, rest async) autoRowSize: {syncLimit: 300}, // as a string (percent) autoRowSize: {syncLimit: '40%'},
-
autoWrapColboolean
-
If
true
, pressing ENTER or down arrow in the last row will move to the first row in the next column.- Default Value: true
Example
// stop ENTER key navigation on the last row autoWrapCol: false,
-
autoWrapRowboolean
-
If
true
, pressing TAB or right arrow in the last column will move to first column in next row.- Default Value: true
Example
// stop TAB key navigation on the last column autoWrapRow: false,
-
bindRowsWithHeadersboolean string
-
Enables the functionality of the
BindRowsWithHeaders
plugin which allows binding the table rows with their headers.
If the plugin is enabled, the table row headers will "stick" to the rows, when they are hidden/moved. Basically,
if at the initialization row 0 has a header titled "A", it will have it no matter what you do with the table.- Default Value: undefined
Example
// keep row data and row headers in sync bindRowsWithHeaders: true
-
cellArray.<Array>
-
Any constructor or column option may be overwritten for a particular cell (row/column combination), using
cell
array passed to the Handsontable constructor.- Default Value: []
Example
// make cell with coordinates (0, 0) read only cell: [ { row: 0, col: 0, readOnly: true } ],
-
cellsfunction
-
Defines the cell properties for given
row
,col
,prop
coordinates. Any constructor or column option may be
overwritten for a particular cell (row/column combination) using thecells
property in the Handsontable constructor.Note: Parameters
row
andcol
always represent physical indexes. Example below show how to execute
operations based on the visual representation of Handsontable.Possible values of
prop
:- property name for column's data source object, when dataset is an array of objects
- the same number as
col
, when dataset is an array of arrays.
- Default Value: undefined
Example
cells: function(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; } return cellProperties; },
-
checkedTemplateboolean string number
-
Data template for
'checkbox'
type when checkbox is checked.- Default Value: true
Example
checkedTemplate: 'good' // if a checkbox-typed cell is checked, then getDataAtCell(x, y), // where x and y are the coordinates of the cell will return 'good'.
-
classNamestring Array.<string>
-
Class name for the current element.
The interpretation depends on the level on which this option is provided in the cascading configuration.
IfclassName
is provided on the first (constructor) level, it is the applied to the Handsontable container.
IfclassName
is provided on the second (column
) or the third (cell
orcells
) level, it is applied to the table cell.- Default Value: undefined
Example
// can be set as a string className: 'your__class--name', // or as an array of strings className: ['first-class-name', 'second-class-name'],
-
colHeadersboolean Array.<string> function
-
Setting
true
orfalse
will enable or disable the default column headers (A, B, C).
You can also define an array['One', 'Two', 'Three', ...]
or a function to define the headers.
If a function is set, then the index of the column is passed as a parameter.- Default Value: null
Example
// as a boolean colHeaders: true, // as an array colHeaders: ['A', 'B', 'C'], // as a function colHeaders: function(index) { return index + ': AB'; },
-
collapsibleColumnsboolean Array.<object>
-
The
CollapsibleColumns
plugin allows collapsing of columns, covered by a header with thecolspan
property
defined.Clicking the "collapse/expand" button collapses (or expands) all "child" headers except the first one.
Setting the
collapsibleColumns
property totrue
will display a "collapse/expand" button in every
header with a defined colspan` property.To limit this functionality to a smaller group of headers, define the
collapsibleColumns
property
as an array of objects, as in the example below.- Default Value: undefined
Example
// enable collapsing for all headers collapsibleColumns: true, // or // enable collapsing for selected headers collapsibleColumns: [ {row: -4, col: 1, collapsible: true}, {row: -3, col: 5, collapsible: true} ],
-
columnHeaderHeightnumber Array.<number>
-
Allows setting a custom height of the column headers. You can provide a number or an array of heights, if many
column header levels are defined.- Default Value: undefined
Example
// set shared height for all headers columnHeaderHeight: 35, // or // set height for each header individually columnHeaderHeight: [35, 20, 55], // or // skipped headers will fallback to default value columnHeaderHeight: [35, undefined, 55],
-
columnsArray.<object> function
-
Defines the cell properties and data binding for certain columns.
Note: Using this option sets a fixed number of columns (options
startCols
,minCols
,maxCols
will be ignored).See documentation -> datasources.html for examples.
- Default Value: undefined
Example
// as an array of objects // order of the objects in array is representation of physical indexes. columns: [ { // column options for the first column type: 'numeric', numericFormat: { pattern: '0,0.00 $' } }, { // column options for the second column type: 'text', readOnly: true } ], // or as a function, based on physical indexes columns: function(index) { return { type: index > 0 ? 'numeric' : 'text', readOnly: index < 1 } }
-
columnSortingboolean object
-
Turns on Column sorting. Can be either a boolean (
true
/false
) or an object with a declared sorting options:initialConfig
- Object with predefined keys:column
- sorted columnsortOrder
- order in which column will be sorted'asc'
= ascending'desc'
= descending
indicator
- display status for sorting order indicator (an arrow icon in the column header, specifying the sorting order).true
= show sort indicator for sorted columnsfalse
= don't show sort indicator for sorted columns
headerAction
- allow to click on the headers to sorttrue
= turn on possibility to click on the headers to sortfalse
= turn off possibility to click on the headers to sort
sortEmptyCells
- how empty values should be handledtrue
= the table sorts empty cellsfalse
= the table moves all empty cells to the end of the table
compareFunctionFactory
- curry function returning compare function; compare function should work in the same way as function which is handled by nativeArray.sort
method); please take a look at below examples for more information.
- Default Value: undefined
Example
// as boolean columnSorting: true // as an object with initial sort config (sort ascending for column at index 1) columnSorting: { initialConfig: { column: 1, sortOrder: 'asc' } } // as an object which define specific sorting options for all columns columnSorting: { sortEmptyCells: true, // true = the table sorts empty cells, false = the table moves all empty cells to the end of the table indicator: true, // true = shows indicator for all columns, false = don't show indicator for columns headerAction: false, // true = allow to click on the headers to sort, false = turn off possibility to click on the headers to sort compareFunctionFactory: function(sortOrder, columnMeta) { return function(value, nextValue) { // Some value comparisons which will return -1, 0 or 1... } } }```
-
columnSummaryArray.<object> function
-
Allows making pre-defined calculations on the cell values and display the results within Handsontable.
Possible types:
'sum'
'min'
'max'
'count'
'average'
'custom'
- addcustomFunction
.
- Default Value: undefined
Example
columnSummary: [ { destinationRow: 4, destinationColumn: 1, forceNumeric: true, reversedRowCoords: true, suppressDataTypeErrors: false, readOnly: true, roundFloat: false, type: 'custom', customFunction: function(endpoint) { return 100; } } ],
-
colWidthsnumber Array.<number> string Array.<string> function
-
Defines column widths in pixels. Accepts number, string (that will be converted to a number), array of numbers
(if you want to define column width separately for each column) or a function (if you want to set column width
dynamically on each render).- Default Value: undefined
Example
// as a number, for each column. colWidths: 100, // as a string, for each column. colWidths: '100px', // as an array, based on visual indexes. The rest of the columns have a default width. colWidths: [100, 120, 90], // as a function, based on visual indexes. colWidths: function(index) { return index * 10; },
-
commentedCellClassNamestring
-
CSS class name added to the commented cells.
- Default Value: 'htCommentCell'
Example
// set custom class for commented cells commentedCellClassName: 'has-comment',
-
commentsboolean Array.<object>
-
If
true
, enables theComments
plugin, which enables an option to apply cell comments through the context menu
(configurable with context menu keyscommentsAddEdit
,commentsRemove
).To initialize Handsontable with predefined comments, provide cell coordinates and comment text values in a form of
an array.See Comments demo for examples.
- Default Value: false
Example
// enable comments plugin comments: true, // or an object with extra predefined plugin config: comments: { displayDelay: 1000 } // or // enable comments plugin and add predefined comments const hot = new Handsontable(document.getElementById('example'), { data: getData(), comments: true, cell: [ { row: 1, col: 1, comment: { value: 'Foo' } }, { row: 2, col: 2, comment: { value: 'Bar' } } ] });
-
contextMenuboolean Array.<string> object
-
Defines if the right-click context menu should be enabled. Context menu allows to create new row or column at any
place in the grid among other features.
Possible values:true
(to enable default options),false
(to disable completely)- an array of predefined options,
- an object with defined structure.
If the value is an object, you can also customize the options with:
disableSelection
- aboolean
, if set to true it prevents mouseover from highlighting the item for selectionisCommand
- aboolean
, if set to false it prevents clicks from executing the command and closing the menu.
See the context menu demo for examples.
- Default Value: undefined
Example
// as a boolean contextMenu: true, // as an array contextMenu: ['row_above', 'row_below', '---------', 'undo', 'redo'], // as an object (`name` attribute is required in the custom keys) contextMenu: { items: { "option1": { name: "option1" }, "option2": { name: "option2", submenu: { items: [ { key: "option2:suboption1", name: "option2:suboption1", callback: function(key, options) { ... } }, ... ] } } } },
-
copyableboolean
-
Makes a cell copyable (pressing CTRL + C on your keyboard moves its value to system clipboard).
Note: this setting is
false
by default for cells with typepassword
.- Default Value: true
Example
cells: [ { cell: 0, row: 0, // cell with coordinates (0, 0) can't be copied copyable: false, } ],
-
copyPasteobject boolean
-
Disables or enables the copy/paste functionality.
- Default Value: true
Example
// disable copy and paste copyPaste: false, // enable copy and paste with custom configuration copyPaste: { columnsLimit: 25, rowsLimit: 50, pasteMode: 'shift_down', uiContainer: document.body, },
-
correctFormatboolean
-
If
true
then dates will be automatically formatted to match the desired format.Note, this option only works for date-typed cells.
- Default Value: false
Example
columns: [{ type: 'date', dateFormat: 'YYYY-MM-DD', // force selected date format correctFormat: true }],
-
currentColClassNamestring
-
Class name for all visible columns in the current selection.
- Default Value: undefined
Example
// This will add a 'currentColumn' class name to appropriate table cells. currentColClassName: 'currentColumn',
-
currentHeaderClassNamestring
-
Class name for all visible headers in current selection.
- Default Value: 'ht__highlight'
Example
// This will add a 'ht__highlight' class name to appropriate table headers. currentHeaderClassName: 'ht__highlight',
-
currentRowClassNamestring
-
Class name for all visible rows in the current selection.
- Default Value: undefined
Example
// This will add a 'currentRow' class name to appropriate table cells. currentRowClassName: 'currentRow',
-
customBordersboolean Array.<object>
-
If
true
, enables theCustomBorders
plugin, which enables an option to apply custom borders through the context
menu (configurable with context menu keyborders
). To initialize Handsontable with predefined custom borders,
provide cell coordinates and border styles in a form of an array.See Custom Borders demo for examples.
- Default Value: false
Example
// enable custom borders customBorders: true, // or // enable custom borders and start with predefined left border customBorders: [ { range: { from: { row: 1, col: 1 }, to: { row: 3, col: 4 } }, left: { width: 2, color: 'red' }, right: {}, top: {}, bottom: {} } ], // or customBorders: [ { row: 2, col: 2, left: { width: 2, color: 'red' }, right: { width: 1, color: 'green' }, top: '', bottom: '' } ],
-
dataArray.<Array> Array.<object>
-
Initial data source that will be bound to the data grid by reference (editing data grid alters the data source).
Can be declared as an array of arrays or an array of objects.- Default Value: undefined
Example
// as an array of arrays data: [ ['A', 'B', 'C'], ['D', 'E', 'F'], ['G', 'H', 'J'] ] // as an array of objects data: [ {id: 1, name: 'Ted Right'}, {id: 2, name: 'Frank Honest'}, {id: 3, name: 'Joan Well'}, {id: 4, name: 'Gail Polite'}, {id: 5, name: 'Michael Fair'}, ]
-
dataSchemaobject
-
Defines the structure of a new row when data source is an array of objects.
See data-schema for more options.
- Default Value: undefined
Example
// with data schema we can start with an empty table data: null, dataSchema: {id: null, name: {first: null, last: null}, address: null}, colHeaders: ['ID', 'First Name', 'Last Name', 'Address'], columns: [ {data: 'id'}, {data: 'name.first'}, {data: 'name.last'}, {data: 'address'} ], startRows: 5, minSpareRows: 1
-
dateFormatstring
-
Date validation format.
Note, this option only works for date-typed cells.
- Default Value: 'DD/MM/YYYY'
Example
columns: [{ type: 'date', // localise date format dateFormat: 'MM/DD/YYYY' }],
-
defaultDatestring
-
Definition of default value which will fill the empty cells.
Note, this option only works for date-typed cells.
- Default Value: undefined
Example
columns: [ { type: 'date', // always set this date for empty cells defaultDate: '2015-02-02' } ],
-
disableVisualSelectionboolean string Array.<string>
-
Disables visual cells selection.
Possible values:
true
- Disables any type of visual selection (current and area selection),false
- Enables any type of visual selection. This is default value.'current'
- Disables the selection of a currently selected cell, the area selection is still present.'area'
- Disables the area selection, the currently selected cell selection is still present.'header'
- Disables the headers selection, the currently selected cell selection is still present.
- Default Value: false
Example
// as a boolean disableVisualSelection: true, // as a string ('current', 'area' or 'header') disableVisualSelection: 'current', // as an array disableVisualSelection: ['current', 'area'],
-
dragToScrollboolean
-
Disables or enables the drag to scroll functionality.
- Default Value: true
Example
// don't scroll the viewport when selection gets to the viewport edge dragToScroll: false,
-
dropdownMenuboolean object Array.<string>
-
This plugin allows adding a configurable dropdown menu to the table's column headers. The dropdown menu acts like
theOptions#contextMenu
, but is triggered by clicking the button in the header.- Default Value: undefined
Example
// enable dropdown menu dropdownMenu: true, // or // enable and configure dropdown menu options dropdownMenu: ['remove_col', '---------', 'make_read_only', 'alignment']
-
editorstring function boolean
-
Defines the editor for the table/column/cell.
If a string is provided, it may be one of the following predefined values:
Or you can register the custom editor under specified name and use its name as an alias in your
configuration.To disable cell editing completely set
editor
property tofalse
.- Default Value: undefined
Example
columns: [ { // set editor for the first column editor: 'select' }, { // disable editor for the second column editor: false } ],
-
enterBeginsEditingboolean
-
If
true
, ENTER begins editing mode (like in Google Docs). Iffalse
, ENTER moves to next
row (like Excel) and adds a new row if necessary. TAB adds new column if necessary.- Default Value: true
Example
enterBeginsEditing: false,
-
enterMovesobject function
-
Defines the cursor movement after ENTER was pressed (SHIFT + ENTER uses a negative vector). Can
be an object or a function that returns an object. The event argument passed to the function is a DOM Event object
received after the ENTER key has been pressed. This event object can be used to check whether user pressed
ENTER or SHIFT + ENTER.- Default Value: {col: 0, row: 1}
Example
// move selection diagonal by 1 cell in x and y axis enterMoves: {col: 1, row: 1}, // or as a function enterMoves: function(event) { return {col: 1, row: 1}; },
-
fillHandleboolean string object
-
Enables the fill handle (drag-down and copy-down) functionality, which shows a small rectangle in bottom
right corner of the selected area, that let's you expand values to the adjacent cells.Setting to
true
enables the fillHandle plugin. Possible values:true
(to enable in all directions),
'vertical'
or'horizontal'
(to enable in one direction),false
(to disable completely), an object with
options:autoInsertRow
,direction
.If
autoInsertRow
option istrue
, fill-handler will create new rows till it reaches the last row.
It is enabled by default.- Default Value: true
Example
// enable plugin in all directions and with autoInsertRow as true fillHandle: true, // or // enable plugin in vertical direction and with autoInsertRow as true fillHandle: 'vertical', // or fillHandle: { // enable plugin in both directions and with autoInsertRow as false autoInsertRow: false, }, // or fillHandle: { // enable plugin in vertical direction and with autoInsertRow as false autoInsertRow: false, direction: 'vertical' },
-
filterboolean
-
If defined as
true
, when the user types into the input area the Autocomplete's suggestion list is updated to only
include those choices starting with what has been typed; if defined asfalse
all suggestions remain shown, with
those matching what has been typed marked in bold.Note, this option only works for autocomplete-typed cells.
- Default Value: true
Example
columns: [ { type: 'autocomplete', source: [ ... ], // don't hide options that don't match search query filter: false } ],
-
filteringCaseSensitiveboolean
-
If defined as
true
, filtering in the Autocomplete Editor will be case-sensitive.Note, this option only works for autocomplete-typed cells.
- Default Value: false
Example
columns: [ { type: 'autocomplete', source: [ ... ], // match case while searching autocomplete options filteringCaseSensitive: true } ],
-
filtersboolean
-
The
Filters
plugin allows filtering the table data either by the built-in component or with the API.- Default Value: undefined
Example
// enable filters filters: true,
-
fixedColumnsLeftnumber
-
Allows to specify the number of fixed (or frozen) columns on the left of the table.
- Default Value: 0
Example
// freeze first 3 columns of the table. fixedColumnsLeft: 3,
-
fixedRowsBottomnumber
-
Allows to specify the number of fixed (or frozen) rows at the bottom of the table.
- Default Value: 0
Example
// freeze the last 3 rows of the table. fixedRowsBottom: 3,
-
fixedRowsTopnumber
-
Allows to specify the number of fixed (or frozen) rows at the top of the table.
- Default Value: 0
Example
// freeze the first 3 rows of the table. fixedRowsTop: 3,
-
formulasboolean object
-
The
Formulas
plugin allows Handsontable to process formula expressions defined in the provided data.- Default Value: undefined
Example
// enable formulas plugin formulas: true, // or as an object with custom variables to be used in formula expressions formulas: { variables: { FOO: 64, BAR: 'baz', } },
-
fragmentSelectionboolean string
-
If set to
true
, it enables the browser's native selection of a fragment of the text within a single cell, between
adjacent cells or in a whole table. If set to'cell'
, it enables the possibility of selecting a fragment of the
text within a single cell's body.- Default Value: false
Example
// enable text selection within table fragmentSelection: true, // or // enable text selection within cells only fragmentSelection: 'cell',
-
headerTooltipsboolean object
-
Allows adding a tooltip to the table headers.
Available options:
- the
rows
property defines if tooltips should be added to row headers, - the
columns
property defines if tooltips should be added to column headers, - the
onlyTrimmed
property defines if tooltips should be added only to headers, which content is trimmed by the header itself (the content being wider then the header).
- Deprecated
This plugin is deprecated and will be removed in the next major release. - the
- Default Value: undefined
Example
// enable tooltips for all headers
headerTooltips: true,
// or
headerTooltips: {
rows: false,
columns: true,
onlyTrimmed: true
}
heightnumber string function
Height of the grid. Can be a number or a function that returns a number.
- Default Value: undefined
Example
// as a number
height: 500,
// as a string
height: '75vh',
// as a function
height: function() {
return 500;
},
hiddenColumnsboolean object
The HiddenColumns
plugin allows hiding of certain columns. You can pass additional configuration with an
object notation. Options that are then available are:
columns
- an array of rows that should be hidden on plugin initializationindicators
- enables small ui markers to indicate where are hidden columns.
- Default Value: undefined
Example
// enable column hiding
hiddenColumns: true,
// or
hiddenColumns: {
// set columns that are hidden by default
columns: [5, 10, 15],
// show where are hidden columns
indicators: true
}
hiddenRowsboolean object
The HiddenRows
plugin allows hiding of certain rows. You can pass additional configuration with an
object notation. Options that are then available are:
rows
- an array of rows that should be hidden on plugin initializationindicators
- enables small ui markers to indicate where are hidden columns.
- Default Value: undefined
Example
// enable row hiding
hiddenRows: true,
// or
hiddenRows: {
// set rows that are hidden by default
rows: [5, 10, 15],
// show where are hidden rows
indicators: true
}
invalidCellClassNamestring
CSS class name for cells that did not pass validation.
- Default Value: 'htInvalid'
Example
// set custom validation error class
invalidCellClassName: 'highlight--error',
labelobject
Object which describes if renderer should create checkbox element with label element as a parent.
Note, this option only works for checkbox-typed cells.
By default the checkbox renderer renders the checkbox without a label.
Possible object properties:
property
- Defines the property name of the data object, which will to be used as a label.
(eg.label: {property: 'name.last'}
). This option works only if data was passed as an array of objects.position
- String which describes where to place the label text (before or after checkbox element).
Valid values are'before'
and 'after
' (defaults to'after'
).value
- String or a Function which will be used as label text.
- Default Value: undefined
Example
columns: [{
type: 'checkbox',
// add "My label:" after the checkbox
label: {position: 'after', value: 'My label: '}
}],
languagestring
Language for Handsontable translation. Possible language codes are listed here.
- Default Value: 'en-US'
Example
// set Polish language
language: 'pl-PL',
licenseKeystring
License key for commercial version of Handsontable.
- Default Value: undefined
Example
licenseKey: '00000-00000-00000-00000-00000',
// or
licenseKey: 'non-commercial-and-evaluation',
manualColumnFreezeboolean
Disables or enables ManualColumnFreeze
plugin.
- Default Value: undefined
Example
// enable fixed columns
manualColumnFreeze: true,
manualColumnMoveboolean Array.<number>
Turns on Manual column move, if set to a boolean or define initial column order (as an array of column indexes).
- Default Value: undefined
Example
// as a boolean to enable column move
manualColumnMove: true,
// as a array with initial order
// (move column index at 0 to 1 and move column index at 1 to 4)
manualColumnMove: [1, 4],
manualColumnResizeboolean Array.<number>
Turns on Manual column resize, if set to a boolean or define initial column resized widths (an an array of widths).
- Default Value: undefined
Example
// as a boolean to enable column resize
manualColumnResize: true,
// as a array with initial widths
// (column at 0 index has 40px and column at 1 index has 50px)
manualColumnResize: [40, 50],
manualRowMoveboolean Array.<number>
Turns on Manual row move, if set to a boolean or define initial row order (as an array of row indexes).
- Default Value: undefined
Example
// as a boolean
manualRowMove: true,
// as a array with initial order
// (move row index at 0 to 1 and move row index at 1 to 4)
manualRowMove: [1, 4],
manualRowResizeboolean Array.<number>
Turns on Manual row resize, if set to a boolean or define initial row resized heights (as an array of heights).
- Default Value: undefined
Example
// as a boolean to enable row resize
manualRowResize: true,
// as an array to set initial heights
// (row at 0 index has 40px and row at 1 index has 50px)
manualRowResize: [40, 50],
maxColsnumber
Maximum number of cols. If set to a value lower than the initial col count, the data will be trimmed to the provided
value as the number of cols.
- Default Value: Infinity
Example
// limit table size to maximum 300 columns
maxCols: 300,
maxRowsnumber
Maximum number of rows. If set to a value lower than the initial row count, the data will be trimmed to the provided
value as the number of rows.
- Default Value: Infinity
Example
// limit table size to maximum 300 rows
maxRows: 300,
mergeCellsboolean Array.<object>
If set to true
, it enables a possibility to merge cells. If set to an array of objects, it merges the cells provided
in the objects (see the example below). More information on the demo page.
- Default Value: false
Example
// enables the mergeCells plugin
margeCells: true,
// declares a list of merged sections
mergeCells: [
// rowspan and colspan properties declare the width and height of a merged section in cells
{row: 1, col: 1, rowspan: 3, colspan: 3},
{row: 3, col: 4, rowspan: 2, colspan: 2},
{row: 5, col: 6, rowspan: 3, colspan: 3}
],
minColsnumber
Minimum number of columns. At least that number of columns will be created during initialization.
Works only with an array data source. When data source in an object, you can only have as many columns
as defined in the first data row, data schema, or the columns
setting.
- Default Value: 0
Example
// set minimum table size to 10 columns
minCols: 10,
minRowsnumber
Minimum number of rows. At least that number of rows will be created during initialization.
- Default Value: 0
Example
// set minimum table size to 10 rows
minRows: 10,
minSpareColsnumber
When set to 1 (or more), Handsontable will add a new column at the end of grid if there are no more empty columns.
(unless the number of rows exceeds the one set in the maxCols
property).
- Default Value: 0
Example
// always add 3 empty columns at the table end
minSpareCols: 3,
minSpareRowsnumber
When set to 1 (or more), Handsontable will add a new row at the end of grid if there are no more empty rows.
(unless the number of rows exceeds the one set in the maxRows
property).
- Default Value: 0
Example
// always add 3 empty rows at the table end
minSpareRows: 3,
multiColumnSortingboolean object
Turns on Multi-column sorting. Can be either a boolean (true
/ false
) or an object with a declared sorting options:
initialConfig
- Array containing objects, every with predefined keys:column
- sorted columnsortOrder
- order in which column will be sorted'asc'
= ascending'desc'
= descending
indicator
- display status for sorting order indicator (an arrow icon in the column header, specifying the sorting order).true
= show sort indicator for sorted columnsfalse
= don't show sort indicator for sorted columns
headerAction
- allow to click on the headers to sorttrue
= turn on possibility to click on the headers to sortfalse
= turn off possibility to click on the headers to sort
sortEmptyCells
- how empty values should be handledtrue
= the table sorts empty cellsfalse
= the table moves all empty cells to the end of the table
compareFunctionFactory
- curry function returning compare function; compare function should work in the same way as function which is handled by nativeArray.sort
method); please take a look at below examples for more information.
- Default Value: undefined
Example
// as boolean
multiColumnSorting: true
// as an object with initial sort config (sort ascending for column at index 1 and then sort descending for column at index 0)
multiColumnSorting: {
initialConfig: [{
column: 1,
sortOrder: 'asc'
}, {
column: 0,
sortOrder: 'desc'
}]
}
// as an object which define specific sorting options for all columns
multiColumnSorting: {
sortEmptyCells: true, // true = the table sorts empty cells, false = the table moves all empty cells to the end of the table
indicator: true, // true = shows indicator for all columns, false = don't show indicator for columns
headerAction: false, // true = allow to click on the headers to sort, false = turn off possibility to click on the headers to sort
compareFunctionFactory: function(sortOrder, columnMeta) {
return function(value, nextValue) {
// Some value comparisons which will return -1, 0 or 1...
}
}
}```
nestedHeadersArray.<Array>
Allows creating a nested header structure, using the HTML's colspan attribute.
- Default Value: undefined
Example
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']
],
nestedRowsboolean
Disable or enable the nested rows functionality - displaying nested structures in a two-dimensional data table.
- Default Value: false
Example
nestedRows: true,
noWordWrapClassNamestring
CSS class name added to cells with cell meta wordWrap: false
.
- Default Value: 'htNoWrap'
Example
// set custom class for cells which content won't be wrapped
noWordWrapClassName: 'is-noWrapCell',
numericFormatobject
Display format for numeric typed renderers.
Note, this option only works for numeric-typed cells.
Format is described by two properties:
pattern
- Handled bynumbro
for purpose of formatting numbers to desired pattern. List of supported patterns can be found here.culture
- Handled bynumbro
for purpose of formatting currencies. Examples showing how it works can be found here. List of supported cultures can be found here.
Note: Please keep in mind that this option is used only to format the displayed output! It has no effect on the input data provided for the cell. The numeric data can be entered to the table only as floats (separated by a dot or a comma) or integers, and are stored in the source dataset as JavaScript numbers.
Handsontable uses numbro as a main library for numbers formatting.
- Since: 0.35.0
- Default Value: undefined
Example
columns: [
{
type: 'numeric',
// set desired format pattern and
numericFormat: {
pattern: '0,00',
culture: 'en-US'
}
}
],
observeChangesboolean
Enables the ObserveChanges
plugin switches table into one-way data binding where changes are applied into
data source (from outside table) will be automatically reflected in the table.
For every data change afterChangesObserved hook will be fired.
- Deprecated
Example
observeChanges: true,
observeDOMVisibilityboolean
When set to true
, the table is re-rendered when it is detected that it was made visible in DOM.
- Default Value: true
Example
// don't rerender the table on visibility changes
observeDOMVisibility: false,
outsideClickDeselectsboolean function
If true
, mouse click outside the grid will deselect the current selection. Can be a function that takes the
click event target and returns a boolean.
- Default Value: true
Example
// don't clear current selection when mouse click was outside the grid
outsideClickDeselects: false,
// or
outsideClickDeselects: function(event) {
return false;
}
persistentStateboolean
Turns on saving the state of column sorting, column positions and column sizes in local storage.
You can save any sort of data in local storage to preserve table state between page reloads. In order to enable
data storage mechanism, persistentState
option must be set to true
(you can set it either during Handsontable
initialization or using the updateSettings
method). When persistentState
is enabled it exposes 3 hooks:
persistentStateSave (key: String, value: Mixed).
- Saves value under given key in browser local storage.
persistentStateLoad (key: String, valuePlaceholder: Object).
- Loads
value
, saved under given key, form browser local storage. The loadedvalue
will be saved in
valuePlaceholder.value
(this is due to specific behaviour ofHooks.run()
method). If no value have
been saved under keyvaluePlaceholder.value
will beundefined
.
persistentStateReset (key: String).
- Clears the value saved under
key
. If nokey
is given, all values associated with table will be cleared.
Note: The main reason behind using persistentState
hooks rather than regular LocalStorage API is that it
ensures separation of data stored by multiple Handsontable instances. In other words, if you have two (or more)
instances of Handsontable on one page, data saved by one instance won't be accessible by the second instance.
Those two instances can store data under the same key and no data would be overwritten.
Important: In order for the data separation to work properly, make sure that each instance of Handsontable has a unique id
.
- Default Value: false
Example
// enable the persistent state plugin
persistentState: true,
placeholderstring
When set to an non-empty string, displayed as the cell content for empty cells. If a value of a different type is provided,
it will be stringified and applied as a string.
- Default Value: undefined
Example
// add custom placeholder content to empty cells
placeholder: 'Empty Cell',
placeholderCellClassNamestring
CSS class name for cells that have a placeholder in use.
- Default Value: 'htPlaceholder'
Example
// set custom placeholder class
placeholderCellClassName: 'has-placeholder',
preventOverflowstring boolean
Prevents table to overlap outside the parent element. If 'horizontal'
option is chosen then table will show
a horizontal scrollbar if parent's width is narrower then table's width.
Possible values:
false
- Disables functionality.horizontal
- Prevents horizontal overflow table.vertical
- Prevents vertical overflow table.
- Default Value: false
Example
preventOverflow: 'horizontal',
readOnlyboolean
Makes cell, column or comment read only.
- Default Value: false
Example
// set as read only
readOnly: true,
readOnlyCellClassNamestring
CSS class name for read-only cells.
- Default Value: 'htDimmed'
Example
// set custom read-only class
readOnlyCellClassName: 'is-readOnly',
renderAllRowsboolean
If typed true
then virtual rendering mechanism for handsontable will be disabled.
- Default Value: undefined
Example
// disable virtual rows rendering
renderAllRows: true,
rendererstring function
If a string is provided, it may be one of the following predefined values:
autocomplete
,checkbox
,html
,numeric
,password
.text
.
Or you can register the custom renderer under specified name and use its name as an alias in your
configuration.
If a function is provided, it will receive the following arguments:
function(instance, TD, row, col, prop, value, cellProperties) {}
You can read more about custom renderes in the documentation.
- Default Value: undefined
Example
// register custom renderer
Handsontable.renderers.registerRenderer('my.renderer', function(instance, TD, row, col, prop, value, cellProperties) {
TD.innerHTML = value;
});
// use it for selected column:
columns: [
{
// as a string with the name of build in renderer
renderer: 'autocomplete',
editor: 'select'
},
{
// as an alias to custom renderer registered above
renderer: 'my.renderer'
},
{
// renderer as custom function
renderer: function(hotInstance, TD, row, col, prop, value, cellProperties) {
TD.style.color = 'blue';
TD.innerHTML = value;
}
}
],
rowHeadersboolean Array.<string> function
Setting true
or false
will enable or disable the default row headers (1, 2, 3).
You can also define an array ['One', 'Two', 'Three', ...]
or a function to define the headers.
If a function is set the index of the row is passed as a parameter.
- Default Value: undefined
Example
// as a boolean
rowHeaders: true,
// as an array
rowHeaders: ['1', '2', '3'],
// as a function
rowHeaders: function(index) {
return index + ': AB';
},
rowHeaderWidthnumber Array.<number>
Allows setting a custom width of the row headers. You can provide a number or an array of widths, if many row
header levels are defined.
- Default Value: undefined
Example
// set width for all row headers
rowHeaderWidth: 25,
// or
// set width for selected headers only
rowHeaderWidth: [25, 30, 55],
rowHeightsnumber Array.<number> string Array.<string> function
Defines row heights in pixels. Accepts numbers, strings (that will be converted into a number), array of numbers
(if you want to define row height separately for each row) or a function (if you want to set row height dynamically
on each render).
If the ManualRowResize
or AutoRowSize
plugins are enabled, this is also the minimum height that can
be set via either of those two plugins.
Height should be equal or greater than 23px. Table is rendered incorrectly if height is less than 23px.
- Default Value: undefined
Example
// as a number, the same for all rows
rowHeights: 100,
// as a string, the same for all row
rowHeights: '100px',
// as an array, based on visual indexes. The rest of the rows have a default height
rowHeights: [100, 120, 90],
// as a function, based on visual indexes
rowHeights: function(index) {
return index * 10;
},
searchboolean
- Default Value: false
Example
// enable search plugin
search: true,
// or
// as an object with detailed configuration
search: {
searchResultClass: 'customClass',
queryMethod: function(queryStr, value) {
...
},
callback: function(instance, row, column, value, result) {
...
}
}
selectionModestring
Defines how the table selection reacts. The selection support three different behaviors defined as:
'single'
Only a single cell can be selected.'range'
Multiple cells within a single range can be selected.'multiple'
Multiple ranges of cells can be selected.
To see how to interact with selection by getting selected data or change styles of the selected cells go to
https://docs.handsontable.com/demo-selecting-ranges.html.
- Default Value: 'multiple'
Example
// only one cell can be selected at a time
selectionMode: 'single',
selectOptionsArray.<string>
Data source for select-typed cells.
Note, this option only works for select-typed cells.
- Default Value: undefined
Example
columns: [
{
editor: 'select',
// add three select options to choose from
selectOptions: ['A', 'B', 'C'],
}
],
skipColumnOnPasteboolean
When added to a column
property, it skips the column on paste and pastes the data on the next column to the right.
- Default Value: false
Example
columns: [
{
// don't paste data to this column
skipColumnOnPaste: true
}
],
skipRowOnPasteboolean
When added to a cell property, it skips the row on paste and pastes the data on the following row.
- Default Value: false
Example
cells: function(row, column) {
const cellProperties = {};
// don't paste data to the second row
if (row === 1) {
cellProperties.skipRowOnPaste = true;
}
return cellProperties;
}
sortByRelevanceboolean
If defined as true
, the Autocomplete's suggestion list would be sorted by relevance (the closer to the left the
match is, the higher the suggestion).
Note, this option only works for autocomplete-typed cells.
- Default Value: true
Example
columns: [
{
type: 'autocomplete',
source: [ ... ],
// keep options order as they were defined
sortByRelevance: false
}
],
sourceArray function
Defines data source for Autocomplete or Dropdown cell types.
- Default Value: undefined
Example
// source as a array
columns: [{
type: 'autocomplete',
source: ['A', 'B', 'C', 'D']
}],
// source as a function
columns: [{
type: 'autocomplete',
source: function(query, callback) {
fetch('https://example.com/query?q=' + query, function(response) {
callback(response.items);
})
}
}],
startColsnumber
Initial number of columns.
Note: This option only has effect in Handsontable constructor and only if data
option is not provided.
- Default Value: 5
Example
// start with 15 empty columns
startCols: 15,
startRowsnumber
Initial number of rows.
Note: This option only has effect in Handsontable constructor and only if data
option is not provided.
- Default Value: 5
Example
// start with 15 empty rows
startRows: 15,
stretchHstring
Defines how the columns react, when the declared table width is different than the calculated sum of all column widths.
See more mode. Possible values:
'none'
Disable stretching'last'
Stretch only the last column'all'
Stretch all the columns evenly.
- Default Value: 'none'
Example
// fit table to the container
stretchH: 'all',
strictboolean
If set to true
, the value entered into the cell must match (case-sensitive) the autocomplete source.
Otherwise, cell won't pass the validation. When filtering the autocomplete source list, the editor will
be working in case-insensitive mode.
Note, this option only works for autocomplete-typed cells.
- Default Value: undefined
Example
columns: [{
type: 'autocomplete',
source: ['A', 'B', 'C'],
// force selected value to match the source list
strict: true
}],
tableClassNamestring Array.<string>
Class name for all tables inside container element.
- Default Value: undefined
Example
// set custom class for table element
tableClassName: 'your__class--name',
// or
tableClassName: ['first-class-name', 'second-class-name'],
tabMovesobject function
Defines the cursor movement after TAB is pressed (SHIFT + TAB uses a negative vector). Can
be an object or a function that returns an object. The event argument passed to the function is a DOM Event object
received after the TAB key has been pressed. This event object can be used to check whether user pressed
TAB or SHIFT + TAB.
- Default Value: {row: 0, col: 1}
Example
// move selection 2 cells away after TAB pressed.
tabMoves: {row: 2, col: 2},
// or as a function
tabMoves: function(event) {
return {row: 2, col: 2};
},
titlestring
Defines the column header name.
- Default Value: undefined
Example
// set header names for every column
columns: [
{
title: 'First name',
type: 'text',
},
{
title: 'Last name',
type: 'text',
}
],
trimDropdownboolean
Makes autocomplete or dropdown width the same as the edited cell width. If false
then editor will be scaled
according to its content.
- Default Value: true
Example
columns: [
{
type: 'autocomplete',
// don't trim dropdown width with column width
trimDropdown: false,
}
],
trimRowsboolean Array.<number>
Plugin allowing hiding of certain rows.
- Default Value: undefined
Example
// enable plugin
trimRows: true,
// or
// trim selected rows on table initialization
trimRows: [5, 10, 15],
trimWhitespaceboolean
Defines whether Handsontable should trim the whitespace at the beginning and the end of the cell contents.
- Default Value: true
Example
columns: [
{
// don't remove whitespace
trimWhitespace: false
}
]
typestring
Shortcut to define the combination of the cell renderer, editor and validator for the column, cell or whole table.
Possible values:
Or you can register the custom cell type under specified name and use
its name as an alias in your configuration.
- Default Value: 'text'
Example
// register custom cell type:
Handsontable.cellTypes.registerCellType('my.type', {
editor: MyEditorClass,
renderer: function(hot, td, row, col, prop, value, cellProperties) {
td.innerHTML = value;
},
validator: function(value, callback) {
callback(value === 'foo' ? true : false);
}
});
// use it in column settings:
columns: [
{
type: 'text'
},
{
// an alias to custom type
type: 'my.type'
},
{
type: 'checkbox'
}
],
uncheckedTemplateboolean string number
Data template for 'checkbox'
type when checkbox is unchecked.
- Default Value: false
Example
uncheckedTemplate: 'bad'
// if a checkbox-typed cell is not checked, then getDataAtCell(x,y),
// where x and y are the coordinates of the cell will return 'bad'.
undoboolean
If true
, undo/redo functionality is enabled.
Note: undefined
by default but it acts as enabled.
You need to switch it to false
to disable it completely.
- Default Value: undefined
Example
// enable undo and redo
undo: true,
validatorfunction RegExp string
A function, regular expression or a string, which will be used in the process of cell validation. If a function is
used, be sure to execute the callback argument with either true
(callback(true)
) if the validation passed
or with false
(callback(false)
), if the validation failed.
Note, that this
in the function points to the cellProperties
object.
If a string is provided, it may be one of the following predefined values:
autocomplete
,date
,numeric
,time
.
Or you can register the validator function under specified name and use its name as an alias in your
configuration.
See more in the demo.
- Default Value: undefined
Example
columns: [
{
// as a function
validator: function(value, callback) {
...
}
},
{
// regular expression
validator: /^[0-9]$/
},
{
// as a string
validator: 'numeric'
}
],
viewportColumnRenderingOffsetnumber string
Number of columns to be rendered outside of the visible part of the table. By default, it's set to 'auto'
, which
makes Handsontable try calculating the best offset performance-wise.
You may experiment with the value to find the one that works best for your specific implementation.
- Default Value: 'auto'
Example
viewportColumnRenderingOffset: 70,
viewportRowRenderingOffsetnumber string
Number of rows to be rendered outside of the visible part of the table. By default, it's set to 'auto'
, which
makes Handsontable to attempt to calculate the best offset performance-wise.
You may test out different values to find the best one that works for your specific implementation.
- Default Value: 'auto'
Example
viewportRowRenderingOffset: 70,
visibleRowsnumber
Control number of choices for the autocomplete (or dropdown) typed cells. After exceeding it, a scrollbar for the
dropdown list of choices will appear.
- Default Value: 10
Example
columns: [
{
type: 'autocomplete',
// set autocomplete options list height
visibleRows: 15,
}
],
widthnumber string function
Width of the grid. Can be a value or a function that returns a value.
- Default Value: undefined
Example
// as a number
width: 500,
// as a string
width: '75vw',
// as a function
width: function() {
return 500;
},
wordWrapboolean
When set to true
, the text of the cell content is wrapped if it does not fit in the fixed column width.
- Default Value: true
Example
colWidths: 100,
columns: [
{
// fixed column width is set but don't wrap the content
wordWrap: false,
}
],
Methods
-
isEmptyCol(col){boolean}
-
Overwrites the default
isEmptyCol
method, which checks if column at the provided index is empty.Parameters:
Name Type Description col
number Visual column index.
Returns: {boolean}
Example
// define custom checks for empty column isEmptyCol: function(column) { return false; },
-
isEmptyRow(row){boolean}
-
Overwrites the default
isEmptyRow
method, which checks if row at the provided index is empty.Parameters:
Name Type Description row
number Visual row index.
Returns: {boolean}
Example
// define custom checks for empty row isEmptyRow: function(row) { ... },