Home Original page

Configuration options

Plugin: Configuration options

Description

Configuration options let you heavily customize your Handsontable instance. For example, you can:

  • Enable and disable built-in features
  • Enable and configure additional plugins
  • Personalize Handsontable's look
  • Adjust Handsontable's behavior
  • Implement your own custom features

To apply configuration options, pass them as a second argument of the Handsontable constructor, using the object literal notation (opens new window):

Read more on the Configuration options page.

Depending on your needs, you can apply configuration options to different elements of your grid:

Read more:

Members

Source code

options.activeHeaderClassName : string

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

Read more:

Default: "ht__active_highlight"
Category: Core
Since: 0.38.2
Example

allowEmpty

Source code

options.allowEmpty : boolean

The allowEmpty option determines whether Handsontable accepts the following values:

  • null
  • undefined
  • ''

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

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

TIP

To use the allowEmpty option, you need to set the validator option (or the type option).

Default: true
Category: Core
Example

allowHtml

Source code

options.allowHtml : boolean

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

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

Setting Description
false (default) The source data is not treated as HTML
true The source data is treated as HTML

Warning: Setting the allowHtml option to true can cause serious XSS vulnerabilities.

Read more:

Default: false
Category: Core
Example

allowInsertColumn

Source code

options.allowInsertColumn : boolean

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

  • Insert column left
  • Insert column right

Default: true
Category: Core
Example

allowInsertRow

Source code

options.allowInsertRow : boolean

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

  • Insert row above
  • Insert row below

Default: true
Category: Core
Example

allowInvalid

Source code

options.allowInvalid : boolean

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

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

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

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

Read more:

Default: true
Category: Core
Example

allowRemoveColumn

Source code

options.allowRemoveColumn : boolean

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

  • Remove column

Read more:

Default: true
Category: Core
Example

allowRemoveRow

Source code

options.allowRemoveRow : boolean

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

  • Remove row

Read more:

Default: true
Category: Core
Example

ariaTags

Source code

options.ariaTags : boolean

If set to true, the accessibility-related ARIA tags will be added to the table. If set to false, they will be omitted. Defaults to true.

Default: true
Category: Core
Since: 14.0.0

autoColumnSize

Source code

options.autoColumnSize : object | boolean

The autoColumnSize option configures the AutoColumnSize plugin.

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

If you set the autoColumnSize option to an object, you can set the following AutoColumnSize plugin options:

Property Possible values Description
syncLimit A number | A percentage string The number/percentage of columns to keep in sync
(default: 50)
useHeaders true | false When calculating column widths:
true: use column headers
false: don't use column headers
samplingRatio A number The number of samples of the same length to be used in column width calculations
allowSampleDuplicates true | false When calculating column widths:
true: Allow duplicate samples
false: Don't allow duplicate samples

By default, the autoColumnSize option is set to undefined, but the AutoColumnSize plugin acts as enabled. To disable the AutoColumnSize plugin completely, set the autoColumnSize option to false.

Using the colWidths option forcibly disables the AutoColumnSize plugin.

Read more:

Default: undefined
Category: AutoColumnSize
Example

autoRowSize

Source code

options.autoRowSize : object | boolean

The autoRowSize option configures the AutoRowSize plugin.

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

Setting Description
false Disable the AutoRowSize plugin
true Enable the AutoRowSize plugin with the default configuration
An object Enable the AutoRowSize plugin and modify the plugin options

To give Handsontable's scrollbar a proper size, set the autoRowSize option to true.

If you set the autoRowSize option to an object, you can set the following AutoRowSize plugin options:

Property Possible values Description
syncLimit A number | A percentage string The number/percentage of rows to keep in sync
(default: 500)

Using the rowHeights option forcibly disables the AutoRowSize plugin.

Read more:

Default: undefined
Category: AutoRowSize
Example

autoWrapCol

Source code

options.autoWrapCol : boolean

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

When you select a top-most cell, pressing ↑ doesn't do anything.

true When you select a bottom-most cell, pressing ↓ takes you to the top-most cell of the next column.

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

Default: false
Category: Core
Example

autoWrapRow

Source code

options.autoWrapRow : boolean

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

When you select the last cell of a row, pressing →* (or Tab**) doesn't do anything.

true When you select the first cell of a row, pressing ←* (or Shift+Tab**) takes you to the last cell of the row above.

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

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

Default: false
Category: Core
Example

Source code

options.bindRowsWithHeaders : boolean | string

The bindRowsWithHeaders option configures the BindRowsWithHeaders plugin.

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

Read more:

Default: undefined
Category: BindRowsWithHeaders
Example

cell

Source code

options.cell : Array<Array>

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

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

Read more:

Default: []
Category: Core
Example

cells

Source code

options.cells : function

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

The cells option overwrites all other options (including options set by columns and cell). It takes the following parameters:

Parameter Required Type Description
row Yes Number A physical row index
column Yes Number A physical column index
prop No String | Number If data is set to an array of arrays, prop is the same number as column.

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

Read more:

Default: undefined
Category: Core
Example

checkedTemplate

Source code

options.checkedTemplate : boolean | string | number

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

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

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

Read more:

Default: true
Category: Core
Example

className

Source code

options.className : string | Array<string>

The className option lets you add CSS class names to every currently-selected element.

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

Setting Description
A string Add a single CSS class name to every currently-selected element
An array of strings Add multiple CSS class names to every currently-selected element

TIP

Don't change the className metadata of the column summary row. To style the summary row, use the class name assigned automatically by the ColumnSummary plugin: columnSummaryResult.

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

Read more:

Default: undefined
Category: Core
Example

Source code

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

The colHeaders option configures your grid's column headers.

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

Setting Description
true Enable the default column headers ('A', 'B', 'C', ...)
false Disable column headers
An array Define your own column headers (e.g. ['One', 'Two', 'Three', ...])
A function Define your own column headers, using a function

Read more:

Default: null
Category: Core
Example

collapsibleColumns

Source code

options.collapsibleColumns : boolean | Array<object>

The collapsibleColumns option configures the CollapsibleColumns plugin.

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

Read more:

Default: undefined
Category: CollapsibleColumns
Example

columnHeaderHeight

Source code

options.columnHeaderHeight : number | Array<number>

The columnHeaderHeight option configures the height of column headers.

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

Setting Description
A number Set the same height for every column header
An array Set different heights for individual column headers

Default: undefined
Category: Core
Example

columns

Source code

options.columns : Array<object> | function

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

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

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

The columns option overwrites the top-level grid options.

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

Read more:

Default: undefined
Category: Core
Example

columnSorting

Source code

options.columnSorting : boolean | object

The columnSorting option configures the ColumnSorting plugin.

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

If you set the columnSorting option to an object, you can set the following ColumnSorting plugin options:

Option Possible settings
indicator true: Display the arrow icon in the column header, to indicate a sortable column
false: Don't display the arrow icon in the column header
headerAction true: Enable clicking on the column header to sort the column
false: Disable clicking on the column header to sort the column
sortEmptyCells true: Sort empty cells as well
false: Place empty cells at the end
compareFunctionFactory A custom compare function

If you set the columnSorting option to an object, you can also sort individual columns at Handsontable's initialization. In the columnSorting object, add an object named initialConfig, with the following properties:

Option Possible settings Description
column A number The index of the column that you want to sort at initialization
sortOrder 'asc' | 'desc' The sorting order:
'asc': ascending
'desc': descending

Read more:

Default: undefined
Category: ColumnSorting
Example

columnSummary

Source code

options.columnSummary : Array<object> | function

The columnSummary option configures the ColumnSummary plugin.

You can set the columnSummary option to an array of objects. Each object configures a single column summary, using the following properties:

Read more:

Default: undefined
Category: ColumnSummary
Example

colWidths

Source code

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

The colWidths option sets columns' widths, in pixels.

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

Setting Description Example
A number Set the same width for every column colWidths: 100
A string Set the same width for every column colWidths: '100px'
An array Set widths separately for each column colWidths: [100, 120, undefined]
A function Set column widths dynamically,
on each render		 colWidths(visualColumnIndex) { return visualColumnIndex * 10; }
undefined Used by the modifyColWidth hook,
to detect column width changes.		 colWidths: undefined

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

Read more:

Default: undefined
Category: Core
Example

Source code

options.commentedCellClassName : string

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

Read more:

Default: "htCommentCell"
Category: Core
Example

Source code

options.comments : boolean | Array<object>

The comments option configures the Comments plugin.

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

Setting Description
true - Enable the Comments plugin
- Add comment menu items to the context menu
false Disable the Comments plugin
An object - Enable the Comments plugin
- Add comment menu items to the context menu
- Configure comment settings

If you set the comments option to an object, you can configure the following comment options:

Option Possible settings Description
displayDelay A number (default: 250) Display comments after a delay (in milliseconds)
readOnly true | false (default) true: Make comments read-only
style An object Set comment boxes' width and height (in pixels)

Read more:

Default: false
Category: Comments
Example

Source code

options.contextMenu : boolean | Array<string> | object

The contextMenu option configures the ContextMenu plugin.

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

Read more:

Default: undefined
Category: ContextMenu
Example

copyable

Source code

options.copyable : boolean

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

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

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

Read more:

Default: true
Category: Core
Example

copyPaste

Source code

options.copyPaste : object | boolean

The copyPaste option configures the CopyPaste plugin.

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

Setting Description
true (default) Enable the CopyPaste plugin with the default configuration
false Disable the CopyPaste plugin
An object - Enable the CopyPaste plugin
- Modify the CopyPaste plugin options
copyPaste: Additional options

If you set the copyPaste option to an object, you can set the following CopyPaste plugin options:

Option Possible settings Description
columnsLimit A number (default: Infinity) The maximum number of columns that can be copied
rowsLimit A number (default: Infinity) The maximum number of columns that can be copied
pasteMode 'overwrite' | 'shift_down' | 'shift_right' When pasting:
'overwrite': overwrite the currently-selected cells
'shift_down': move the currently-selected cells down
'shift_right': move the currently-selected cells to the right
copyColumnHeaders Boolean (default: false) true: add a context menu option for copying cells along with their nearest column headers
copyColumnGroupHeaders Boolean (default: false) true: add a context menu option for copying cells along with all their related columns headers
copyColumnHeadersOnly Boolean (default: false) true: add a context menu option for copying column headers nearest to the selected cells (without copying cells)
uiContainer An HTML element The UI container for the secondary focusable element

Read more:

Default: true
Category: CopyPaste
Example

correctFormat

Source code

options.correctFormat : boolean

The correctFormat option configures whether incorrectly-formatted times and dates are amended or not.

When the user enters dates and times, Handsontable can automatically adjust their format to match the dateFormat and timeFormat settings.

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

Setting Description
false (default) Don't correct the format of the entered date or time (treat the entered date or time as invalid)
true Correct the format of the entered date or time to match the dateFormat or timeFormat settings

Read more:

Default: false
Category: Core
Example

currentColClassName

Source code

options.currentColClassName : string

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

Read more:

Default: undefined
Category: Core
Example

Source code

options.currentHeaderClassName : string

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

Read more:

Default: "ht__highlight"
Category: Core
Example

currentRowClassName

Source code

options.currentRowClassName : string

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

Read more:

Default: undefined
Category: Core
Example

customBorders

Source code

options.customBorders : boolean | Array<object>

The customBorders option configures the CustomBorders plugin.

To enable the CustomBorders plugin (and add its menu items to the context menu), set the customBorders option to true.

To enable the CustomBorders plugin and add a predefined border around a particular cell, set the customBorders option to an array of objects. Each object represents a border configuration for one cell, and has the following properties:

Property Sub-properties Types Description
row - row: Number The cell's row coordinate.
col - col: Number The cell's column coordinate.
start width
color
style		 width: Number
color: String
style: String		 If the layout direction is LTR (default): start sets the width (width), color (color) and style (style) of the left-hand border.

If the layout direction is RTL: start sets the width (width), color (color) and style (style) of the right-hand border.

end width
color
style		 width: Number
color: String
style: String		 If the layout direction is LTR (default): end sets the width (width), color (color) and style (style) of the right-hand border.

If the layout direction is RTL: end sets the width (width), color (color) and style (style) of the left-hand border.

top width
color
style		 width: Number
color: String
style: String		 Sets the width (width), color (color) and style (style) of the top border.
bottom width
color
style		 width: Number
color: String
style: String		 Sets the width (width), color (color) and style (style) of the bottom border.

To enable the CustomBorders plugin and add a predefined border around a range of cells, set the customBorders option to an array of objects. Each object represents a border configuration for a single range of cells, and has the following properties:

Property Sub-properties Types Description
range from {row, col}
to {row, col}		 from: Object
to: Object
row: Number
col: Number		 If the layout direction is LTR (default):
- from selects the range's top-left corner.
- to selects the range's bottom-right corner.

If the layout direction is RTL:
- from selects the range's top-right corner.
- to selects the range's bottom-left corner.

start width
color
style		 width: Number
color: String
style: String		 If the layout direction is LTR (default): start sets the width (width), color (color) and style (style) of the left-hand border.

If the layout direction is RTL: start sets the width (width), color (color) and style (style) of the right-hand border.

end width
color
style		 width: Number
color: String
style: String		 If the layout direction is LTR (default): end sets the width (width), color (color) and style (style) of the right-hand border.

If the layout direction is RTL: end sets the width (width), color (color) and style (style) of the left-hand border.

top width
color
style		 width: Number
color: String
style: String		 Sets the width (width), color (color) and style (style) of the top border.
bottom width
color
style		 width: Number
color: String
style: String		 Sets the width (width), color (color) and style (style) of the bottom border.

Read more:

Default: false
Category: CustomBorders
Example

data

Source code

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

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

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

You can set the data option:

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

Read more:

Default: undefined
Category: Core
Example

dataDotNotation

Source code

options.dataDotNotation : boolean

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

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

Default: true
Category: Core
Since: 14.4.0
Example

dataSchema

Source code

options.dataSchema : object | function

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

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

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

  • An object
  • A function

Read more:

Default: undefined
Category: Core
Example

dateFormat

Source code

options.dateFormat : string

The dateFormat option configures the date format accepted by date cells.

You can set the dateFormat option to a string with a proper date format. The default value is: 'DD/MM/YYYY'.

To automatically correct dates whose format doesn't match the dateFormat setting, use the correctFormat option.

Read more:

Default: "DD/MM/YYYY"
Category: Core
Example

datePickerConfig

Source code

options.datePickerConfig : object

The datePickerConfig option configures the date cell editor's date picker, which uses an external dependency: Pikaday (opens new window).

You can set the datePickerConfig option to an object with any of the available Pikaday options (opens new window), except for the following, which are always overwritten by the date cell editor:

  • bound
  • container
  • field
  • trigger

If the datePickerConfig option is not defined, the date cell editor overwrites the following Pikaday options (opens new window) as well:

Pikaday option Handsontable's setting
format 'DD/MM/YYYY'
reposition false

Read more:

Default: undefined
Category: Core

defaultDate

Source code

options.defaultDate : string

The defaultDate option configures the date displayed in empty date cells.

You can set the defaultDate option to a string.

Read more:

Default: undefined
Category: Core
Example

dialog

Source code

options.dialog : boolean | object

The dialog option configures the Dialog plugin.

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

Setting Description
false Disable the Dialog plugin
true Enable the Dialog plugin with default options
dialog: Additional options
Option Possible settings Description
template Object with the template configuration (default: null). The template of the dialog allows to use prebuild templates
template.type The type of the template ('confirm') The type of the template
template.title The title of the template The title of the template
template.description The description of the template The description of the template
template.buttons Array of objects with the buttons configuration (default: []) The buttons of the template
template.buttons.text The text of the button The text of the button
template.buttons.type The type of the button ('primary' 'secondary')
template.buttons.callback The callback function to trigger when the button is clicked The callback function to trigger when the button is clicked
content A string, HTMLElement or DocumentFragment (default: '') The content of the dialog
customClassName A string (default: '') The custom class name of the dialog
background One of the options: 'solid' or 'semi-transparent' (default: 'solid') The background of the dialog
contentBackground Boolean (default: false) Whether to show the content background
animation Boolean (default: true) Whether to show the animation
closable Boolean (default: false) Whether to make the dialog closable
a11y Object with accessibility options (default: { role: 'dialog', ariaLabel: 'Dialog', ariaLabelledby: '', ariaDescribedby: '' }) Accessibility options for the dialog
a11y.role The role of the dialog ('dialog' 'alertdialog')
a11y.ariaLabel The label of the dialog The label of the dialog
a11y.ariaLabelledby The ID of the element that labels the dialog The ID of the element that labels the dialog
a11y.ariaDescribedby The ID of the element that describes the dialog The ID of the element that describes the dialog

Read more:

Default: false
Category: Dialog
Since: 16.1.0
Example

disableVisualSelection

Source code

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

The disableVisualSelection option configures how selection is shown.

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

Setting Description
false (default) - Show single-cell selection
- Show range selection
- Show header selection
true - Don't show single-cell selection
- Don't show range selection
- Don't show header selection
'current' - Don't show single-cell selection
- Show range selection
- Show header selection
'area' - Show single-cell selection
- Don't show range selection
- Show header selection
'header' - Show single-cell selection
- Show range selection
- Don't show header selection
An array A combination of 'current', 'area', and/or 'header'

Read more:

Default: false
Category: Core
Example

dragToScroll

Source code

options.dragToScroll : boolean

The dragToScroll option configures the DragToScroll plugin.

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

Setting Description
true (default) When selection reaches the edge of the grid's viewport, scroll the viewport
false Don't scroll the viewport

Read more:

Default: true
Category: DragToScroll
Example

Source code

options.dropdownMenu : boolean | object | Array<string>

The dropdownMenu option configures the DropdownMenu plugin.

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

Read more:

Default: undefined
Category: DropdownMenu
Example

editor

Source code

options.editor : string | function | boolean

The editor option sets a cell editor for a cell.

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

Alias Cell editor function
A custom alias Your custom cell editor function
'autocomplete' AutocompleteEditor
'base' BaseEditor
'checkbox' CheckboxEditor
'date' DateEditor
'dropdown' DropdownEditor
'handsontable' HandsontableEditor
'numeric' NumericEditor
'password' PasswordEditor
'select' SelectEditor
'text' TextEditor
'time' TimeEditor

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

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

Read more:

Default: undefined
Category: Core
Example

emptyDataState

Source code

options.emptyDataState : boolean | object

The emptyDataState option configures the EmptyDataState plugin.

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

If you set the emptyDataState option to an object, you can configure the following settings:

Property Possible values Description
message string | object | function Message to display in the empty data state overlay.

If you set the message option to an object, it have following properties:

Property Possible values Description
title string Title to display in the empty data state overlay.
description string Description to display in the empty data state overlay.
buttons array Buttons to display in the empty data state overlay.

If you set the buttons option to an array, each item requires following properties:

Property Possible values Description
text string Text to display in the button.
type 'primary' | 'secondary' Type of the button.
callback function Callback function to call when the button is clicked.

Read more:

Default: false
Category: EmptyDataState
Since: 16.2.0
Example

enterBeginsEditing

Source code

options.enterBeginsEditing : boolean

The enterBeginsEditing option configures the action of the Enter key.

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

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

Read more:

Default: true
Category: Core
Example

enterMoves

Source code

options.enterMoves : object | function

The enterMoves option configures the action of the Enter key.

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

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

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

Property Type Description
col Number - On pressing Enter, move selection col columns right
- On pressing Shift+Enter, move selection col columns left
row Number - On pressing Enter, move selection row rows down
- On pressing Shift+Enter, move selection row rows up

Read more:

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

fillHandle

Source code

options.fillHandle : boolean | string | object

The fillHandle option configures the Autofill plugin.

You can set the fillHandle option to one the following:

Setting Description
true - Enable autofill in all directions
- Add the fill handle
false Disable autofill
'vertical' - Enable vertical autofill
- Add the fill handle
'horizontal' - Enable horizontal autofill
- Add the fill handle
An object - Enable autofill
- Add the fill handle
- Configure autofill options

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

Option Possible settings Description
autoInsertRow true (default) | false true: When you reach the grid's bottom, add new rows
false: When you reach the grid's bottom, stop
direction 'vertical' | 'horizontal' 'vertical': Enable vertical autofill
'horizontal': Enable horizontal autofill

Read more:

Default: true
Category: Core
Example

filter

Source code

options.filter : boolean

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

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

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

Read more:

Default: true
Category: Core
Example

filteringCaseSensitive

Source code

options.filteringCaseSensitive : boolean

The filteringCaseSensitive option configures whether autocomplete cells' input is case-sensitive.

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

Setting Description
false (default) autocomplete cells' input is not case-sensitive
true autocomplete cells' input is case-sensitive

Read more:

Default: false
Category: Core
Example

filters

Source code

options.filters : boolean

The filters option configures the Filters plugin.

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

Setting Description
false Disable the Filters plugin
true Enable the Filters plugin
An object Enable the Filters plugin with custom settings

If you set the filters option to an object, you can configure the following settings:

Property Possible values Description
searchMode 'show' | 'apply' Enable filtering only visible elements

If filers is set to true, the searchMode option is set to 'show' by default.

Read more:

Default: undefined
Category: Filters
Example

fixedColumnsLeft

Source code

options.fixedColumnsLeft : number

fixedColumnsLeft is a legacy option.

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

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

Use fixedColumnsStart, which works in any layout direction.

Read more:

Default: 0
Category: Core
Example

fixedColumnsStart

Source code

options.fixedColumnsStart : number

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

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

Read more:

Default: 0
Category: Core
Example

fixedRowsBottom

Source code

options.fixedRowsBottom : number

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

Read more:

Default: 0
Category: Core
Example

fixedRowsTop

Source code

options.fixedRowsTop : number

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

Read more:

Default: 0
Category: Core
Example

formulas

Source code

options.formulas : object

The formulas option configures the Formulas plugin.

The Formulas plugin uses the HyperFormula (opens new window) calculation engine. To install HyperFormula (opens new window), read the following:

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

Read more:

Default: undefined
Category: Formulas
Example

fragmentSelection

Source code

options.fragmentSelection : boolean | string

The fragmentSelection option configures text selection settings.

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

Setting Description
false (default) Disable text selection
true Enable text selection in multiple cells at a time
'cell' Enable text selection in one cell at a time

Default: false
Category: Core
Example

Source code

options.headerClassName : string

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

Default: undefined
Category: Core
Since: 14.5.0
Example

height

Source code

options.height : number | string | function

The height option configures the height of your grid.

You can set height option to one of the following:

Setting Example
A number of pixels height: 500
A string with a CSS unit (opens new window) height: '75vw'
A function that returns a valid number or string height() { return 500; }

Read more:

Default: undefined
Category: Core
Example

hiddenColumns

Source code

options.hiddenColumns : boolean | object

The hiddenColumns option configures the HiddenColumns plugin.

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

Setting Description
false Disable the HiddenColumns plugin
true Enable the HiddenColumns plugin with the default plugin options
An object - Enable the HiddenColumns plugin
- Modify the plugin options

If you set the hiddenColumns to an object, you can set the following HiddenColumns plugin options:

Property Possible values Description
columns An array of indexes An array of indexes of columns that are hidden at initialization
copyPasteEnabled true | false true: when copying or pasting data, take hidden columns into account
false: when copying or pasting data, don't take hidden columns into account
indicators true | false true: display UI markers to indicate the presence of hidden columns
false: display UI markers

Read more:

Default: undefined
Category: HiddenColumns
Example

hiddenRows

Source code

options.hiddenRows : boolean | object

The hiddenRows option configures the HiddenRows plugin.

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

Setting Description
false Disable the HiddenRows plugin
true Enable the HiddenRows plugin with the default plugin options
An object - Enable the HiddenRows plugin
- Modify the plugin options

If you set the hiddenRows to an object, you can set the following HiddenRows plugin options:

Property Possible values Description
rows An array of indexes An array of indexes of rows that are hidden at initialization
copyPasteEnabled true | false true: when copying or pasting data, take hidden rows into account
false: when copying or pasting data, don't take hidden rows into account
indicators true | false true: display UI markers to indicate the presence of hidden rows
false: display UI markers

Read more:

Default: undefined
Category: HiddenRows
Example

imeFastEdit

Source code

options.imeFastEdit : boolean

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

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

Category: Core
Since: 14.0.0

initialState

Source code

options.initialState : object | undefined

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

Default: undefined
Category: Core
Since: 16.1.0
Example

invalidCellClassName

Source code

options.invalidCellClassName : string

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

Read more:

Default: "htInvalid"
Category: Core
Example

label

Source code

options.label : object

The label option configures checkbox cells` labels.

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

Property Possible values Description
position 'after' (default) | 'before' 'after': place the label to the right of the checkbox
'before': place the label to the left of the checkbox
value A string | A function The label's text
separated false (default) | true false: don't separate the label from the checkbox
true: separate the label from the checkbox
property A string - A data object property name that's used as the label's text
- Works only when the data option is set to an array of objects

Read more:

Default: undefined
Category: Core
Example

language

Source code

options.language : string

The language option configures Handsontable's language settings.

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

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

To properly render this language, set the layout direction to RTL.

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

Read more:

Default: "en-US"
Category: Core
Example

layoutDirection

Source code

options.layoutDirection : string

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

You can set the layout direction only at Handsontable's initialization. Any change of the layoutDirection option after the initialization (e.g. using the updateSettings() method) is ignored.

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

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

Setting Description
inherit (default) Set Handsontable's layout direction automatically,
based on the value of your HTML document's dir (opens new window) attribute
rtl Render Handsontable from the right to the left,
even when your HTML document's dir (opens new window) attribute is set to ltr
ltr Render Handsontable from the left to the right,
even when your HTML document's dir (opens new window) attribute is set to rtl

Read more:

Default: "inherit"
Category: Core
Example

licenseKey

Source code

options.licenseKey : string

The licenseKey option sets your Handsontable license key.

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

Read more:

Default: undefined
Category: Core
Example

loading

Source code

options.loading : boolean | object

The loading option configures the Loading plugin.

Loading plugin, automatically loads Dialog plugin.

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

Setting Description
false Disable the Loading plugin
true Enable the Loading plugin with default configuration
An object - Enable the Loading plugin
- Apply custom configuration

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

Option Possible settings Description
icon A string Custom loading icon to display (default: <svg />)
title A string Custom loading title to display (default: 'Loading...')
description A string Custom loading description to display (default: '')

Read more:

Default: false
Category: Loading
Since: 16.1.0
Example

locale

Source code

options.locale : string

The locale option configures Handsontable's locale settings.

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

Read more:

Default: "en-US"
Category: Core
Example

manualColumnFreeze

Source code

options.manualColumnFreeze : boolean

The manualColumnFreeze option configures the ManualColumnFreeze plugin.

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

Read more:

Default: undefined
Category: ManualColumnFreeze
Example

manualColumnMove

Source code

options.manualColumnMove : boolean | Array<number>

The manualColumnMove option configures the ManualColumnMove plugin.

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

Read more:

Default: undefined
Category: ManualColumnMove
Example

manualColumnResize

Source code

options.manualColumnResize : boolean | Array<number>

The manualColumnResize option configures the ManualColumnResize plugin.

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

Read more:

Default: undefined
Category: ManualColumnResize
Example

manualRowMove

Source code

options.manualRowMove : boolean | Array<number>

The manualRowMove option configures the ManualRowMove plugin.

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

Read more:

Default: undefined
Category: ManualRowMove
Example

manualRowResize

Source code

options.manualRowResize : boolean | Array<number>

The manualRowResize option configures the ManualRowResize plugin.

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

Read more:

Default: undefined
Category: ManualRowResize
Example

maxCols

Source code

options.maxCols : number

The maxCols option sets a maximum number of columns.

The maxCols option is used:

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

Default: Infinity
Category: Core
Example

maxRows

Source code

options.maxRows : number

The maxRows option sets a maximum number of rows.

The maxRows option is used:

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

Default: Infinity
Category: Core
Example

mergeCells

Source code

options.mergeCells : boolean | Array<object>

The mergeCells option configures the MergeCells plugin.

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

Setting Description
true Enable the MergeCells plugin
false Disable the MergeCells plugin
An array of objects - Enable the MergeCells plugin
- Merge specific cells at initialization
{ virtualized: true } Enable the MergeCells plugin with enabled virtualization mode

To merge specific cells at Handsontable's initialization, set the mergeCells option to an array of objects, with the following properties:

Property Description
row The row index of the merged section's beginning
col The column index of the merged section's beginning
rowspan The width (as a number of rows) of the merged section
colspan The height (as a number of columns ) of the merged section

Read more:

Default: false
Category: MergeCells
Example

minCols

Source code

options.minCols : number

The minCols option sets a minimum number of columns.

The minCols option is used:

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

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

Default: 0
Category: Core
Example

minRowHeights

Source code

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

Alias for the rowHeights option.

See the rowHeights option description for more information.

Default: undefined
Category: Core
Since: 16.2.0
Example

minRows

Source code

options.minRows : number

The minRows option sets a minimum number of rows.

The minRows option is used:

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

Default: 0
Category: Core
Example

minSpareCols

Source code

options.minSpareCols : number

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

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

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

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

Default: 0
Category: Core
Example

minSpareRows

Source code

options.minSpareRows : number

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

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

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

Default: 0
Category: Core
Example

multiColumnSorting

Source code

options.multiColumnSorting : boolean | object

The multiColumnSorting option configures the MultiColumnSorting plugin.

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

If you set the multiColumnSorting option to an object, you can set the following MultiColumnSorting plugin options:

Option Possible settings
indicator true: Display the arrow icon in the column header, to indicate a sortable column
false: Don't display the arrow icon in the column header
headerAction true: Enable clicking on the column header to sort the column
false: Disable clicking on the column header to sort the column
sortEmptyCells true: Sort empty cells as well
false: Place empty cells at the end
compareFunctionFactory A custom compare function

If you set the multiColumnSorting option to an object, you can also sort individual columns at Handsontable's initialization. In the multiColumnSorting object, add an object named initialConfig, with the following properties:

Option Possible settings Description
column A number The index of the column that you want to sort at initialization
sortOrder 'asc' | 'desc' The sorting order:
'asc': ascending
'desc': descending

Read more:

Default: undefined
Category: MultiColumnSorting
Example

Source code

options.navigableHeaders : boolean

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

Default: false
Category: Core
Since: 14.0.0
Example

Source code

options.nestedHeaders : boolean | Array<Array>

The nestedHeaders option configures the NestedHeaders plugin.

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

Setting Description
false (default) Disable the NestedHeaders plugin
true - Enable the NestedHeaders plugin
- Don't configure any nested headers
Array of arrays - Enable the NestedHeaders plugin
- Configure headers that are nested on Handsontable's initialization

If you set the nestedHeaders option to an array of arrays, each array configures one set of nested headers.

Each array element configures one header, and can be one of the following:

Array element Description
A string The header's label
An object Properties:
label (string): the header's label
colspan (integer): the column width

Read more:

Default: undefined
Category: NestedHeaders
Example

nestedRows

Source code

options.nestedRows : boolean

The nestedRows option configures the NestedRows plugin.

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

Read more:

Default: false
Category: NestedRows
Example

noWordWrapClassName

Source code

options.noWordWrapClassName : string

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

Read more:

Default: "htNoWrap"
Category: Core
Example

numericFormat

Source code

options.numericFormat : object

The numericFormat option configures the number format and the currency format of numeric cells` displayed output in the numeric cell renderer.

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

The numericFormat option as no effect on the numeric cell editor.

In the source data, numeric data is stored as JavaScript numbers.

Read more:

Default: undefined
Category: Core
Since: 0.35.0
Example

observeDOMVisibility

Source code

options.observeDOMVisibility : boolean

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

Default: true
Category: Core
Example

outsideClickDeselects

Source code

options.outsideClickDeselects : boolean | function

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

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

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

Default: true
Category: Core
Example

Source code

options.pagination : boolean

The pagination option configures the Pagination plugin.

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

If you set the pagination option to an object, you can set the following Pagination plugin options:

Option Possible settings Description
pageSize A number or auto (default: 10) Sets the number of rows displayed per page. If 'auto' is set, the page size will be calculated to match all rows to the currently set table's viewport height
pageSizeList An array (default: ['auto', 5, 10, 20, 50, 100]) Defines the selectable values for page size in the UI
initialPage A number (default: 1) Specifies which page to display on initial load
showPageSize Boolean (default: true) Controls visibility of the "page size" section
showCounter Boolean (default: true) Controls visibility of the "page counter" section (e.g., "1 - 10 of 50");
showNavigation Boolean (default: true) Controls visibility of the "page navigation" section
uiContainer An HTML element (default: null) The container element where the pagination UI will be installed. If not provided, the pagination container will be injected below the root table element.

Read more:

Default: undefined
Category: Pagination
Since: 16.1.0
Example

persistentState

Source code

options.persistentState : boolean

The persistentState option configures the PersistentState plugin.

You can set the persistentState to one of the following:

Read more:

Default: false
Category: PersistentState
Example

placeholder

Source code

options.placeholder : string

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

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

Setting Example Description
A non-empty string 'Empty cell' Display Empty cell text in empty cells
A non-string value 000 Display 000 text in empty cells (non-string values get stringified)

Read more:

Default: undefined
Category: Core
Example

placeholderCellClassName

Source code

options.placeholderCellClassName : string

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

Read more:

Default: "htPlaceholder"
Category: Core
Example

preventOverflow

Source code

options.preventOverflow : string | boolean

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

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

Setting Description
false (default) Don't prevent overflowing
'horizontal' Prevent horizontal overflowing
'vertical' Prevent vertical overflowing

Default: false
Category: Core
Example

readOnly

Source code

options.readOnly : boolean

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

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

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

Read more:

Default: false
Category: Core
Example

readOnlyCellClassName

Source code

options.readOnlyCellClassName : string

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

Read more:

Default: "htDimmed"
Category: Core
Example

renderAllColumns

Source code

options.renderAllColumns : boolean

The renderAllColumns option configures Handsontable's column virtualization.

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

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

Setting renderAllColumns to true overwrites the viewportColumnRenderingOffset setting.

Read more:

Default: false
Category: Core
Since: 14.1.0
Example

renderAllRows

Source code

options.renderAllRows : boolean

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

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

Setting renderAllRows to true overwrites the viewportRowRenderingOffset setting.

Read more:

Default: false
Category: Core
Example

renderer

Source code

options.renderer : string | function

The renderer option sets a cell renderer for a cell.

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

Alias Cell renderer function
A custom alias Your custom cell renderer function
'autocomplete' AutocompleteRenderer
'base' BaseRenderer
'checkbox' CheckboxRenderer
'date' DateRenderer
'dropdown' DropdownRenderer
'html' HtmlRenderer
'numeric' NumericRenderer
'password' PasswordRenderer
'text' TextRenderer
'time' TimeRenderer

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

Read more:

Default: undefined
Category: Core
Example

Source code

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

The rowHeaders option configures your grid's row headers.

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

Setting Description
true Enable the default row headers ('1', '2', '3', ...)
false Disable row headers
An array Define your own row headers (e.g. ['One', 'Two', 'Three', ...])
A function Define your own row headers, using a function

Read more:

Default: undefined
Category: Core
Example

Source code

options.rowHeaderWidth : number | Array<number>

The rowHeaderWidth option configures the width of row headers.

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

Setting Description
A number Set the same width for every row header
An array Set different widths for individual row headers

Default: undefined
Category: Core
Example

rowHeights

Source code

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

The rowHeights option sets rows' heights, in pixels.

In the rendering process, the default row height is classic (legacy): 23px, main: 29px, horizon: 37px (in the classic (legacy) theme: 22px + 1px of the row's bottom border) or whatever is defined in the used theme (based on the line height, vertical padding and cell borders). You can change it to equal or greater than the default value, by setting the rowHeights option to one of the following:

Setting Description Example
A number Set the same height for every row rowHeights: 100
A string Set the same height for every row rowHeights: '100px'
An array Set heights separately for each row rowHeights: [100, 120, undefined]
A function Set row heights dynamically,
on each render		 rowHeights(visualRowIndex) { return visualRowIndex * 10; }
undefined Used by the modifyRowHeight hook,
to detect row height changes		 rowHeights: undefined

The rowHeights option also sets the minimum row height that can be set via the ManualRowResize and AutoRowSize plugins (if they are enabled).

Read more:

Default: undefined
Category: Core
Example

Source code

options.search : boolean | object

The search option configures the Search plugin.

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

Setting Description
false (default) Disable the Search plugin
true Enable the Search plugin with the default configuration
An object - Enable the Search plugin
- Apply your custom configuration

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

Read more:

Default: false
Category: Search
Example

selectionMode

Source code

options.selectionMode : string

The selectionMode option configures how selection works.

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

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

Read more:

Default: "multiple"
Category: Core
Example

selectOptions

Source code

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

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

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

Setting Description
An array of strings Each string is one option's value and label
An object with key-string pairs - Each key is one option's value
- The key's string is that option's label
A function A function that returns an object with key-string pairs

Read more:

Default: undefined
Category: Core
Example

skipColumnOnPaste

Source code

options.skipColumnOnPaste : boolean

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

You can only apply the skipColumnOnPaste option to an entire column, using the columns option.

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

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

Read more:

Default: false
Category: Core
Example

skipRowOnPaste

Source code

options.skipRowOnPaste : boolean

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

You can only apply the skipRowOnPaste option to an entire row, using the cells option.

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

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

Read more:

Default: false
Category: Core
Example

sortByRelevance

Source code

options.sortByRelevance : boolean

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

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

Setting Description
true (default) Sort options in the same order as provided in the source option
false Sort options alphabetically

Read more:

Default: true
Category: Core
Example

source

Source code

options.source : Array | function

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

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

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

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

Read more:

Default: undefined
Category: Core
Example

startCols

Source code

options.startCols : number

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

The startCols option works only in Handsontable's constructor.

Default: 5
Category: Core
Example

startRows

Source code

options.startRows : number

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

The startRows option works only in Handsontable's constructor.

Default: 5
Category: Core
Example

stretchH

Source code

options.stretchH : string

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

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

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

Read more:

Default: "none"
Category: Core
Example

strict

Source code

options.strict : boolean

The strict option configures the behavior of autocomplete cells.

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

Setting Mode Description
true Strict mode The end user:
- Can only choose one of suggested values
- Can't enter a custom value
false Flexible mode The end user:
- Can choose one of suggested values
- Can enter a custom value

Read more:

Default: undefined
Category: Core
Example

tableClassName

Source code

options.tableClassName : string | Array<string>

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

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

Setting Description
A string Add a single CSS class name to every Handsontable instance inside the container element
An array of strings Add multiple CSS class names to every Handsontable instance inside the container element

Read more:

Default: undefined
Category: Core
Example

tabMoves

Source code

options.tabMoves : object | function

The tabMoves option configures the action of the Tab key.

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

Property Type Description
row Number - On pressing Tab, move selection row rows down
- On pressing Shift+Tab, move selection row rows up
col Number - On pressing Tab, move selection col columns right
- On pressing Shift+Tab, move selection col columns left

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

tabNavigation

Source code

options.tabNavigation : boolean

When set to false, the tabNavigation option changes the behavior of the Tab and Shift+Tab keyboard shortcuts. The Handsontable no more captures that shortcuts to make the grid navigation available (tabNavigation: true) but returns control to the browser so the native page navigation is possible.

Default: true
Category: Core
Since: 14.0.0
Example

textEllipsis

Source code

options.textEllipsis : boolean

The textEllipsis option configures whether the text content in the cells should be truncated with an ellipsis (three dots).

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

Setting Description
false (default) Don't truncate text content with an ellipsis
true Truncate text content with an ellipsis

Default: false
Category: Core
Since: 16.0.0
Example

themeName

Source code

options.themeName : string | boolean | undefined

The themeName option allows enabling a theme by that name.

If no themeName is provided, the table will use the classic (legacy) theme (if the correct CSS files are imported).

Read more:

Default: undefined
Category: Core
Since: 15.0.0
Example

timeFormat

Source code

options.timeFormat : string

The timeFormat option configures the time format accepted by time cells.

You can set the timeFormat option to a string with a proper time format. The default value is: 'h:mm:ss a'.

To automatically correct times whose format doesn't match the timeFormat setting, use the correctFormat option.

Read more:

Default: "h:mm:ss a"
Category: Core
Example

title

Source code

options.title : string

The title option configures column header names.

You can set the title option to a string.

Read more:

Default: undefined
Category: Core
Example

trimDropdown

Source code

options.trimDropdown : boolean

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

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

Setting Description
true (default) Make the dropdown/autocomplete list's width the same as the edited cell's width
false Scale the dropdown/autocomplete list's width to the list's content

Read more:

Default: true
Category: Core
Example

trimRows

Source code

options.trimRows : boolean | Array<number>

The trimRows option configures the TrimRows plugin.

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

Setting Description
false Disable the TrimRows plugin
true Enable the TrimRows plugin
An array of physical row indexes - Enable the TrimRows plugin
- Trim selected rows at initialization

Read more:

Default: undefined
Category: TrimRows
Example

trimWhitespace

Source code

options.trimWhitespace : boolean

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

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

Setting Description
true (default) Remove whitespace at the beginning and at the end of each cell
false Don't remove whitespace

Default: true
Category: Core
Example

type

Source code

options.type : string

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

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

Cell type Renderer, editor & validator
A custom cell type Renderer: your custom cell renderer
Editor: your custom cell editor
Validator: your custom cell validator
'autocomplete' Renderer: AutocompleteRenderer
Editor: AutocompleteEditor
Validator: AutocompleteValidator
'checkbox' Renderer: CheckboxRenderer
Editor: CheckboxEditor
Validator: -
'date' Renderer: DateRenderer
Editor: DateEditor
Validator: DateValidator
'dropdown' Renderer: DropdownRenderer
Editor: DropdownEditor
Validator: DropdownValidator
'handsontable' Renderer: AutocompleteRenderer
Editor: HandsontableEditor
Validator: -
'numeric' Renderer: NumericRenderer
Editor: NumericEditor
Validator: NumericValidator
'password' Renderer: PasswordRenderer
Editor: PasswordEditor
Validator: -
'text' Renderer: TextRenderer
Editor: TextEditor
Validator: -
'time' Renderer: TimeRenderer
Editor: TimeEditor
Validator: TimeValidator

Read more:

Default: "text"
Category: Core
Example

uncheckedTemplate

Source code

options.uncheckedTemplate : boolean | string | number

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

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

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

Read more:

Default: false
Category: Core
Example

undo

Source code

options.undo : boolean

The undo option configures the UndoRedo plugin.

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

Setting Description
true Enable the UndoRedo plugin
false Disable the UndoRedo plugin

By default, the undo option is set to true, To disable the UndoRedo plugin completely, set the undo option to false.

Read more:

Default: undefined
Category: UndoRedo
Example

validator

Source code

options.validator : function | RegExp | string

The validator option sets a cell validator for a cell.

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

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

Alias Cell validator function
A custom alias Your custom cell validator
'autocomplete' AutocompleteValidator
'date' DateValidator
'dropdown' DropdownValidator
'numeric' NumericValidator
'time' TimeValidator

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

Read more:

Default: undefined
Category: Core
Example

valueGetter

Source code

options.valueGetter : function

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

Default: undefined
Category: Core
Since: 16.1.0
Example

Param Type Description
value * The value to be displayed in the cell.
row number The visual row index of the cell.
column number The visual column index of the cell.
cellMeta object The cell meta object.

valueSetter

Source code

options.valueSetter : function

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

Default: undefined
Category: Core
Since: 16.1.0
Example

Param Type Description
value * The value to be set to a cell.
row number The visual row index of the cell.
column number The visual column index of the cell.
cellMeta object The cell meta object.

viewportColumnRenderingOffset

Source code

options.viewportColumnRenderingOffset : number | 'auto'

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

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

Setting Description
auto (default) Use the offset calculated automatically by Handsontable
A number Set the offset manually

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

Read more:

Default: 'auto'
Category: Core
Example

viewportColumnRenderingThreshold

Source code

options.viewportColumnRenderingThreshold : number | 'auto'

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

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

Setting Description
auto Triggers rendering at half the offset defined by viewportColumnRenderingOffset option
A number Sets the offset manually (0 is a default)

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

Read more:

Default: 0
Category: Core
Since: 1.14.7
Example

viewportRowRenderingOffset

Source code

options.viewportRowRenderingOffset : number | 'auto'

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

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

Setting Description
auto (default) Use the offset calculated automatically by Handsontable
A number Set the offset manually

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

Read more:

Default: 'auto'
Category: Core
Example

viewportRowRenderingThreshold

Source code

options.viewportRowRenderingThreshold : number | 'auto'

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

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

Setting Description
auto Triggers rendering at half the offset defined by viewportRowRenderingOffset option
A number Sets the offset manually (0 is a default)

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

Read more:

Default: 0
Category: Core
Since: 1.14.7
Example

visibleRows

Source code

options.visibleRows : number

The visibleRows option sets the height of the autocomplete and dropdown lists.

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

Read more:

Default: 10
Category: Core
Example

width

Source code

options.width : number | string | function

The width option configures the width of your grid.

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

Setting Example
A number of pixels width: 500
A string with a CSS unit (opens new window) width: '75vw'
A function that returns a valid number or string width() { return 500; }

Read more:

Default: undefined
Category: Core
Example

wordWrap

Source code

options.wordWrap : boolean

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

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

Setting Description
true (default) If content exceeds the column's width, wrap the content
false Don't wrap content

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

Read more:

Default: true
Category: Core
Example

Methods

isEmptyCol

Source code

options.isEmptyCol(col) ⇒ boolean

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

The isEmptyCol setting overwrites the built-in isEmptyCol method.

Category: Core
Example

Param Type Description
col number Visual column index.

isEmptyRow

Source code

options.isEmptyRow(row) ⇒ boolean

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

The isEmptyRow setting overwrites the built-in isEmptyRow method.

Category: Core
Example

Param Type Description
row number Visual row index.