Class: Options

Options

handsontable/src/core.js, line 3362

Constructor options

Constructor options are applied using an object literal passed as a second argument to the Handsontable constructor.

var hot = new Handsontable(document.getElementById('example1'), {
  data: myArray,
  width: 400,
  height: 300
});

Cascading configuration

Handsontable 0.9 and newer 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:

var hot = new Handsontable(document.getElementById('example'), {
  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 second-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

allowEmptyBoolean

If set to true, Handsontable will accept values that are empty (null, undefined or '').
If set to false, Handsontable will not accept the empty values and mark cell as invalid.

Since:
  • 0.23.0
Default Value:
  • true
Example
...
allowEmpty: true // allow empty values for all cells (whole table)
...
// or
...
columns: [
  // allow empty values only for 'date' column
  {data: 'date', dateFormat: 'DD/MM/YYYY', allowEmpty: true}
]
...

allowHtmlBoolean

If typed true, data defined in source of the autocomplete or dropdown cell will be treated as HTML.

Warning: Enabling this option can cause serious XSS vulnerabilities.

Option desired for 'autocomplete'-typed cells.

Default Value:
  • false
Example
...
columns: [{
  type: 'autocomplete',
  allowHtml: true,
  source: ['<b>foo</b>', '<b>bar</b>']
}]
...

allowInsertColumnBoolean

If set to false, there won't be an option to insert new columns in the Context Menu.

Default Value:
  • true

allowInsertRowBoolean

If set to false, there won't be an option to insert new rows in the Context Menu.

Default Value:
  • true

allowInvalidBoolean

If set to true, Handsontable will accept values that were marked as invalid by the cell validator.
It will result with invalid cells being treated as valid (will save the invalid value into the Handsontable data source).
If set to false, 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's strict mode.

Since:
  • 0.9.5
Default Value:
  • true

allowRemoveColumnBoolean

If set to false, there won't be an option to remove columns in the Context Menu.

Default Value:
  • true

allowRemoveRowBoolean

If set to false, there won't be an option to remove rows in the Context Menu.

Default Value:
  • true

autoColumnSizeObject Boolean

Enables or disables the autoColumnSize plugin. Default value is undefined, which has the same effect as true.
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 this 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.
syncLimit option is available since 0.16.0.

You can also use the useHeaders option to take the column headers with 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 calculation the column width
autoColumnSize: {useHeaders: true},
...

autoCompleteArray

Autocomplete definitions. See autocomplete demo for examples and definitions.

Default Value:
  • undefined

autoRowSizeObject Boolean

Enables or disables autoRowSize plugin. Default value is undefined, which has the same effect as true.
Disabling this plugin can increase performance, as no size-related calculations would be performed.

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.
syncLimit options is available since 0.16.0.

Default Value:
  • {syncLimit: 1000}
Example
...
// as number (300 columns in sync, rest async)
autoRowSize: {syncLimit: 300},
...

...
// as 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:
  • false

autoWrapRowBoolean

If true, pressing TAB or right arrow in the last column will move to first column in next row.

Default Value:
  • false

bindRowsWithHeadersBoolean String

Plugin allowing 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.

Since:
  • 1.0.0-beta1
Example
...
var hot = new Handsontable(document.getElementById('example'), {
  date: getData(),
  bindRowsWithHeaders: true
});
...

cellArray

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
...
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 the cells property in the Handsontable constructor.

Default Value:
  • undefined
Example
...
cells: function (row, col, prop) {
  var cellProperties = {};

  if (row === 0 && col === 0) {
    cellProperties.readOnly = true;
  }

  return cellProperties;
},
...

checkedTemplateBoolean String

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

Class name for the Handsontable container element.

Default Value:
  • undefined

colHeadersBoolean Array function

Setting true or false 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 boolean
colHeaders: true,
...

...
// as array
colHeaders: ['A', 'B', 'C'],
...

...
// as function
colHeaders: function(index) {
  return index + ': AB';
},
...

collapsibleColumnsBoolean Array

The CollapsibleColumns plugin allows collapsing of columns, covered by a header with the colspan property defined.

Clicking the "collapse/expand" button collapses (or expands) all "child" headers except the first one.

Setting the collapsibleColumns property to true 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.

Since:
  • 1.0.0-beta1
Example
...
 collapsibleColumns: [
   {row: -4, col: 1, collapsible: true},
   {row: -3, col: 5, collapsible: true}
 ]
...
// or
...
 collapsibleColumns: true
...

columnHeaderHeightNumber Array

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.

Since:
  • 0.22.0

columnsArray

Defines the cell properties and data binding for certain columns.

Notice: 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
...
columns: [
  {
    // column options for the first column
    type: 'numeric',
    format: '0,0.00 $'
  },
  {
    // column options for the second column
    type: 'text',
    readOnly: true
  }
],
...

columnSortingBoolean Object

Turns on Column sorting.
Can be either a boolean (true/false) or an object with a declared sorting options. See the below example:

Default Value:
  • undefined
Example
...
// as boolean
columnSorting: true
...
// as a object with initial order (sort ascending column at index 2)
columnSorting: {
  column: 2,
  sortOrder: true, // true = ascending, false = descending, undefined = original order
  sortEmptyCells: true // true = the table sorts empty cells, false = the table moves all empty cells to the end of the table
}
...

columnSummaryObject

Allows making pre-defined calculations on the cell values and display the results within Handsontable.
See the demo for more information.

Since:
  • 1.0.0-beta1

colWidthsArray function Number String

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

commentedCellClassNameString

CSS class name added to the commented cells.

Default Value:
  • 'htCommentCell'

commentsBoolean Array

If true, enables the Comments plugin, which enables an option to apply cell comments through the context menu
(configurable with context menu keys commentsAddEdit, 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.

Since:
  • 0.11.0
Default Value:
  • false
Example
...
comments: [{row: 1, col: 1, comment: {value: "Test comment"}}],
...

contextMenuBoolean Array 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)

or array of any available strings:

  • ["row_above", "row_below", "col_left", "col_right", "remove_row", "remove_col", "---------", "undo", "redo"].

See the context menu demo for examples.

Default Value:
  • undefined
Example
...
// as a boolean
contextMenu: true
...
// as a array
contextMenu: ['row_above', 'row_below', '--------', 'undo', 'redo']
...

contextMenuCopyPasteObject

Defines new actions copy/paste for context menu. This functionality is dependent on ZeroClipboard from which you
should pass the swf file path under swfPath object key.

Example
...
contextMenuCopyPaste: {swfPath: '[path to file]'}
...

copyableBoolean

Make cell copyable (pressing CTRL + C on your keyboard moves its value to system clipboard).

Note: this setting is false by default for cells with type password.

Since:
  • 0.10.2
Default Value:
  • true

copyColsLimitNumber

Maximum number of columns than can be copied to clipboard using CTRL + C.

Default Value:
  • 1000

copyPasteBoolean

Disable or enable the copy/paste functionality.

Default Value:
  • undefined
Example
...
copyPaste: false,
...

copyRowsLimitNumber

Maximum number of rows than can be copied to clipboard using CTRL + C.

Default Value:
  • 1000

correctFormatBoolean

If true then dates will be automatically formatted to match the desired format.

Option desired for 'date'-typed typed cells.

Default Value:
  • false
Example
...
columns: [{
  type: 'date',
  dateFormat: 'YYYY-MM-DD',
  correctFormat: true
}]
...

currentColClassNameString

Class name for all visible columns in the current selection.

Default Value:
  • undefined
Example
currentColClassName: 'currentColumn' // This will add a 'currentColumn' class name to appropriate table cells.

currentHeaderClassNameString

Class name for all visible headers in current selection.

Since:
  • 0.27.0
Default Value:
  • 'ht__highlight'
Example
currentHeaderClassName: 'ht__highlight' // This will add a 'ht__highlight' class name to appropriate table headers.

currentRowClassNameString

Class name for all visible rows in the current selection.

Default Value:
  • undefined
Example
currentRowClassName: 'currentRow' // This will add a 'currentRow' class name to appropriate table cells.

customBordersBoolean Array

If true, enables the Custom Borders plugin, which enables an option to apply custom borders through the context menu (configurable with context menu key borders).

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.

Since:
  • 0.11.0
Default Value:
  • false
Example
...
customBorders: [
  {range: {
    from: {row: 1, col: 1},
    to: {row: 3, col: 4}},
    left: {},
    right: {},
    top: {},
    bottom: {}
  }
],
...

// or
...
customBorders: [
  {row: 2, col: 2, left: {width: 2, color: 'red'},
    right: {width: 1, color: 'green'}, top: '', bottom: ''}
],
...

dataArray function

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, Array of Objects or a Function.

See Understanding binding as reference.

Default Value:
  • undefined

dataSchemaObject

Defines the structure of a new row when data source is an array of objects.

See data-schema for examples.

Default Value:
  • undefined

dateFormatString

Date validation format.

Option desired for 'date' - typed cells.

Default Value:
  • 'DD/MM/YYYY'
Example
...
columns: [{
  type: 'date',
  dateFormat: 'MM/DD/YYYY'
}]
...

debugBoolean

Setting to true enables the debug mode, currently used to test the correctness of the row and column
header fixed positioning on a layer above the master table.

Default Value:
  • false

defaultDateString

Definition of default value which will fill the empty cells.

Option desired for 'date'-typed cells.

Example
...
columns: [{
  type: 'date',
  defaultData: '2015-02-02'
}]
...

disableVisualSelectionBoolean String Array

Disable 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.
Since:
  • 0.13.2
Default Value:
  • false
Example
...
// as boolean
disableVisualSelection: true,
...

...
// as string ('current' or 'area')
disableVisualSelection: 'current',
...

...
// as array
disableVisualSelection: ['current', 'area'],
...

This plugin allows adding a configurable dropdown menu to the table's column headers.
The dropdown menu acts like the Context Menu, but is triggered by clicking the button in the header.

Since:
  • 1.0.0-beta1

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 disable cell editing passing false.

Default Value:
  • 'text'
Example
...
columns: [
  {
    editor: 'select'
  },
  {
    editor: false
  }
]
...

enterBeginsEditingBoolean

If true, ENTER begins editing mode (like in Google Docs). If false, ENTER moves to next
row (like Excel) and adds a new row if necessary. TAB adds new column if necessary.

Default Value:
  • true

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:
  • {row: 1, col: 0}

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.

Possible values: true (to enable in all directions), 'vertical' or 'horizontal' (to enable in one direction),
false (to disable completely). Setting to true enables the fillHandle plugin.

Since 0.23.0 you can pass object to plugin which allows you to add more options for this functionality. If autoInsertRow
option is true, fill-handler will create new rows till it reaches the last row. It is enabled by default.

Default Value:
  • true
Example
...
fillHandle: true // enable plugin in all directions and with autoInsertRow as true
...
// or
...
fillHandle: 'vertical' // enable plugin in vertical direction and with autoInsertRow as true
...
// 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' // 'vertical' or 'horizontal'
}

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 as 'false' all suggestions remain shown, with
those matching what has been typed marked in bold.

Default Value:
  • true

filteringCaseSensitiveBoolean

If defined as 'true', filtering in the Autocomplete Editor will be case-sensitive.

filtersBoolean

The filters plugin.
It allows filtering the table data either by the built-in component or with the API.

Since:
  • 1.0.0-beta1

fixedColumnsLeftNumber

Allows to specify the number of fixed (or frozen) columns on the left of the table.

Default Value:
  • 0
Example
fixedColumnsLeft: 3 // This would freeze the top 3 rows of the table.

fixedRowsBottomNumber

Allows to specify the number of fixed (or frozen) rows at the bottom of the table.

Default Value:
  • 0
Example
fixedRowsBottom: 3 // This would freeze the top 3 rows of the table.

fixedRowsTopNumber

Allows to specify the number of fixed (or frozen) rows at the top of the table.

Default Value:
  • 0
Example
fixedRowsTop: 3 // This would freeze the top 3 rows of the table.

formatString

Display format. See numbrojs. This option is desired for
numeric-typed cells.

Since 0.26.0 Handsontable uses numbro as a main library for numbers formatting.

Default Value:
  • '0'
Example
...
columns: [{
  type: 'numeric',
  format: '0,00'
}]
...

formulasBoolean

It allows Handsontable to process formula expressions defined in the provided data.

Since:
  • 1.7.0

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

ganttChartObject

GanttChart plugin enables a possibility to create a Gantt chart using a Handsontable instance.
In this case, the whole table becomes read-only.

Since:
  • 1.0.0-beta1

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).
Since:
  • 1.0.0-beta1

heightNumber function

Height of the grid. Can be a number or a function that returns a number.

Default Value:
  • undefined

hiddenColumnsBoolean Object

Plugin allowing hiding of certain columns.

Since:
  • 1.0.0-beta1

hiddenRowsBoolean Object

Plugin allowing hiding of certain rows.

Since:
  • 1.0.0-beta1

invalidCellClassNameString

CSS class name for cells that did not pass validation.

Default Value:
  • 'htInvalid'

labelObject

Object which describes if renderer should create checkbox element with label element as a parent. Option desired 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.
Since:
  • 0.19.0
Default Value:
  • undefined
Example
...
columns: [{
  type: 'checkbox',
  label: {position: 'after', value: 'My label: '}
}]
...

languageString

Language display format. See numbrojs. This option is desired for
numeric-typed cells.

Since 0.26.0 Handsontable uses numbro as a main library for numbers formatting.

Default Value:
  • 'en-US'
Example
...
columns: [{
  type: 'numeric',
  language: 'en-US'
}]
...

manualColumnFreezeBoolean

Disable or enable ManualColumnFreeze plugin.

Default Value:
  • false

manualColumnMoveBoolean Array

Turns on Manual column move, if set to a boolean or define initial
column order, if set to an array of column indexes.

Default Value:
  • undefined
Example
...
// as boolean
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

Turns on Manual column resize, if set to a boolean or define initial
column resized widths, if set to an array of numbers.

Default Value:
  • undefined
Example
...
// as boolean
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

Turns on Manual row move, if set to a boolean or define initial
row order, if set to an array of row indexes.

Since:
  • 0.11.0
Default Value:
  • undefined
Example
...
// as 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

Turns on Manual row resize, if set to a boolean or define initial
row resized heights, if set to an array of numbers.

Since:
  • 0.11.0
Default Value:
  • undefined
Example
...
// as boolean
manualRowResize: true
...
// as a array with initial heights (row at 0 index has 40px and row at 1 index has 50px)
manualRowResize: [40, 50]
...

maxColsNumber

Maximum number of cols.

Default Value:
  • Infinity

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

mergeCellsBoolean Array

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: [
  {row: 1, col: 1, rowspan: 3, colspan: 3}, // rowspan and colspan properties declare the width and height of a merged section in cells
  {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.

Default Value:
  • 0

minRowsNumber

Minimum number of rows. At least that number of rows will be created during initialization.

Default Value:
  • 0

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

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

multiSelectBoolean

If true, selection of multiple cells using keyboard or mouse is allowed.

Default Value:
  • true

nestedHeadersArray

Allows creating a nested header structure, using the HTML's colspan attribute.

Since:
  • 1.0.0-beta1

noWordWrapClassNameString

CSS class name added to cells with cell meta wordWrap: false.

Since:
  • 0.11.0
Default Value:
  • 'htNoWrap'

observeChangesBoolean

Enabling this 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.

Default Value:
  • false

observeDOMVisibilityBoolean

When set to true, the table is re-rendered when it is detected that it was made visible in DOM.

Default Value:
  • true

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

pasteModeString

Defines paste (CTRL + V) behavior.

  • Default value "overwrite" will paste clipboard value over current selection.
  • When set to "shift_down", clipboard data will be pasted in place of current selection, while all selected cells are moved down.
  • When set to "shift_right", clipboard data will be pasted in place of current selection, while all selected cells are moved right.
Default Value:
  • 'overwrite'

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 loaded value will be saved in valuePlaceholder.value
    (this is due to specific behaviour of Hooks.run() method). If no value have been saved under key valuePlaceholder.value
    will be undefined.

persistentStateReset (key: String)

  • Clears the value saved under key. If no key 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

placeholderMixed

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:
  • false

placeholderCellClassNameString

CSS class name for cells that have a placeholder in use.

Default Value:
  • 'htPlaceholder'

preventOverflowString Boolean

Prevents table to overlap outside the parent element. If 'horizontal' option is chosen then table will appear horizontal
scrollbar in case where parent's width is narrower then table's width.

Possible values:

  • false - Disables functionality (Default option).
  • horizontal - Prevents horizontal overflow table.
  • vertical - Prevents vertical overflow table (Not implemented yet).
Since:
  • 0.20.3
Example
...
preventOverflow: 'horizontal'
...

readOnlyBoolean

Make cell read only.

Default Value:
  • false

readOnlyCellClassNameString

CSS class name for read-only cells.

Default Value:
  • 'htDimmed'

renderAllRowsBoolean

If typed true then virtual rendering mechanism for handsontable will be disabled.

rendererString function

If a string is provided, it may be one of the following predefined values:

  • autocomplete,
  • checkbox,
  • text,
  • numeric.

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
...
columns: [
  {
    editor: 'select',
    renderer: 'autocomplete' // as string
  },
  {
    // renderer as custom function
    renderer: function(hotInstance, TD, row, col, prop, value, cellProperties) {
      TD.style.color = 'blue';
      TD.innerHTML = value;
    }
  }
]
...

rowHeadersBoolean Array 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:
  • null
Example
...
// as boolean
rowHeaders: true,
...

...
// as array
rowHeaders: [1, 2, 3],
...

...
// as function
rowHeaders: function(index) {
  return index + ': AB';
},
...

rowHeaderWidthNumber Array

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.

Since:
  • 0.22.0

rowHeightsArray function Number String

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

Default Value:
  • undefined

Setting to true enables the search plugin (see demo).

Default Value:
  • false

selectOptionsArray

Data source for select-typed cells.

Example
...
columns: [{
  editor: 'select',
  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

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

Option desired for cells of the 'autocomplete' type.

Default Value:
  • true

sortFunctionfunction

When passed to the column property, allows specifying a custom sorting function for the desired column.

Since:
  • 0.24.0
Example
columns: [
  {
    sortFunction: function(sortOrder) {
       return function(a, b) {
         // sorting function body.
         //
         // Function parameters:
         // sortOrder: If true, the order is ascending, if false - descending. undefined = original order
         // a, b: Two compared elements. These are 2-element arrays, with the first element being the row index, the second - cell value.
       }
    }
  }
]

sortIndicatorBoolean

Set whether to display the current sorting order indicator (a triangle icon in the column header, specifying the sorting order).

Since:
  • 0.15.0-beta3
Default Value:
  • 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('http://example.com/query?q=' + query, function(response) {
      callback(response.items);
    })
  }
}]
...

startColsNumber

Initial number of columns.

Notice: This option only has effect in Handsontable constructor and only if data option is not provided

Default Value:
  • 5

startRowsNumber

Initial number of rows.

Notice: This option only has effect in Handsontable constructor and only if data option is not provided

Default Value:
  • 5

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'

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.

Option desired for autocomplete-typed cells.

Example
...
columns: [{
  type: 'autocomplete',
  source: ['A', 'B', 'C'],
  strict: true
}]
...

tableClassNameString Array

Class name for all tables inside container element.

Since:
  • 0.17.0
Default Value:
  • undefined

tabMovesObject

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}

titleString

Defines the column header name.

Default Value:
  • undefined
Example
...
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.

Since:
  • 0.17.0
Default Value:
  • true

trimRowsBoolean Array

Plugin allowing hiding of certain rows.

Since:
  • 1.0.0-beta1

trimWhitespaceBoolean

Defines whether Handsontable should trim the whitespace at the beginning and the end of the cell contents.

Default Value:
  • true

typeString

Shortcut to define the combination of the cell renderer and editor for the column.

Possible values:

Default Value:
  • 'text'
Example
...
columns: [
  {
    type: 'text'
  },
  {
    type: 'checkbox'
  }
]
...

uncheckedTemplateBoolean String

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.

Default Value:
  • undefined

validatorfunction RegExp

A function or a regular expression, 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.

See more in the demo.

Since:
  • 0.9.5
Default Value:
  • undefined
Example
// as a function
columns: [
   {
     validator: function(value, callback) { // validation rules }
   }
]
...
// as a regexp
columns: [
   {
     validator: /^[0-9]$/ // regular expression
   }
]

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'

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'

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.

Since:
  • 0.18.0
Default Value:
  • 10

widthNumber function

Width of the grid. Can be a value or a function that returns a value.

Default Value:
  • undefined

wordWrapBoolean

When set to true, the text of the cell content is wrapped if it does not fit in the fixed column width.

Since:
  • 0.11.0
Default Value:
  • true

Methods

handsontable/src/core.js, line 4015

isEmptyCol(col){Boolean}

Lets you overwrite the default isEmptyCol method, which checks if column at the provided index is empty.

Parameters:
Name Type Description
col Number
Returns: {Boolean}
handsontable/src/core.js, line 3989

isEmptyRow(row){Boolean}

Lets you overwrite the default isEmptyRow method, which checks if row at the provided index is empty.

Parameters:
Name Type Description
row Number
Returns: {Boolean}