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:

Read more on the Configuration options page.

1
const container = document.getElementById('example');
2

3
const hot = new Handsontable(container, {
4
  // configuration options, in the object literal notation
5
  licenseKey: 'non-commercial-and-evaluation',
6
  data: [
7
    ['A1', 'B1', 'C1', 'D1', 'E1'],
8
    ['A2', 'B2', 'C2', 'D2', 'E2'],
9
    ['A3', 'B3', 'C3', 'D3', 'E3'],
10
    ['A4', 'B4', 'C4', 'D4', 'E4'],
11
    ['A5', 'B5', 'C5', 'D5', 'E5'],
12
  ],
13
  width: 400,
14
  height: 300,
15
  colHeaders: true,
16
  rowHeaders: true,
17
  customBorders: true,
18
  dropdownMenu: true,
19
  multiColumnSorting: true,
20
  filters: true,
21
  manualRowMove: true,
22
});

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

Configuration options

Members

activeHeaderClassName

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

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

currentRowClassName
currentColClassName
currentHeaderClassName
invalidCellClassName
readOnlyCellClassName
commentedCellClassName
noWordWrapClassName
TableClassName
className

Default: “ht__active_highlight”
Category: Core
Since: 0.38.2
Example

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

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`

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

Default: true
Category: Core
Example

1
// allow empty values in each cell of the entire grid
2
allowEmpty: true,
3

4
// or
5
columns: [
6
  {
7
    type: 'date',
8
    dateFormat: 'DD/MM/YYYY',
9
    // allow empty values in each cell of the 'date' column
10
    allowEmpty: true
11
  }
12
],
13

14
// or, using the `cells` option
15
cells(row, col) {
16
  if (col === 2) {
17
    return { allowEmpty: false };
18
  }
19
},

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.

Default: false
Category: Core
Example

1
columns: [
2
  {
3
  // set the `type` of each cell in this column to `autocomplete`
4
  type: 'autocomplete',
5
  // set options available in every `autocomplete` cell of this column
6
  source: ['<strong>foo</strong>', '<strong>bar</strong>']
7
  // use HTML in the `source` list
8
  allowHtml: true,
9
  },
10
],

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

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

Default: true
Category: Core
Example

1
// hide the 'Insert column left' and 'Insert column right' menu items from the context menu
2
allowInsertColumn: false,

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

1
// hide the 'Insert row above' and 'Insert row below' menu items from the context menu
2
allowInsertRow: false,

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.

Default: true
Category: Core
Example

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

allowRemoveColumn

Source code

options.allowRemoveColumn : boolean

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

Remove column

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

Context menu

Default: true
Category: Core
Example

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

allowRemoveRow

Source code

options.allowRemoveRow : boolean

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

Remove row

Context menu

Default: true
Category: Core
Example

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

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:

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

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

Property	Possible values	Description
`syncLimit`	A number \| A percentage string	The number/percentage of columns to keep in sync (default: `50`)
`useHeaders`	`true` \| `false`	When calculating column widths: `true`: use column 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.

Plugins: AutoColumnSize

Default: undefined
Category: AutoColumnSize
Example

1
autoColumnSize: {
2
  // keep 40% of columns in sync (the rest of columns: async)
3
  syncLimit: '40%',
4
  // when calculating column widths, use column headers
5
  useHeaders: true,
6
  // when calculating column widths, use 10 samples of the same length
7
  samplingRatio: 10,
8
  // when calculating column widths, allow duplicate samples
9
  allowSampleDuplicates: true
10
},

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.

Plugins: AutoRowSize

Default: undefined
Category: AutoRowSize
Example

1
autoRowSize: {
2
  // keep 40% of rows in sync (the rest of rows: async)
3
  syncLimit: '40%'
4
},

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

1
// when you select a bottom-most cell, pressing ⬇ doesn't do anything
2
// when you select a top-most cell, pressing ⬆ doesn't do anything
3
autoWrapCol: false, // default setting
4

5
// when you select a bottom-most cell, pressing ⬇ takes you to the top-most cell of the next column
6
// when you select a top-most cell, pressing ⬆ takes you to the bottom-most cell of the previous column
7
autoWrapCol: true,

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

1
// when you select the first cell of a row, pressing ⬅ (or Shift+Tab) doesn't do anything
2
// when you select the last cell of a row, pressing ➡ (or Tab) doesn't do anything
3
autoWrapRow: false, // default setting
4

5
// when you select the first cell of a row, pressing ⬅ (or Shift+Tab) takes you to the last cell of the row above
6
// when you select the last cell of a row, pressing ➡ (or Tab) takes you to the first cell of the row below
7
autoWrapRow: true,

bindRowsWithHeaders

Source code

options.bindRowsWithHeaders : boolean | string

The bindRowsWithHeaders option configures the BindRowsWithHeaders plugin.

When enabled, each row stays permanently linked to its row header label, regardless of row sorting or row moving. Normally, row headers display the visual row index and update as rows are reordered; with this plugin enabled, the header travels with the data row it was originally assigned to.

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

Setting	Description
`false`	Disable the the `BindRowsWithHeaders` plugin
`true`	Enable the the `BindRowsWithHeaders` plugin

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

Plugins: BindRowsWithHeaders

Default: undefined
Category: BindRowsWithHeaders
Example

1
// enable the `BindRowsWithHeaders` plugin
2
bindRowsWithHeaders: true

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.

Default: []
Category: Core
Example

1
// set the `cell` option to an array of objects
2
cell: [
3
  // make the cell with coordinates (0, 0) read-only
4
  {
5
    row: 0,
6
    col: 0,
7
    readOnly: true
8
  }
9
],

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.

Default: undefined
Category: Core
Example

1
// set the `cells` option to your custom function
2
cells(row, column, prop) {
3
  const cellProperties = { readOnly: false };
4
  const visualRowIndex = this.instance.toVisualRow(row);
5
  const visualColIndex = this.instance.toVisualColumn(column);
6

7
  if (visualRowIndex === 0 && visualColIndex === 0) {
8
    cellProperties.readOnly = true;
9
  } else {
10
    cellProperties.readOnly = false;
11
  }
12

13
  return cellProperties;
14
},

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

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

Default: true
Category: Core
Example

1
columns: [
2
  {
3
    // set the `type` of each cell in this column to `checkbox`
4
    // when checked, the cell's value is `true`
5
    // when unchecked, the cell's value is `false`
6
    type: 'checkbox',
7
  },
8
  {
9
    // set the `type` of each cell in this column to `checkbox`
10
    type: 'checkbox',
11
    // when checked, the cell's value is `'Yes'`
12
    checkedTemplate: 'Yes',
13
    // when unchecked, the cell's value is `'No'`
14
    uncheckedTemplate: 'No'
15
 }
16
],

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

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

Configuration options: Cascading configuration
currentRowClassName
currentColClassName
currentHeaderClassName
activeHeaderClassName
invalidCellClassName
placeholderCellClassName
commentedCellClassName
noWordWrapClassName
readOnlyCellClassName
TableClassName

Default: undefined
Category: Core
Example

1
// add a `your-class-name` CSS class name
2
// to every currently-selected element
3
className: 'your-class-name',
4

5
// add `first-class-name` and `second-class-name` CSS class names
6
// to every currently-selected element
7
className: ['first-class-name', 'second-class-name'],

colHeaders

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

Column header

Default: null
Category: Core
Example

1
// enable the default column headers
2
colHeaders: true,
3

4
// set your own column headers
5
colHeaders: ['One', 'Two', 'Three'],
6

7
// set your own column headers, using a function
8
colHeaders: function(visualColumnIndex) {
9
  return `${visualColumnIndex} + : AB`;
10
},

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:

Setting	Description
`false`	Disable the `CollapsibleColumns` plugin
`true`	Enable the `CollapsibleColumns` plugin
An array of objects	Enable the `CollapsibleColumns` plugin for selected column headers

When using an array of objects, specify the header to make collapsible using row and col. The row value is a negative integer that counts header levels from the bottom of the header area: -1 is the header row closest to the data, -2 is one level above, and so on. This option requires the nestedHeaders plugin to be configured.

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

Default: undefined
Category: CollapsibleColumns
Example

1
// enable column collapsing for all headers
2
collapsibleColumns: true,
3

4
// enable column collapsing for selected headers
5
collapsibleColumns: [
6
  {row: -4, col: 1, collapsible: true},
7
  {row: -3, col: 5, collapsible: true}
8
],

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

1
// set the same height for every column header
2
columnHeaderHeight: 25,
3

4
// set different heights for individual column headers
5
columnHeaderHeight: [25, 30, 55],

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.

Default: undefined
Category: Core
Example

1
// set the `columns` option to an array of objects
2
// each object represents one column
3
columns: [
4
  {
5
    // column options for the first (by physical index) column
6
    type: 'numeric',
7
    numericFormat: {
8
      pattern: '0,0.00 $'
9
    }
10
  },
11
  {
12
    // column options for the second (by physical index) column
13
    type: 'text',
14
    readOnly: true
15
  }
16
],
17

18
// or set the `columns` option to a function, based on physical indexes
19
columns(index) {
20
  return {
21
    type: index > 0 ? 'numeric' : 'text',
22
    readOnly: index < 1
23
  }
24
}

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:

Setting	Description
`true`	Enable the `ColumnSorting` plugin with the default configuration
`false`	Disable the `ColumnSorting` plugin
An object	- Enable the `ColumnSorting` plugin - Modify the `ColumnSorting` plugin options

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

Option	Possible settings
`indicator`	`true`: Display the arrow icon in the column header, to indicate a sortable 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

Default: undefined
Category: ColumnSorting
Example

1
// enable the `ColumnSorting` plugin
2
columnSorting: true
3

4
// enable the `ColumnSorting` plugin with custom configuration
5
columnSorting: {
6
  // sort empty cells as well
7
  sortEmptyCells: true,
8
  // display the arrow icon in the column header
9
  indicator: true,
10
  // disable clicking on the column header to sort the column
11
  headerAction: false,
12
  // add a custom compare function
13
  compareFunctionFactory(sortOrder, columnMeta) {
14
    return function(value, nextValue) {
15
      // some value comparisons which will return -1, 0 or 1...
16
    }
17
  }
18
}
19

20
// enable the `ColumnSorting` plugin with an initial sort order:
21
// sort column 1 in ascending order at initialization
22
columnSorting: {
23
  initialConfig: {
24
    column: 1,
25
    sortOrder: 'asc'
26
  }
27
}

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:

Property	Possible values	Description
`sourceColumn`	A number	Column to summarize
`ranges`	An array	Ranges of rows to summarize
`type`	`'sum'` \| `'min'` \| `'max'` \| `'count'` \| `'average'` \| `'custom'`	Summary function
`destinationRow`	A number	Destination cell’s row coordinate
`destinationColumn`	A number	Destination cell’s column coordinate
`forceNumeric`	`true` \| `false`	Treat non-numerics as numerics
`reversedRowCoords`	`true` \| `false`	Reverse row coordinates
`suppressDataTypeErrors`	`true` \| `false`	Suppress data type errors
`readOnly`	`true` \| `false`	Make summary cell read-only
`roundFloat`	`true` \| `false` \| A number	Round summary result
`customFunction`	A function	Custom summary function

Default: undefined
Category: ColumnSummary
Example

1
columnSummary: [
2
  {
3
    sourceColumn: 0,
4
    ranges: [
5
      [0, 2], [4], [6, 8]
6
    ],
7
    type: 'custom',
8
    destinationRow: 4,
9
    destinationColumn: 1,
10
    forceNumeric: true,
11
    reversedRowCoords: true,
12
    suppressDataTypeErrors: false,
13
    readOnly: true,
14
    roundFloat: false,
15
    customFunction(endpoint) {
16
       return 100;
17
    }
18
  }
19
],

colWidths

Source code

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.

Default: undefined
Category: Core
Example

1
// set every column's width to 100px
2
colWidths: 100,
3

4
// set every column's width to 100px
5
colWidths: '100px',
6

7
// set the first (by visual index) column's width to 100
8
// set the second (by visual index) column's width to 120
9
// set the third (by visual index) column's width to `undefined`, so that it defaults to 50px
10
// set any other column's width to the default 50px (note that longer cell values and column names can get cut)
11
colWidths: [100, 120, undefined],
12

13
// set each column's width individually, using a function
14
colWidths(visualColumnIndex) {
15
  return visualColumnIndex * 10;
16
},

commentedCellClassName

Source code

options.commentedCellClassName : string

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

Comments
comments
readOnlyCellClassName
currentRowClassName
currentHeaderClassName
activeHeaderClassName
invalidCellClassName
placeholderCellClassName
readOnlyCellClassName
noWordWrapClassName
TableClassName
className

Default: “htCommentCell”
Category: Core
Example

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

comments

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)

Comments
Context menu
width
height
readOnly
commentedCellClassName

Default: false
Category: Comments
Example

1
// enable the `Comments` plugin
2
comments: true,
3

4
// enable the `Comments` plugin
5
// and configure its settings
6
comments: {
7
  // display all comments with a 1-second delay
8
  displayDelay: 1000,
9
  // make all comments read-only
10
  readOnly: true,
11
  // set the default size of all comment boxes
12
  style: {
13
    width: 300,
14
    height: 100
15
  }
16
}

contextMenu

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:

Setting	Description
`false`	Disable the `ContextMenu` plugin
`true`	- Enable the `ContextMenu` plugin - Use the default context menu options
An array	- Enable the `ContextMenu` plugin - Modify individual context menu options
An object	- Enable the `ContextMenu` plugin - Apply a custom context menu configuration

Default: undefined
Category: ContextMenu
Example

1
// enable the `ContextMenu` plugin
2
// use the default context menu options
3
contextMenu: true,
4

5
// enable the `ContextMenu` plugin
6
// and modify individual context menu options
7
contextMenu: ['row_above', 'row_below', '---------', 'undo', 'redo'],
8

9
// enable the `ContextMenu` plugin
10
// and apply a custom context menu configuration
11
contextMenu: {
12
  items: {
13
    'option1': {
14
      name: 'Option 1'
15
    },
16
    'option2': {
17
      name: 'Option 2',
18
      submenu: {
19
        items: [
20
          {
21
            key: 'option2:suboption1',
22
            name: 'Suboption 1',
23
            callback: function(key, options) {
24
              ...
25
            }
26
          },
27
          ...
28
        ]
29
      }
30
    }
31
  }
32
},

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

Default: true
Category: Core
Example

1
// enable copying for each cell of the entire grid
2
copyable: true,
3

4
// enable copying for individual columns
5
columns: [
6
  {
7
    // enable copying for each cell of this column
8
    copyable: true
9
  },
10
  {
11
    // disable copying for each cell of this column
12
    copyable: false
13
  }
14
]
15

16
// enable copying for specific cells
17
cell: [
18
  {
19
    col: 0,
20
    row: 0,
21
    // disable copying for cell (0, 0)
22
    copyable: false,
23
  }
24
],

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

Default: true
Category: CopyPaste
Example

1
// enable the plugin with the default configuration
2
copyPaste: true // set by default
3

4
// disable the plugin
5
copyPaste: false,
6

7
// enable the plugin with a custom configuration
8
copyPaste: {
9
  // set a maximum number of columns that can be copied
10
  columnsLimit: 25,
11

12
  // set a maximum number of rows that can be copied
13
  rowsLimit: 50,
14

15
  // set the paste behavior
16
  pasteMode: 'shift_down',
17

18
  // add the option to copy cells along with their nearest column headers
19
  copyColumnHeaders: true,
20

21
  // add the option to copy cells along with all their related columns headers
22
  copyColumnGroupHeaders: true,
23

24
  // add the option to copy just column headers (without copying cells)
25
  copyColumnHeadersOnly: true,
26

27
  // set a UI container
28
  uiContainer: document.body,
29
},

correctFormat Deprecated

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

Default: false
Category: Core
Example

1
columns: [
2
  {
3
  // set the `type` of each cell in this column to `date`
4
  type: 'date',
5
  // for every `date` cell of this column, set the date format to `YYYY-MM-DD`
6
  dateFormat: 'YYYY-MM-DD',
7
  // enforce the `YYYY-MM-DD` date format
8
  correctFormat: true
9
  },
10

11
  {
12
  // set the `type` of each cell in this column to `time`
13
  type: 'time',
14
  // for every `time` cell of this column, set the time format to `h:mm:ss a`
15
  timeFormat: 'h:mm:ss a',
16
  // enforce the `h:mm:ss a` time format
17
  correctFormat: true
18
  },
19
],

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.

currentRowClassName
currentHeaderClassName
activeHeaderClassName
invalidCellClassName
placeholderCellClassName
readOnlyCellClassName
commentedCellClassName
noWordWrapClassName
TableClassName
className

Default: undefined
Category: Core
Example

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

currentHeaderClassName

Source code

options.currentHeaderClassName : string

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

currentRowClassName
currentColClassName
activeHeaderClassName
invalidCellClassName
readOnlyCellClassName
commentedCellClassName
noWordWrapClassName
TableClassName
className

Default: “ht__highlight”
Category: Core
Example

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

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.

currentColClassName
currentHeaderClassName
activeHeaderClassName
invalidCellClassName
placeholderCellClassName
readOnlyCellClassName
commentedCellClassName
noWordWrapClassName
TableClassName
className

Default: undefined
Category: Core
Example

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

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.

Default: false
Category: CustomBorders
Example

1
// enable the `CustomBorders` plugin
2
customBorders: true,
3

4
// enable the `CustomBorders` plugin
5
// and add a predefined border for a particular cell
6
customBorders: [
7
  // add an object with a border configuration for one cell
8
  {
9
    // set the cell's row coordinate
10
    row: 2,
11
    // set the cell's column coordinate
12
    col: 2,
13
    // set the left/right border's width and color
14
    start: {
15
      width: 2,
16
      color: 'red'
17
    },
18
    // set the right/left border's width, color and style
19
    end: {
20
      width: 1,
21
      color: 'green',
22
      style: 'dashed'
23
    },
24
    // set the top border's width and color
25
    top: '',
26
    // set the bottom border's width and color
27
    bottom: ''
28
  }
29
],
30

31
// enable the `CustomBorders` plugin
32
// and add a predefined border for a range of cells
33
customBorders: [
34
  // add an object with a border configuration for one range of cells
35
  {
36
    // select a range of cells
37
    range: {
38
      // set the range's top-left corner
39
      from: {
40
        row: 1,
41
        col: 1
42
      },
43
      // set the range's bottom-right corner
44
      to: {
45
        row: 3,
46
        col: 4
47
      }
48
    },
49
    // set the left/right border's width, color and style
50
    start: {
51
      width: 2,
52
      color: 'red',
53
      style: 'dashed'
54
    },
55
    // set the right/left border's width and color
56
    end: {},
57
    // set the top border's width and color
58
    top: {},
59
    // set the bottom border's width and color
60
    bottom: {}
61
  }
62
],

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:

Either to an array of arrays.
Or to an array of objects.

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

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

Binding to data
dataSchema
startRows
startCols

Default: undefined
Category: Core
Example

1
// as an array of arrays
2
data: [
3
  ['A', 'B', 'C'],
4
  ['D', 'E', 'F'],
5
  ['G', 'H', 'J']
6
]
7

8
// as an array of objects
9
data: [
10
  {id: 1, name: 'Ted Right'},
11
  {id: 2, name: 'Frank Honest'},
12
  {id: 3, name: 'Joan Well'},
13
  {id: 4, name: 'Gail Polite'},
14
  {id: 5, name: 'Michael Fair'},
15
]
16

17
// as a column accessor inside `columns`
18
columns: [
19
  { data: 'id' },
20
  { data: 'name' }
21
]

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

1
// All dots are interpreted as nested object paths
2
dataDotNotation: true,
3
data: [
4
  { id: 1, name: { first: 'Ted', last: 'Right' }, user: { address: '1234 Any Street' } },
5
],
6
columns={[
7
  { data: 'name.first' },
8
  { data: 'user.address' },
9
]},

1
// All dots are interpreted as simple object keys
2
dataDotNotation: false,
3
data: [
4
  { id: 1, 'name.first': 'Ted', 'user.address': '1234 Any Street' },
5
],
6
columns={[
7
  { data: 'name.first' },
8
  { data: 'user.address' },
9
]},

dataProvider

Source code

options.dataProvider : object

When set, the table loads data from an async provider (e.g. a REST API) instead of a static data array. Use the object form with every key defined: rowId, fetchRows, onRowsCreate, onRowsUpdate, and onRowsRemove. All five are required on that object so paging, row identity, and create, update, and remove map cleanly to your backend. Pair with pagination for server-side paging. Valid cell edits apply at once; if onRowsUpdate fails or beforeRowsMutation blocks the update, affected cells roll back.

Default: undefined
Category: Core
Since: 17.1.0
Example

1
dataProvider: {
2
  rowId: 'id',
3
  fetchRows: async (queryParameters, { signal }) => {
4
    const { page, pageSize, sort, filters } = queryParameters;
5
    const params = new URLSearchParams({ page: String(page), pageSize: String(pageSize) });
6

7
    if (sort) {
8
      params.set('sortBy', sort.prop);
9
      params.set('sortDir', sort.order);
10
    }
11

12
    const res = await fetch(`/api/products?${params}`, { signal });
13
    const json = await res.json();
14

15
    return { rows: json.data, totalRows: json.total };
16
  },
17
  onRowsCreate: async ({ position, referenceRowId, rowsAmount }) => { ... },
18
  onRowsUpdate: async (rows) => { ... },
19
  onRowsRemove: async (rowIds) => { ... },
20
},

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

Default: undefined
Category: Core
Example

1
// with `dataSchema`, you can start with an empty grid
2
data: null,
3
dataSchema: {id: null, name: {first: null, last: null}, address: null},
4
colHeaders: ['ID', 'First Name', 'Last Name', 'Address'],
5
columns: [
6
  {data: 'id'},
7
  {data: 'name.first'},
8
  {data: 'name.last'},
9
  {data: 'address'}
10
],
11
startRows: 5,
12
minSpareRows: 1

dateFormat

Source code

options.dateFormat : string | object

Configures the date format for date cells. Accepts either a string (legacy, for date cells) or an object of Intl.DateTimeFormat options (for intl-date cells).

Object form (Intl.DateTimeFormat options):

The object form is supported only when the cell type is intl-date. The locale is controlled separately via the locale option.

Style shortcuts:

Property	Possible values	Description
`dateStyle`	`'full'`, `'long'`, `'medium'`, `'short'`	Date formatting style (expands to weekday, day, month, year, era)
`timeStyle`	`'full'`, `'long'`, `'medium'`, `'short'`	Time formatting style (expands to hour, minute, second, timeZoneName)

Date-time component options:

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

Locale and other options:

Property	Possible values	Description
`localeMatcher`	`'best fit'` (default), `'lookup'`	Locale matching algorithm
`calendar`	`'chinese'`, `'gregory'`, `'persian'`, etc.	Calendar to use
`numberingSystem`	`'latn'`, `'arab'`, `'hans'`, etc.	Numbering system
`timeZone`	IANA time zone (e.g. `'UTC'`, `'America/New_York'`)	Time zone for formatting
`hour12`	`true`, `false`	Use 12-hour vs 24-hour time
`hourCycle`	`'h11'`, `'h12'`, `'h23'`, `'h24'`	Hour cycle
`formatMatcher`	`'basic'`, `'best fit'` (default)	Format matching algorithm

For complete reference, see MDN: Intl.DateTimeFormat.

Deprecated: string form

Passing a string (e.g. 'DD/MM/YYYY', 'YYYY-MM-DD') is deprecated and works only with the date cell type. Migrate to the intl-date cell type and pass an Intl.DateTimeFormat options object.

Migration example:

1
// Before (deprecated)
2
columns: [{
3
  type: 'date',
4
  dateFormat: 'YYYY-MM-DD'
5
}]
6

7
// After (recommended)
8
columns: [{
9
  type: 'intl-date',
10
  locale: 'en-US',
11
  dateFormat: {
12
    year: 'numeric',
13
    month: '2-digit',
14
    day: '2-digit'
15
  }
16
}]

Default: “DD/MM/YYYY”
Category: Core
Example

1
// intl-date cell type with Intl options
2
columns: [
3
  {
4
    type: 'intl-date',
5
    locale: 'en-US',
6
    dateFormat: {
7
      dateStyle: 'short'
8
    }
9
  }
10
]

Example

1
// Legacy: date cell type with string format (deprecated)
2
columns: [
3
  {
4
    type: 'date',
5
    dateFormat: 'YYYY-MM-DD'
6
  }
7
]

datePickerConfig Deprecated

Source code

options.datePickerConfig : object

The `datePickerConfig` option configures the `date` [cell editor](/docs/javascript-data-grid/cell-editor/)'s date picker, which uses an external dependency: [Pikaday](https://github.com/Pikaday/Pikaday/tree/1.8.2).

You can set the datePickerConfig option to an object with any of the available Pikaday options, 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 as well:

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

Default: undefined
Category: Core

defaultDate

Source code

options.defaultDate : string

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

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

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

Default: undefined
Category: Core
Example

1
columns: [
2
  {
3
    type: 'date',
4
    defaultDate: '2015-02-02'
5
  }
6
],

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

Plugins: Dialog

Default: false
Category: Dialog
Since: 16.1.0
Example

1
// enable the Dialog plugin with default option
2
dialog: true,
3

4
// enable the Dialog plugin with custom configuration
5
dialog: {
6
  content: 'Dialog content',
7
  customClassName: 'custom-dialog',
8
  background: 'semi-transparent',
9
  contentBackground: false,
10
  animation: false,
11
  closable: true,
12
  a11y: {
13
    role: 'dialog',
14
    ariaLabel: 'Dialog',
15
    ariaLabelledby: 'titleID',
16
    ariaDescribedby: 'descriptionID',
17
  }
18
}
19

20
// enable the Dialog plugin using a template
21
dialog: {
22
  template: {
23
    type: 'confirm',
24
    title: 'Confirm',
25
    description: 'Do you want change the value?',
26
    buttons: [
27
      {
28
        text: 'Ok',
29
        type: 'primary',
30
        callback: () => {
31
          console.log('Ok');
32
        }
33
      },
34
    ],
35
  },
36
}

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'`

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

Selection

Default: false
Category: Core
Example

1
// don't show single-cell selection
2
// don't show range selection
3
// don't show header selection
4
disableVisualSelection: true,
5

6
// don't show single-cell selection
7
// show range selection
8
// show header selection
9
disableVisualSelection: 'current',
10

11
// don't show single-cell selection
12
// don't show range selection
13
// show header selection
14
disableVisualSelection: ['current', 'area'],

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

Plugins: DragToScroll

Default: true
Category: DragToScroll
Example

1
// when selection reaches the edge of the grid's viewport, scroll the viewport
2
dragToScroll: true,

dropdownMenu

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:

Setting	Description
`false`	Disable the `DropdownMenu` plugin
`true`	- Enable the `DropdownMenu` plugin - Use the default context menu options
An array	- Enable the `DropdownMenu` plugin - Modify individual context menu options
An object	- Enable the `DropdownMenu` plugin - Apply a custom dropdown menu configuration

This option can only be set at the grid level. It is not possible to show or hide the dropdown menu icon for individual columns using this option.

Default: undefined
Category: DropdownMenu
Example

1
// enable the `DropdownMenu` plugin
2
// use the default context menu options
3
dropdownMenu: true,
4

5
// enable the `DropdownMenu` plugin
6
// and modify individual context menu options
7
dropdownMenu: ['---------', 'undo', 'redo'],
8

9
// enable the `DropdownMenu` plugin
10
// and apply a custom dropdown menu configuration
11
dropdownMenu: {
12
  items: {
13
    'option1': {
14
      name: 'Option 1'
15
    },
16
    'option2': {
17
      name: 'Option 2',
18
      submenu: {
19
        items: [
20
          {
21
            key: 'option2:suboption1',
22
            name: 'Suboption 1',
23
            callback(key, options) {
24
              ...
25
            }
26
          },
27
          ...
28
        ]
29
      }
30
    }
31
  }
32
},

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`
`'intl-date'`	`IntlDateEditor`
`'dropdown'`	`DropdownEditor`
`'handsontable'`	`HandsontableEditor`
`'numeric'`	`NumericEditor`
`'password'`	`PasswordEditor`
`'select'`	`SelectEditor`
`'text'`	`TextEditor`
`'time'`	`TimeEditor`
`'intl-time'`	`IntlTimeEditor`

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

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

Default: undefined
Category: Core
Example

1
// use the `numeric` editor for each cell of the entire grid
2
editor: 'numeric',
3

4
// apply the `editor` option to individual columns
5
columns: [
6
  {
7
    // use the `autocomplete` editor for each cell of this column
8
    editor: 'autocomplete'
9
  },
10
  {
11
    // disable editing cells through cell editors for each cell of this column
12
    editor: false
13
  }
14
]

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:

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

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

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

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

Property	Possible values	Description
`title`	`string`	Title to display in the empty data state overlay.
`description`	`string`	Description to display in the empty data state overlay.
`buttons`	`array`	Buttons to display in the empty data state overlay.
`loading`	`boolean`	When `true`, shows a loading spinner (used for server fetch state).

If you set the message option to a function, the source argument can be "unknown", "filters", or "loading". With [[Options#dataProvider]], the "loading" branch follows DataProvider fetch hooks (beforeDataProviderFetch, afterDataProviderFetch, and related hooks) using the same rules as server-backed loading in the DataProvider plugin. Internal refetches (for example after column sort or CRUD) set skipLoading on [[Hooks#beforeDataProviderFetch]] so the EmptyDataState plugin can omit the loading overlay for those requests.

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

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

Plugins: EmptyDataState

Default: false
Category: EmptyDataState
Since: 16.2.0
Example

1
// Enable empty data state plugin with default messages
2
emptyDataState: true,
3

4
// Enable empty data state plugin with custom message
5
emptyDataState: {
6
  message: 'No data available',
7
},
8

9
// Enable empty data state plugin with custom message and buttons for any source
10
emptyDataState: {
11
  message: {
12
    title: 'No data available',
13
    description: 'There’s nothing to display yet.',
14
    buttons: [{ text: 'Reset filters', type: 'secondary', callback: () => {} }],
15
  },
16
},
17

18
// Enable empty data state plugin with custom message and buttons for specific source
19
emptyDataState: {
20
  message: (source) => {
21
    switch (source) {
22
      case "filters":
23
        return {
24
          title: 'No data available',
25
          description: 'There’s nothing to display yet.',
26
          buttons: [{ text: 'Reset filters', type: 'secondary', callback: () => {} }],
27
        };
28
      case "loading":
29
        return {
30
          title: 'Loading data',
31
          description: 'Please wait.',
32
        };
33
      default:
34
        return {
35
          title: 'No data available',
36
          description: 'There’s nothing to display yet.',
37
        };
38
    }
39
  },
40
},

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

enterMoves

Default: true
Category: Core
Example

1
// press Enter once to start editing
2
// press Enter twice to move to another cell
3
enterBeginsEditing: true,
4

5
// press Enter once to move to another cell
6
enterBeginsEditing: false,

enterCommits

Source code

options.enterCommits : boolean

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

Default: true
Category: Core
Since: 17.0.0
Example

1
columns: [{
2
  type: 'multiselect',
3
  // press Enter to close the `multiSelect` editor and Space to select an option
4
  enterCommits: true,
5
}, {
6
  type: 'multiselect',
7
  // press Enter to select an option
8
  enterCommits: false,
9
}],
10
],

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

enterBeginsEditing

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

1
// on pressing Enter, move selection 1 column right and 1 row down
2
// on pressing Shift+Enter, move selection 1 column left and 1 row up
3
enterMoves: {col: 1, row: 1},
4

5
// the same setting, as a function
6
// `event` is a DOM Event object received on pressing Enter
7
// you can use it to check whether the user pressed Enter or Shift+Enter
8
enterMoves(event) {
9
  return {col: 1, row: 1};
10
},

exportFile

Source code

options.exportFile : object

The exportFile option configures the ExportFile plugin.

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

Setting	Description
`undefined`	Use the `ExportFile` plugin with the default configuration
An object	Enable the `ExportFile` plugin and modify the plugin options

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

Option	Type	Default	Description
`engines`	`Object`	–	A map of format keys to their engine constructors. Pass `{ xlsx: ExcelJS }` to enable XLSX export via ExcelJS.

Default: undefined
Category: ExportFile
Since: 17.1.0
Example

1
import ExcelJS from 'exceljs';
2

3
// enable XLSX export
4
exportFile: {
5
  engines: { xlsx: ExcelJS },
6
},

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

AutoFill values

Default: true
Category: Core
Example

1
// enable autofill in all directions
2
// with `autoInsertRow` enabled
3
fillHandle: true,
4

5
// enable vertical autofill
6
// with `autoInsertRow` enabled
7
fillHandle: 'vertical',
8

9
// enable horizontal autofill
10
// with `autoInsertRow` enabled
11
fillHandle: 'horizontal',
12

13
// enable autofill in all directions
14
// with `autoInsertRow` disabled
15
fillHandle: {
16
  autoInsertRow: false,
17
},
18

19
// enable vertical autofill
20
// with `autoInsertRow` disabled
21
fillHandle: {
22
  autoInsertRow: false,
23
  direction: 'vertical'
24
},

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

Default: true
Category: Core
Example

1
columns: [{
2
  // set the `type` of each cell in this column to `autocomplete`
3
  type: 'autocomplete',
4
  // set options available in every `autocomplete` cell of this column
5
  source: ['A', 'B', 'C'],
6
  // when the end user types in `A`, display only the A option
7
  // when the end user types in `B`, display only the B option
8
  // when the end user types in `C`, display only the C option
9
  filter: true
10
}],

filteringCaseSensitive

Source code

options.filteringCaseSensitive : boolean

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

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

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

Default: false
Category: Core
Example

1
columns: [
2
  {
3
    type: 'autocomplete',
4
    source: [ ... ],
5
    // match case while searching autocomplete options
6
    filteringCaseSensitive: true
7
  },
8
  {
9
    type: 'multiselect',
10
    source: [ ... ],
11
    // match case while searching multiSelect options
12
    filteringCaseSensitive: true
13
  }
14
],

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.

Default: undefined
Category: Filters
Example

1
// enable the `Filters` plugin
2
filters: true,

filterSelectedItems

Source code

options.filterSelectedItems : boolean

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

Default: true
Category: Core
Example

1
// filter out the selected items from the dropdown
2
filterSelectedItems: true,
3

4
// keep the selected items in the dropdown
5
filterSelectedItems: false,
6

7

8
### fixedColumnsLeft
9

10
<button type="button" class="ask-about-api-btn" data-option="fixedColumnsLeft" data-plugin="Options" aria-label="Ask AI about fixedColumnsLeft">Ask AI</button>
11

12
<a href="https://github.com/handsontable/handsontable/blob/ee4829c9fe261b172939f298b26fad39f69427b0/handsontable/handsontable/src/dataMap/metaManager/metaSchema.js#L2885" target="_blank" rel="noopener noreferrer" class="source-code-link">Source code</a>
13

14
_options.fixedColumnsLeft : number_
15

16
`fixedColumnsLeft` is a legacy option.
17

18
If your grid's [layout direction](/docs/javascript-data-grid/layout-direction/) is LTR (default), `fixedColumnsLeft` acts like the [`fixedColumnsStart`](#fixedcolumnsstart) option.
19

20
If your grid's [layout direction](/docs/javascript-data-grid/layout-direction/) is RTL, using `fixedColumnsLeft` throws an error.
21

22
Use [`fixedColumnsStart`](#fixedcolumnsstart), which works in any layout direction.
23

24
Read more:
25
- [`fixedColumnsStart`](#fixedcolumnsstart)
26

27
**Default**: <code>0</code>
28
**Category**: [Core](/docs/javascript-data-grid/api/core/)
29
**Example**
30
```js
31
// freeze the first 3 columns from the left
32
fixedColumnsLeft: 3,

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.

Default: 0
Category: Core
Example

1
// when `layoutDirection` is set to `inherit` (default)
2
// freeze the first 3 columns from the left or from the right
3
// depending on your HTML document's `dir` attribute
4
layoutDirection: 'inherit',
5
fixedColumnsStart: 3,
6

7
// when `layoutDirection` is set to `rtl`
8
// freeze the first 3 columns from the right
9
// regardless of your HTML document's `dir` attribute
10
layoutDirection: 'rtl',
11
fixedColumnsStart: 3,
12

13
// when `layoutDirection` is set to `ltr`
14
// freeze the first 3 columns from the left
15
// regardless of your HTML document's `dir` attribute
16
layoutDirection: 'ltr',
17
fixedColumnsStart: 3,

fixedRowsBottom

Source code

options.fixedRowsBottom : number

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

Default: 0
Category: Core
Example

1
// freeze the bottom 3 rows
2
fixedRowsBottom: 3,

fixedRowsTop

Source code

options.fixedRowsTop : number

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

Default: 0
Category: Core
Example

1
// freeze the top 3 rows
2
fixedRowsTop: 3,

formulas

Source code

options.formulas : object

The formulas option configures the Formulas plugin.

The Formulas plugin uses the HyperFormula calculation engine. To install HyperFormula, read the following:

Formula calculation: Initialization methods

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

Property	Possible values
`engine`	`HyperFormula` \| A HyperFormula instance \| A HyperFormula configuration object
`sheetId`	A number
`sheetName`	A string

Default: undefined
Category: Formulas
Example

1
// either add the `HyperFormula` class
2
formulas: {
3
  // set `engine` to `HyperFormula`
4
  engine: HyperFormula,
5
  sheetId: 1,
6
  sheetName: 'Sheet 1'
7
}
8

9
// or, add a HyperFormula instance
10
// initialized with the `'internal-use-in-handsontable'` license key
11
const hyperformulaInstance = HyperFormula.buildEmpty({
12
  licenseKey: 'internal-use-in-handsontable',
13
});
14

15
formulas: {
16
  // set `engine` to a HyperFormula instance
17
  engine: hyperformulaInstance,
18
  sheetId: 1,
19
  sheetName: 'Sheet 1'
20
}
21

22
// or, add a HyperFormula configuration object
23
formulas: {
24
  // set `engine` to a HyperFormula configuration object
25
  engine: {
26
    hyperformula: HyperFormula // or `engine: hyperformulaInstance`
27
    leapYear1900: false,       // this option comes from HyperFormula
28
    // add more HyperFormula configuration options
29
  },
30
  sheetId: 1,
31
  sheetName: 'Sheet 1'
32
}
33

34
// use the same HyperFormula instance in multiple Handsontable instances
35

36
// a Handsontable instance `hot1`
37
formulas: {
38
  engine: HyperFormula,
39
  sheetId: 1,
40
  sheetName: 'Sheet 1'
41
}
42

43
// a Handsontable instance `hot2`
44
formulas: {
45
  engine: hot1.getPlugin('formulas').engine,
46
  sheetId: 1,
47
  sheetName: 'Sheet 1'
48
}

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

1
// enable text selection in multiple cells at a time
2
fragmentSelection: true,
3

4
// enable text selection in one cell a time
5
fragmentSelection: 'cell',

headerClassName

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

1
// Adding class names to all column headers
2
headerClassName: 'htRight my-class',
3

4
columns: [
5
 {
6
   // Adding class names to the column header of a single column
7
   headerClassName: 'htRight my-class',
8
 }
9
]

height

Source code

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

The height option configures the height of your grid.

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

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

How `'auto'` differs from leaving `height` unset

When you set height: 'auto', Handsontable writes height: auto; overflow: clip; as inline styles on the root element. The grid then grows to match its content height. No internal vertical scrollbar is created, so the page itself scrolls when the grid exceeds the viewport.

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

Grid size

Default: undefined
Category: Core
Example

1
// set the grid's height to 500px
2
height: 500,
3

4
// set the grid's height to 75vh
5
height: '75vh',
6

7
// let the grid grow to fit all its rows (no internal vertical scroll)
8
height: 'auto',
9

10
// set the grid's height to 500px, using a function
11
height() {
12
  return 500;
13
},

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

Default: undefined
Category: HiddenColumns
Example

1
// enable the `HiddenColumns` plugin
2
hiddenColumns: true,
3

4
// enable `HiddenColumns` plugin, and modify the plugin options
5
hiddenColumns: {
6
  // set columns that are hidden by default
7
  columns: [5, 10, 15],
8
  // when copying or pasting data, take hidden columns into account
9
  copyPasteEnabled: true,
10
  // show where hidden columns are
11
  indicators: true
12
}

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

Default: undefined
Category: HiddenRows
Example

1
// enable the `HiddenRows` plugin
2
hiddenRows: true,
3

4
// enable `HiddenRows` plugin, and modify the plugin options
5
hiddenRows: {
6
  // set rows that are hidden by default
7
  rows: [5, 10, 15],
8
  // when copying or pasting data, take hidden rows into account
9
  copyPasteEnabled: true,
10
  // show where hidden rows are
11
  indicators: true
12
}

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

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

injectCoreCss

Source code

options.injectCoreCss : boolean

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

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

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

Themes

Default: true
Category: Core
Since: 17.0.0
Example

1
// inject core CSS (default)
2
injectCoreCss: true,
3

4
// skip injection when you load Handsontable CSS yourself
5
injectCoreCss: false,

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.

Cell validator
currentRowClassName
currentHeaderClassName
activeHeaderClassName
currentColClassName
readOnlyCellClassName
commentedCellClassName
noWordWrapClassName
TableClassName
className

Default: “htInvalid”
Category: Core
Example

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

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

Checkbox cell type: Checkbox labels

Default: undefined
Category: Core
Example

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

language

Source code

options.language : string

The language option configures Handsontable’s language settings.

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

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

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

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

Language
locale
layoutDirection

Default: “en-US”
Category: Core
Example

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

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` attribute
`rtl`	Render Handsontable from the right to the left, even when your HTML document’s `dir` attribute is set to `ltr`
`ltr`	Render Handsontable from the left to the right, even when your HTML document’s `dir` attribute is set to `rtl`

Layout direction
Language
language
locale
fixedColumnsStart
customBorders

Default: “inherit”
Category: Core
Example

1
// inherit Handsontable's layout direction
2
// from the value of your HTML document's `dir` attribute
3
layoutDirection: 'inherit',
4

5
// render Handsontable from the right to the left
6
// regardless of your HTML document's `dir`
7
layoutDirection: 'rtl',
8

9
// render Handsontable from the left to the right
10
// regardless of your HTML document's `dir`
11
layoutDirection: 'ltr',

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:

Setting	Description
A string with your commercial license key	For commercial use
`'non-commercial-and-evaluation'`	For non-commercial use

License key

Default: undefined
Category: Core
Example

1
// for commercial use
2
licenseKey: 'xxxxx-xxxxx-xxxxx-xxxxx-xxxxx', // your commercial license key
3

4
// for non-commercial use
5
licenseKey: 'non-commercial-and-evaluation',

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: `''`)

Plugins: Loading

Default: false
Category: Loading
Since: 16.1.0
Example

1
// enable the `Loading` plugin with default configuration
2
loading: true,
3

4
// enable the `Loading` plugin with custom configuration
5
loading: {
6
  icon: 'A custom loading icon in SVG format',
7
  title: 'Custom loading title',
8
  description: 'Custom loading description',
9
}

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.

Locale
language
layoutDirection

Default: “en-US”
Category: Core
Example

1
// set the entire grid's locale to Polish
2
locale: 'pl-PL',
3

4
// set individual columns' locales
5
columns: [
6
  {
7
    // set the first column's locale to Polish
8
    locale: 'pl-PL',
9
  },
10
  {
11
    // set the second column's locale to German
12
    locale: 'de-DE',
13
  },
14
],

manualColumnFreeze

Source code

options.manualColumnFreeze : boolean

The manualColumnFreeze option configures the ManualColumnFreeze plugin.

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

Setting	Description
`true`	Enable the `ManualColumnFreeze` plugin
`false`	Disable the `ManualColumnFreeze` plugin

Column freezing

Default: undefined
Category: ManualColumnFreeze
Example

1
// enable the `ManualColumnFreeze` plugin
2
manualColumnFreeze: true,

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:

Setting	Description
`true`	Enable the `ManualColumnMove` plugin
`false`	Disable the `ManualColumnMove` plugin
An array	- Enable the `ManualColumnMove` plugin - Move individual columns at initialization

Column moving

Default: undefined
Category: ManualColumnMove
Example

1
// enable the `ManualColumnMove` plugin
2
manualColumnMove: true,
3

4
// enable the `ManualColumnMove` plugin
5
// at initialization, move column 0 to 1
6
// at initialization, move column 1 to 4
7
// at initialization, move column 2 to 6
8
manualColumnMove: [1, 4, 6],

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:

Setting	Description
`true`	Enable the `ManualColumnResize` plugin
`false`	Disable the `ManualColumnResize` plugin
An array	- Enable the `ManualColumnResize` plugin - Set initial widths of individual columns

Column width: Column stretching

Default: undefined
Category: ManualColumnResize
Example

1
// enable the `manualColumnResize` plugin
2
manualColumnResize: true,
3

4
// enable the `manualColumnResize` plugin
5
// set the initial width of column 0 to 40 pixels
6
// set the initial width of column 1 to 50 pixels
7
// set the initial width of column 2 to 60 pixels
8
manualColumnResize: [40, 50, 60],

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:

Setting	Description
`true`	Enable the `ManualRowMove` plugin
`false`	Disable the `ManualRowMove` plugin
An array	- Enable the `ManualRowMove` plugin - Move individual rows at initialization

Row moving

Default: undefined
Category: ManualRowMove
Example

1
// enable the `ManualRowMove` plugin
2
manualRowMove: true,
3

4
// enable the `ManualRowMove` plugin
5
// at initialization, move row 1 to 0
6
// at initialization, move row 4 to 1
7
// at initialization, move row 6 to 2
8
manualRowMove: [1, 4, 6],

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:

Setting	Description
`true`	Enable the `ManualRowResize` plugin
`false`	Disable the `ManualRowResize` plugin
An array	- Enable the `ManualRowResize` plugin - Set initial heights of individual rows

Row height: Adjust the row height manually

Default: undefined
Category: ManualRowResize
Example

1
// enable the `ManualRowResize` plugin
2
manualRowResize: true,
3

4
// enable the `ManualRowResize` plugin
5
// set the initial height of row 0 to 40 pixels
6
// set the initial height of row 1 to 50 pixels
7
// set the initial height of row 2 to 60 pixels
8
manualRowResize: [40, 50, 60],

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

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

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

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

maxSelections

Source code

options.maxSelections : number

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

Default: undefined
Category: Core
Since: 17.0.0
Example

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

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

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

Merge cells

Default: false
Category: MergeCells
Example

1
// enable the `MergeCells` plugin
2
mergeCells: true,
3

4
// enable the `MergeCells` plugin
5
// and merge specific cells at initialization
6
mergeCells: [
7
  // merge cells from cell (1,1) to cell (3,3)
8
  {row: 1, col: 1, rowspan: 3, colspan: 3},
9
  // merge cells from cell (3,4) to cell (2,2)
10
  {row: 3, col: 4, rowspan: 2, colspan: 2},
11
  // merge cells from cell (5,6) to cell (3,3)
12
  {row: 5, col: 6, rowspan: 3, colspan: 3}
13
],
14

15
// enable the `MergeCells` plugin with enabled virtualization mode
16
// and merge specific cells at initialization
17
mergeCells: {
18
  virtualized: true,
19
  cells: [
20
    // merge cells from cell (1,1) to cell (3,3)
21
    {row: 1, col: 1, rowspan: 3, colspan: 3},
22
    // merge cells from cell (3,4) to cell (2,2)
23
    {row: 3, col: 4, rowspan: 2, colspan: 2},
24
    // merge cells from cell (5,6) to cell (3,3)
25
    {row: 5, col: 6, rowspan: 3, colspan: 3}
26
  ],
27
},

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:

The first data row
The dataSchema option
The columns option

Default: 0
Category: Core
Example

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

minRowHeights

Source code

Alias for the rowHeights option.

See the rowHeights option description for more information.

Default: undefined
Category: Core
Since: 16.2.0
Example

1
// set every row's minimum height to 100px
2
minRowHeights: 100,
3

4
// set every row's minimum height to 100px
5
minRowHeights: '100px',
6

7
// set the first (by visual index) row's minimum height to 100
8
// set the second (by visual index) row's minimum height to 120
9
// set any other row's minimum height to the default height value
10
minRowHeights: [100, 120],
11

12
// set each row's minimum height individually, using a function
13
minRowHeights(visualRowIndex) {
14
  return visualRowIndex * 10;
15
},

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

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

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:

The first data row
The dataSchema option
The columns option

Default: 0
Category: Core
Example

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

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

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

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:

Setting	Description
`true`	Enable the `MultiColumnSorting` plugin with the default configuration
`false`	Disable the `MultiColumnSorting` plugin
An object	- Enable the `MultiColumnSorting` plugin - Modify the `MultiColumnSorting` plugin options

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

Option	Possible settings
`indicator`	`true`: Display the arrow icon in the column header, to indicate a sortable 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

Default: undefined
Category: MultiColumnSorting
Example

1
// enable the `MultiColumnSorting` plugin
2
multiColumnSorting: true
3

4
// enable the `MultiColumnSorting` plugin with custom configuration
5
multiColumnSorting: {
6
  // sort empty cells as well
7
  sortEmptyCells: true,
8
  // display the arrow icon in the column header
9
  indicator: true,
10
  // disable clicking on the column header to sort the column
11
  headerAction: false,
12
  // add a custom compare function
13
  compareFunctionFactory(sortOrder, columnMeta) {
14
    return function(value, nextValue) {
15
      // some value comparisons which will return -1, 0 or 1...
16
    }
17
  }
18
}
19

20
// enable the `MultiColumnSorting` plugin with a multi-column initial sort order:
21
// sort column 1 ascending first, then column 2 descending
22
multiColumnSorting: {
23
  initialConfig: [
24
    { column: 1, sortOrder: 'asc' },
25
    { column: 2, sortOrder: 'desc' }
26
  ]
27
}

navigableHeaders

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

1
// you can navigate row and column headers with the keyboard
2
navigableHeaders: true,
3

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

nestedHeaders

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): number of data columns the header spans `rowspan` (integer): number of header rows the header spans `headerClassName` (string): optional space-separated CSS class names

Default: undefined
Category: NestedHeaders
Example

1
nestedHeaders: [
2
  ['A', {label: 'B', colspan: 8}, 'C'],
3
  ['D', {label: 'E', colspan: 4}, {label: 'F', colspan: 4}, 'G'],
4
  ['H', 'I', 'J', 'K', 'L', 'M', 'N', 'R', 'S', 'T']
5
],

nestedRows

Source code

options.nestedRows : boolean

The nestedRows option configures the NestedRows plugin.

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

Setting	Description
`false` (default)	Disable the `NestedRows` plugin
`true`	Enable the `NestedRows` plugin

Plugins: NestedRows

Default: false
Category: NestedRows
Example

1
// enable the `NestedRows` plugin
2
nestedRows: true,

notification

Source code

options.notification : boolean | object

The notification option configures the Notification plugin.

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

Setting	Description
`false`	Disable the `Notification` plugin
`true`	Enable the plugin with default options
An object	Enable the plugin and set `stackLimit` and `animation`

notification: Additional options

Option	Type	Default	Description
`stackLimit`	`number`	`10`	Maximum visible toasts per corner. Extra requests are queued.
`animation`	`boolean`	`true`	Fade and slide animation when toasts appear.

Plugins: Notification

Default: false
Category: Notification
Since: 17.1.0
Example

1
notification: true,

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.

wordWrap
currentRowClassName
currentColClassName
currentHeaderClassName
invalidCellClassName
readOnlyCellClassName
commentedCellClassName
noWordWrapClassName
TableClassName
className

Default: “htNoWrap”
Category: Core
Example

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

numericFormat

Source code

options.numericFormat : object

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

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

Style options:

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

Notation options:

Property	Possible values	Description
`notation`	`'standard'` (default), `'scientific'`, `'engineering'`, `'compact'`	The formatting notation
`compactDisplay`	`'short'` (default), `'long'`	Display style for compact notation (e.g., `1.5M` vs `1.5 million`)

Sign and grouping options:

Property	Possible values	Description
`signDisplay`	`'auto'` (default), `'never'`, `'always'`, `'exceptZero'`, `'negative'`	When to display the sign
`useGrouping`	`true`, `false` (default), `'always'`, `'auto'`, `'min2'`	Whether to use grouping separators (e.g., `1,000`)

Digit options:

Property	Possible values	Description
`minimumIntegerDigits`	`1` to `21`	Minimum number of integer digits (pads with zeros)
`minimumFractionDigits`	`0` to `100`	Minimum number of fraction digits
`maximumFractionDigits`	`0` to `100`	Maximum number of fraction digits
`minimumSignificantDigits`	`1` to `21`	Minimum number of significant digits
`maximumSignificantDigits`	`1` to `21`	Maximum number of significant digits

Rounding options:

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

Locale options:

Property	Possible values	Description
`localeMatcher`	`'best fit'` (default), `'lookup'`	Locale matching algorithm
`numberingSystem`	`'latn'`, `'arab'`, `'hans'`, `'deva'`, `'thai'`, etc.	Numbering system to use

For complete reference, see MDN: Intl.NumberFormat.

This option affects only the displayed output in the cell renderer. It has no effect on the numeric cell editor. In the source data, numeric values are stored as JavaScript numbers.

Deprecated options:

The pattern and culture properties (numbro.js-based formatting) are deprecated and will be removed in the next major release. Migrate to the Intl.NumberFormat API shown above.

Deprecated property	Possible values	Replacement
`pattern`	All `numbro.js` number formats	Use `Intl.NumberFormat` options (see tables above)
`culture`	All `numbro.js` currency formats	Use the `locale` option

Migration example:

1
// Before (deprecated)
2
numericFormat: {
3
  pattern: '0,0.00 $',
4
  culture: 'en-US'
5
}
6

7
// After (recommended)
8
locale: 'en-US',
9
numericFormat: {
10
  style: 'currency',
11
  currency: 'USD',
12
  minimumFractionDigits: 2
13
}

Default: undefined
Category: Core
Since: 0.35.0
Example

1
columns: [
2
  {
3
    type: 'numeric',
4
    locale: 'en-US',
5
    numericFormat: {
6
      style: 'currency',
7
      currency: 'USD',
8
    }
9
  }
10
],

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.

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

Default: true
Category: Core
Example

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

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

1
// on a mouse click outside of the grid, clear the current selection
2
outsideClickDeselects: true,
3

4
// on a mouse click outside of the grid, keep the current selection
5
outsideClickDeselects: false,
6

7
// take the click event target and return `false`
8
outsideClickDeselects(event) {
9
  return false;
10
}
11

12
// take the click event target and return `true`
13
outsideClickDeselects(event) {
14
  return false;
15
}

pagination

Source code

options.pagination : boolean

The pagination option configures the Pagination plugin.

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

Setting	Description
`false`	Disable the `Pagination` plugin
`true`	Enable the `Pagination` plugin

pagination: Additional options

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

Option	Possible settings	Description
`pageSize`	A number or `auto` (default: `10`)	Sets the number of rows displayed per page. If `'auto'` is set, the page size will be calculated to match all rows to the currently set table’s viewport height
`pageSizeList`	An array (default: `['auto', 5, 10, 20, 50, 100]`)	Defines the selectable values for page size in the UI
`initialPage`	A number (default: `1`)	Specifies which page to display on initial load
`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.

Default: undefined
Category: Pagination
Since: 16.1.0
Example

1
// enable the `Pagination` plugin
2
pagination: true,

parsePastedValue

Source code

options.parsePastedValue : boolean

The parsePastedValue option determines how pasted content is written to cells when the user pastes from the clipboard into Handsontable (e.g. from another Handsontable instance or between cells in the same table). It does not affect how other applications read or process the clipboard.

When set to false, pasted content is written as plain strings. Non-scalar values (e.g. objects) are coerced to string, so an object becomes "[object Object]".

When set to true, pasted text is parsed so that JSON-like (or other supported) values are converted to JavaScript values and written to the data source. This allows copying and pasting more sophisticated JavaScript structures (e.g. objects, arrays) between cells and between Handsontable instances. Cells then store the resulting object (e.g. { id: 1, value: 'A1' }). Schema validation is relaxed so object-based values can be pasted into cells that would normally expect a scalar.

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

Setting	Description
`false` (default)	Write pasted content as plain strings
`true`	Parse pasted text and write JavaScript values

Default: false
Category: CopyPaste
Since: 17.0.0
Example

1
// write pasted content as strings (objects become "[object Object]")
2
parsePastedValue: false,

Example

1
// parse pasted text so cells receive JavaScript objects when pasted content is object-like
2
parsePastedValue: true,

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)

placeholderCellClassName

Default: undefined
Category: Core
Example

1
// display 'Empty cell' text
2
// in every empty cell of the entire grid
3
placeholder: 'Empty cell',
4

5
// or
6
columns: [
7
  {
8
    data: 'date',
9
    dateFormat: 'DD/MM/YYYY',
10
    // display 'Empty date cell' text
11
    // in every empty cell of the `date` column
12
    placeholder: 'Empty date cell'
13
  }
14
],

placeholderCellClassName

Source code

options.placeholderCellClassName : string

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

Cell validator
placeholder
currentRowClassName
currentHeaderClassName
activeHeaderClassName
currentColClassName
readOnlyCellClassName
commentedCellClassName
noWordWrapClassName
TableClassName
className

Default: “htPlaceholder”
Category: Core
Example

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

preventOverflow

Source code

options.preventOverflow : string | boolean

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

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

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

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

Default: false
Category: Core
Example

1
// prevent horizontal overflowing
2
preventOverflow: 'horizontal',

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.

Default: false
Category: Core
Example

1
// make the entire grid read-only
2
const configurationOptions = {
3
  columnSorting: true,
4
};
5

6
// make the third column read-only
7
const configurationOptions = {
8
  columns: [
9
    {},
10
    {},
11
    {
12
      readOnly: true,
13
    },
14
  ],
15
};
16

17
// make a specific cell read-only
18
const configurationOptions = {
19
  cell: [
20
    {
21
      row: 0,
22
      col: 0,
23
      readOnly: true,
24
    },
25
};

readOnlyCellClassName

Source code

options.readOnlyCellClassName : string

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

currentRowClassName
currentColClassName
currentHeaderClassName
activeHeaderClassName
invalidCellClassName
placeholderCellClassName
commentedCellClassName
noWordWrapClassName
readOnlyCellClassName
TableClassName

Default: “htDimmed”
Category: Core
Example

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

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.

Column virtualization

Default: false
Category: Core
Since: 14.1.0
Example

1
// disable column virtualization
2
renderAllColumns: true,

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.

Row virtualization

Default: false
Category: Core
Example

1
// disable row virtualization
2
renderAllRows: true,

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:

A custom renderer function
One of the following cell renderer aliases:

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

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

Default: undefined
Category: Core
Example

1
// use the `numeric` renderer for each cell of the entire grid
2
renderer: `'numeric'`,
3

4
// add a custom renderer function
5
renderer(hotInstance, td, row, column, prop, value, cellProperties) {
6
  // your custom renderer's logic
7
  ...
8
}
9

10
// apply the `renderer` option to individual columns
11
columns: [
12
  {
13
    // use the `autocomplete` renderer for each cell of this column
14
    renderer: 'autocomplete'
15
  },
16
  {
17
    // use the `myCustomRenderer` renderer for each cell of this column
18
    renderer: 'myCustomRenderer'
19
  }
20
]

rowHeaders

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

Row header

Default: undefined
Category: Core
Example

1
// enable the default row headers
2
rowHeaders: true,
3

4
// set your own row headers
5
rowHeaders: ['One', 'Two', 'Three'],
6

7
// set your own row headers, using a function
8
rowHeaders: function(visualRowIndex) {
9
  return `${visualRowIndex}: AB`;
10
},

rowHeaderWidth

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

1
// set the same width for every row header
2
rowHeaderWidth: 25,
3

4
// set different widths for individual row headers
5
rowHeaderWidth: [25, 30, 55],

rowHeights

Source code

The rowHeights option sets rows’ heights, in pixels.

In the rendering process, the default row height is classic: 26px, main: 29px, horizon: 37px 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).

Row height

Default: undefined
Category: Core
Example

1
// set every row's height to 100px
2
rowHeights: 100,
3

4
// set every row's height to 100px
5
rowHeights: '100px',
6

7
// set the first (by visual index) row's height to 100
8
// set the second (by visual index) row's height to 120
9
// set the third (by visual index) row's height to `undefined`
10
// set any other row's height to the default height value
11
rowHeights: [100, 120, undefined],
12

13
// set each row's height individually, using a function
14
rowHeights(visualRowIndex) {
15
  return visualRowIndex * 10;
16
},

sanitizer

Source code

options.sanitizer : function

The sanitizer option configures the function used to sanitize HTML before it is written to the DOM. Whenever Handsontable sets HTML (e.g. cell content, headers, context menu labels, dialog content, paste from clipboard), it can pass the string through this function first. Sanitization is important when content comes from users or external sources to prevent XSS (e.g. script injection, event handlers). If no sanitizer is set, HTML is applied as-is. Set a sanitizer when you need to allow rich content while stripping or neutralizing dangerous markup.

The function receives the raw HTML string and an optional second argument (source) indicating where the content is used (e.g. 'innerHTML', 'CopyPaste.paste'), so you can apply different rules per source. It must return a string that is safe to assign to innerHTML.

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

Default: undefined
Category: Core
Since: 17.0.0
Example

1
// Allowlist-based sanitization based on the DOMPurify library
2
import DOMPurify from 'dompurify';
3

4
sanitizer: (content, source) {
5
  if (source === 'CopyPaste.paste') {
6
    return DOMPurify.sanitize(content, {
7
      ADD_TAGS: ['meta'],
8
      ADD_ATTR: ['content'],
9
      FORCE_BODY: true,
10
    });
11
  }
12

13
  return DOMPurify.sanitize(content);
14
},

Example

1
// Maximum safety: strip all tags and escape output (no rich HTML)
2
sanitizer: (content, source) => {
3
  const tpl = document.createElement('template');
4

5
  tpl.innerHTML = content;
6

7
  const text = tpl.content.textContent ?? '';
8

9
  return text
10
    .replace(/&/g, '&amp;')
11
    .replace(/</g, '&lt;')
12
    .replace(/>/g, '&gt;')
13
    .replace(/"/g, '&quot;')
14
    .replace(/'/g, '&#39;');
15
},

Example

1
// Trusted Types: wrap sanitization in a policy so the sink accepts the result.
2
// Add the policy name to the CSP trusted-types directive (e.g. trusted-types default handsontable).
3
const policy = window.trustedTypes?.createPolicy('handsontable', {
4
  createHTML: (input) => DOMPurify.sanitize(input),
5
});
6

7
sanitizer: (content, source) =>
8
  policy ? policy.createHTML(content) : DOMPurify.sanitize(content),

search

Source code

options.search : boolean | object

The search option enables and configures the Search plugin.

Setting	Description
`false` (default)	Disable the `Search` plugin
`true`	Enable the `Search` plugin with the default configuration
An object	Enable the `Search` plugin and apply a custom configuration

When set to an object, the following properties are supported:

Property	Type	Default	Description
`searchResultClass`	`string`	`'htSearchResult'`	CSS class name applied to every cell where `isSearchResult === true`.
`queryMethod`	`Function`	Case-insensitive substring match	Tests whether the query string matches a cell value. Signature: `(queryStr: string, value: string\|number\|null, cellProperties: object) => boolean`.
`callback`	`Function`	Sets `isSearchResult` on cell metadata	Called for every cell after each test. Signature: `(instance: Handsontable, row: number, col: number, data: string\|number\|null, testResult: boolean) => void`.

Default queryMethod behavior: case-insensitive, locale-aware substring match using toLocaleLowerCase() with cellProperties.locale.

Default callback behavior: sets instance.getCellMeta(row, col).isSearchResult = testResult on every cell.

Per-cell overrides: queryMethod and callback can also be set on individual cells, columns, or rows using the cascading configuration model. A cell-level search.queryMethod or search.callback takes precedence over the plugin-level setting for that cell. searchResultClass does not support per-cell overrides.

Default: false
Category: Search
Example

1
// Enable with the default configuration
2
search: true,
3

4
// Enable with a custom configuration
5
search: {
6
  // Apply a custom CSS class to matching cells instead of 'htSearchResult'
7
  searchResultClass: 'customClass',
8
  // Replace the built-in substring match with exact matching
9
  queryMethod(queryStr, value, cellProperties) {
10
    if (!queryStr || queryStr.length === 0) return false;
11
    if (value === undefined || value === null) return false;
12

13
    return queryStr.toString() === value.toString();
14
  },
15
  // Count results while preserving default highlighting
16
  callback(instance, row, col, data, testResult) {
17
    // Preserve the default isSearchResult flag so highlighting still works
18
    instance.getCellMeta(row, col).isSearchResult = testResult;
19

20
    if (testResult) {
21
      // Custom logic: e.g., increment a result counter
22
    }
23
  }
24
},
25

26
// Override queryMethod for a specific column only (per-cell via cascading config)
27
columns: [
28
  {},
29
  {
30
    search: {
31
      queryMethod(queryStr, value) {
32
        return queryStr.toString() === value.toString(); // exact match for column 1
33
      }
34
    }
35
  }
36
],

searchInput

Source code

options.searchInput : boolean

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

Default: true
Category: Core
Since: 17.0.0
Example

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

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.

Selection: Selecting ranges

Default: “multiple”
Category: Core
Example

1
// you can only select one cell at at a time
2
selectionMode: 'single',
3

4
// you can select one range of cells at a time
5
selectionMode: 'range',
6

7
// you can select multiple ranges of cells at a time
8
selectionMode: 'multiple',

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

Select cell type

Default: undefined
Category: Core
Example

1
columns: [
2
  {
3
    // set the `type` of each cell in this column to `select`
4
    type: 'select',
5
    // set the first option's value and label to `A`
6
    // set the second option's value and label to `B`
7
    // set the third option's value and label to `C`
8
    selectOptions: ['A', 'B', 'C'],
9
  },
10
  {
11
    // set the `type` of each cell in this column to `select`
12
    type: 'select',
13
    selectOptions: {
14
      // set the first option's value to `value1` and label to `Label 1`
15
      value1: 'Label 1',
16
      // set the second option's value to `value2` and label to `Label 2`
17
      value2: 'Label 2',
18
      // set the third option's value to `value3` and label to `Label 3`
19
      value3: 'Label 3',
20
    },
21
  },
22
  {
23
    // set the `type` of each cell in this column to `select`
24
    type: 'select',
25
    // set `selectOption` to a function that returns available options as an object
26
    selectOptions(visualRow, visualColumn, prop) {
27
      return {
28
        value1: 'Label 1',
29
        value2: 'Label 2',
30
        value3: 'Label 3',
31
      };
32
  },
33
],

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. This option is not supported for the global table level settings.

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

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

Configuration options: Setting column options

Default: false
Category: Core
Example

1
columns: [
2
  {
3
    // disable pasting data into this column
4
    skipColumnOnPaste: true
5
  }
6
],

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. This option is not supported for the global table level settings.

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

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

Configuration options: Setting row options

Default: false
Category: Core
Example

1
cells(row, column) {
2
 const cellProperties = {};
3

4
 // disable pasting data into row 1
5
 if (row === 1) {
6
   cellProperties.skipRowOnPaste = true;
7
 }
8

9
 return cellProperties;
10
}

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

Default: true
Category: Core
Example

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

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.

Default: undefined
Category: Core
Example

1
// set `source` to an array of string values
2
columns: [{
3
  // set the `type` of each cell in this column to `autocomplete`
4
  type: 'autocomplete',
5
  // set options available in every `autocomplete` cell of this column
6
  source: ['A', 'B', 'C', 'D']
7
}],
8

9
// set `source` to an array of objects with `key` and `value` properties
10
columns: [{
11
  // set the `type` of each cell in this column to `autocomplete`
12
  type: 'autocomplete',
13
  // set options available in every `autocomplete` cell of this column
14
  source: [{
15
    key: 'A',
16
    value: 'Label A'
17
  }, {
18
    key: 'B',
19
    value: 'Label B'
20
  }]
21
}],
22

23
// set `source` to a function
24
columns: [{
25
  // set the `type` of each cell in this column to `autocomplete`
26
  type: 'autocomplete',
27
  // for every `autocomplete` cell in this column, fetch data from an external source
28
  source(query, callback) {
29
    fetch('https://example.com/query?q=' + query, function(response) {
30
      callback(response.items);
31
    })
32
  }
33
}],

sourceDataValidator

Source code

options.sourceDataValidator : function

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

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

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

Default: undefined
Category: Core
Since: 17.0.0
Example

1
sourceDataWarningMessage: 'The source data is invalid.',
2
sourceDataValidator: (value, cellMeta) => {
3
  if (cellMeta.allowEmpty && value == null) {
4
    return true;
5
  }
6

7
  if (typeof value === 'string') {
8
    return true;
9
  }
10

11
  return false;
12
}

sourceDataWarningMessage

Source code

options.sourceDataWarningMessage : string

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

Default: undefined
Category: Core
Since: 17.0.0
Example

1
sourceDataWarningMessage: 'The source data is invalid.',

sourceSortFunction

Source code

options.sourceSortFunction : function

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

Default: undefined
Category: Core
Since: 17.0.0
Example

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

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 and only when data is not provided.

Default: 5
Category: Core
Example

1
// start with 15 empty columns
2
startCols: 15,

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 and only when data is not provided.

Default: 5
Category: Core
Example

1
// start with 15 empty rows
2
startRows: 15,

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

Column width: Column stretching

Default: “none”
Category: Core
Example

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

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

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

Default: undefined
Category: Core
Example

1
columns: [
2
  {
3
  // set the `type` of each cell in this column to `autocomplete`
4
  type: 'autocomplete',
5
  // set options available in every `autocomplete` cell of this column
6
  source: ['A', 'B', 'C'],
7
  // values entered must match `A`, `B`, or `C`
8
  strict: true
9
  },
10
],

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

currentRowClassName
currentColClassName
currentHeaderClassName
activeHeaderClassName
invalidCellClassName
placeholderCellClassName
readOnlyCellClassName
noWordWrapClassName
commentedCellClassName
className

Default: undefined
Category: Core
Example

1
// add a `your-class-name` CSS class name
2
// to every Handsontable instance inside the `container` element
3
tableClassName: 'your-class-name',
4

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

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

1
// on pressing Tab, move selection 2 rows down and 2 columns right
2
// on pressing Shift+Tab, move selection 2 rows up and 2 columns left
3
tabMoves: {row: 2, col: 2},
4

5
// the same setting, as a function
6
// `event` is a DOM Event object received on pressing Tab
7
// you can use it to check whether the user pressed Tab or Shift+Tab
8
tabMoves(event) {
9
  return {row: 2, col: 2};
10
},

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

1
// you can't navigate row and column headers using <kbd>Tab</kbd> or <kbd>Shift</kbd>+<kbd>Tab</kbd> keyboard shortcuts
2
tabNavigation: false,
3

4
// default behavior: you can navigate row and column headers using <kbd>Tab</kbd> or <kbd>Shift</kbd>+<kbd>Tab</kbd> keyboard shortcuts
5
tabNavigation: true,

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

1
columns: [
2
  {
3
    // truncate text content with an ellipsis
4
    textEllipsis: true,
5
  },
6
  {
7
    // don't truncate text content with an ellipsis
8
    textEllipsis: false,
9
  }
10
],

theme

Source code

options.theme : ThemeBuilder | string | undefined

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

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

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

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

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

Themes
themeName

Default: undefined
Category: Core
Since: 17.0.0
Example

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

Example

1
// Pass a plain theme config object
2
import { horizonTheme } from 'handsontable/themes';
3

4
const hot = new Handsontable(container, {
5
  theme: horizonTheme,
6
});

Example

1
// Pass a ThemeBuilder object (for customization before initialization)
2
import { horizonTheme, registerTheme } from 'handsontable/themes';
3

4
const theme = registerTheme(horizonTheme)
5
  .setColorScheme('dark')
6
  .setDensityType('compact')
7
  .params({
8
    tokens: {
9
      fontSize: '14px',
10
      iconSize: 'size_5',
11
      borderColor: ['colors.palette.100', 'colors.palette.800'],
12
    },
13
  });
14

15
const hot = new Handsontable(container, {
16
  theme,
17
});

themeName

Source code

options.themeName : string | undefined

The themeName option allows enabling a theme by that name.

Themes

Default: undefined
Category: Core
Since: 15.0.0
Example

1
themeName: 'ht-theme-name',

timeFormat

Source code

options.timeFormat : string | object

Configures the time format for time cells. Accepts either a string (legacy, for time cells) or an object of Intl.DateTimeFormat options (for intl-time cells).

Object form (Intl.DateTimeFormat options):

The object form is supported only when the cell type is intl-time. The locale is controlled separately via the locale option.

Style shortcuts:

Property	Possible values	Description
`timeStyle`	`'full'`, `'long'`, `'medium'`, `'short'`	Time formatting style (expands to hour, minute, second, timeZoneName)

Time component options:

Property	Possible values	Description
`hour`	`'numeric'`, `'2-digit'`	Representation of the hour
`minute`	`'numeric'`, `'2-digit'`	Representation of the minute
`second`	`'numeric'`, `'2-digit'`	Representation of the second
`fractionalSecondDigits`	`1`, `2`, `3`	Fraction-of-second digits
`dayPeriod`	`'narrow'`, `'short'`, `'long'`	Day period (e.g. “am”, “noon”)
`timeZoneName`	`'long'`, `'short'`, `'shortOffset'`, `'longOffset'`, `'shortGeneric'`, `'longGeneric'`	Time zone display

Locale and other options:

Property	Possible values	Description
`localeMatcher`	`'best fit'` (default), `'lookup'`	Locale matching algorithm
`timeZone`	IANA time zone (e.g. `'UTC'`, `'America/New_York'`)	Time zone for formatting
`hour12`	`true`, `false`	Use 12-hour vs 24-hour time
`hourCycle`	`'h11'`, `'h12'`, `'h23'`, `'h24'`	Hour cycle
`formatMatcher`	`'basic'`, `'best fit'` (default)	Format matching algorithm

For complete reference, see MDN: Intl.DateTimeFormat.

Deprecated: string form

Passing a string (e.g. 'h:mm:ss a') is deprecated and works only with the time cell type. Migrate to the intl-time cell type and pass an Intl.DateTimeFormat options object.

Migration example:

1
// Before (deprecated)
2
columns: [{
3
  type: 'time',
4
  timeFormat: 'h:mm:ss a'
5
}]
6

7
// After (recommended)
8
columns: [{
9
  type: 'intl-time',
10
  locale: 'en-US',
11
  timeFormat: {
12
    hour: 'numeric',
13
    minute: '2-digit',
14
    second: '2-digit',
15
    hour12: true
16
  }
17
}]

Default: “h:mm:ss a”
Category: Core
Example

1
// intl-time cell type with Intl options
2
columns: [
3
  {
4
    type: 'intl-time',
5
    locale: 'en-US',
6
    timeFormat: {
7
      timeStyle: 'medium'
8
    }
9
  }
10
]

Example

1
// Legacy: time cell type with string format (deprecated)
2
columns: [
3
  {
4
    type: 'time',
5
    timeFormat: 'h:mm:ss a'
6
  }
7
]

title

Source code

options.title : string

The title option configures column header names.

You can set the title option to a string.

Default: undefined
Category: Core
Example

1
columns: [
2
  {
3
    // set the first column header name to `First name`
4
    title: 'First name',
5
    type: 'text',
6
  },
7
  {
8
    // set the second column header name to `Last name`
9
    title: 'Last name',
10
    type: 'text',
11
  }
12
],

trimDropdown

Source code

options.trimDropdown : boolean

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

When set to true (default), the list is trimmed to match the width of the edited cell, which can truncate long option labels. When set to false, the list expands to fit its longest option, which may make the list wider than the cell.

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

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

Default: true
Category: Core
Example

1
columns: [
2
  {
3
    type: 'autocomplete',
4
    // for each cell of this column
5
    // make the `autocomplete` list's width the same as the edited cell's width
6
    trimDropdown: true,
7
  },
8
  {
9
    type: 'dropdown',
10
    // for each cell of this column
11
    // scale the `dropdown` list's width to the list's content
12
    trimDropdown: false,
13
  }
14
],

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

Default: undefined
Category: TrimRows
Example

1
// enable the `TrimRows` plugin
2
trimRows: true,
3

4
// enable the `TrimRows` plugin
5
// at Handsontable's initialization, trim rows 5, 10, and 15
6
trimRows: [5, 10, 15],

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

1
columns: [
2
  {
3
    // don't remove whitespace
4
    // from any cell of this column
5
    trimWhitespace: false
6
  }
7
]

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`
`'intl-date'`	Renderer: `IntlDateRenderer` Editor: `IntlDateEditor` Validator: `IntlDateValidator`
`'dropdown'`	Renderer: `DropdownRenderer` Editor: `DropdownEditor` Validator: `DropdownValidator`
`'handsontable'`	Renderer: `AutocompleteRenderer` Editor: `HandsontableEditor` Validator: -
`'numeric'`	Renderer: `NumericRenderer` Editor: `NumericEditor` Validator: `NumericValidator`
`'password'`	Renderer: `PasswordRenderer` Editor: `PasswordEditor` Validator: -
`'text'`	Renderer: `TextRenderer` Editor: `TextEditor` Validator: -
`'time`’	Renderer: `TimeRenderer` Editor: `TimeEditor` Validator: `TimeValidator`
`'intl-time'`	Renderer: `IntlTimeRenderer` Editor: `IntlTimeEditor` Validator: `IntlTimeValidator`

Default: “text”
Category: Core
Example

1
// set the `numeric` cell type for each cell of the entire grid
2
type: `'numeric'`,
3

4
// apply the `type` option to individual columns
5
columns: [
6
  {
7
    // set the `autocomplete` cell type for each cell of this column
8
    type: 'autocomplete'
9
  },
10
  {
11
    // set the `myCustomCellType` cell type for each cell of this column
12
    type: 'myCustomCellType'
13
  }
14
]

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

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

Default: false
Category: Core
Example

1
columns: [
2
  {
3
    // set the `type` of each cell in this column to `checkbox`
4
    // when unchecked, the cell's value is `false`
5
    // when checked, the cell's value is `true`
6
    type: 'checkbox',
7
  },
8
  {
9
    // set the `type` of each cell in this column to `checkbox`
10
    // when unchecked, the cell's value is `'No'`
11
    // when checked, the cell's value is `'Yes'`
12
    type: 'checkbox',
13
    uncheckedTemplate: 'No'
14
    checkedTemplate: 'Yes',
15
 }
16
],

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.

Undo and redo

Default: undefined
Category: UndoRedo
Example

1
// enable the `UndoRedo` plugin
2
undo: true,

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:

Setting	Description
A string	A cell validator alias
A function	Your custom cell validator function
A regular expression	A regular expression used for cell validation

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

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

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

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

Default: undefined
Category: Core
Example

1
columns: [
2
   {
3
     // use a built-in `numeric` cell validator
4
     validator: 'numeric'
5
   },
6
   {
7
     // validate against a regular expression
8
     validator: /^[0-9]$/
9
   },
10
   {
11
     // add a custom cell validator function
12
     validator(value, callback) {
13
         ...
14
     }
15
   },
16
],

valueFormatter

Source code

options.valueFormatter : function

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

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

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

When to use valueFormatter vs renderer:

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

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

Function signature:

1
valueFormatter(value, cellProperties) => formattedValue

Parameter	Type	Description
`value`	`*`	The raw cell value
`cellProperties`	`object`	The cell’s meta object (see Core#getCellMeta)
Returns	`*`	The formatted value to display

Default: undefined
Category: Core
Since: 17.0.0
Example

1
// add a currency symbol to numeric values
2
valueFormatter(value, cellProperties) {
3
  if (value === null || value === undefined) {
4
    return '';
5
  }
6

7
  return `$${value}`;
8
}
9

10
// format dates in a custom format
11
valueFormatter(value, cellProperties) {
12
  if (!value) {
13
    return '';
14
  }
15

16
  const date = new Date(value);
17

18
  return date.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' });
19
}
20

21
// apply valueFormatter to individual columns
22
columns: [
23
  {
24
    // add "kg" suffix to weight values
25
    valueFormatter(value) {
26
      return value ? `${value} kg` : '';
27
    }
28
  },
29
  {
30
    // format percentages
31
    valueFormatter(value) {
32
      return value !== null ? `${(value * 100).toFixed(1)}%` : '';
33
    }
34
  }
35
]

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

1
// use the `label` property of the value object with a fallback to the value itself
2
valueGetter: (value, row, column, cellMeta) => {
3
  return value?.label ?? value;
4
}

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

valueParser

Source code

options.valueParser : function

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

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

When to use valueParser vs valueFormatter:

Use case	Option
Display: raw value -> shown text	`valueFormatter`
Edit: editor value -> source data	`valueParser`

Function signature:

1
valueParser(value, cellProperties) => sourceValue

Parameter	Type	Description
`value`	`*`	The value produced by the editor
`cellProperties`	`object`	The cell’s meta object (see Core#getCellMeta)
Returns	`*`	The value to store in the source data

Default: undefined
Category: Core
Since: 17.0.0
Example

1
// parse editor string to ISO date (e.g. intl-date: display format => source format)
2
valueParser(value, cellProperties) {
3
  if (value == null || value === '') {
4
    return null;
5
  }
6

7
  const date = new Date(value);
8

9
  return Number.isNaN(date.getTime()) ? value : date.toISOString().slice(0, 10);
10
}
11

12
// parse formatted number string to number
13
valueParser(value, cellProperties) {
14
  if (value == null || value === '') {
15
    return null;
16
  }
17

18
  const num = Number(value.replace(/[^\d.-]/g, ''));
19

20
  return Number.isNaN(num) ? value : num;
21
}
22

23
// apply valueParser per column
24
columns: [
25
  { data: 'date', valueParser: (value) => value ? new Date(value).toISOString().slice(0, 10) : null },
26
  { data: 'amount', valueParser: (value) => value != null ? Number(value) : null }
27
]

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

1
// Modify the value of a cell before it is saved
2
valueSetter: (value, row, column, cellMeta) => {
3
  return { id: value?.id ?? value, value: `${value?.value ?? value} at ${row}, ${column}` }
4
},

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.

Performance: Define the number of pre-rendered rows and columns

Default: ‘auto’
Category: Core
Example

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

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.

Default: 0
Category: Core
Since: 1.14.7
Example

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

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.

Default: ‘auto’
Category: Core
Example

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

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.

Default: 0
Category: Core
Since: 1.14.7
Example

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

visibleRows

Source code

options.visibleRows : number

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

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

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

Default: 10
Category: Core
Example

1
columns: [
2
  {
3
    type: 'autocomplete',
4
    // set the `autocomplete` list's height to 15 options
5
    // for each cell of this column
6
    visibleRows: 15,
7
  },
8
  {
9
    type: 'dropdown',
10
    // set the `dropdown` list's height to 5 options
11
    // for each cell of this column
12
    visibleRows: 5,
13
  },
14
  {
15
    type: 'multiselect',
16
    // set the `multiSelect` list's height to 5 options
17
    // for each cell of this column
18
    visibleRows: 5,
19
  }
20
],

width

Source code

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

The width option configures the width of your grid.

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

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

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

Grid size

Default: undefined
Category: Core
Example

1
// set the grid's width to 500px
2
width: 500,
3

4
// set the grid's width to 75vw
5
width: '75vw',
6

7
// let the grid follow its parent container's width
8
width: 'auto',
9

10
// set the grid's width to 500px, using a function
11
width() {
12
  return 500;
13
},

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.

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

noWordWrapClassName

Default: true
Category: Core
Example

1
// set column width for every column of the entire grid
2
colWidths: 100,
3

4
columns: [
5
  {
6
    // don't wrap content in this column
7
    wordWrap: false,
8
  },
9
  {
10
    // if content exceeds this column's width, wrap the content
11
    wordWrap: true,
12
  }
13
],

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. The function receives a visual column index and must return a boolean.

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

Category: Core
Example

1
// overwrite the built-in `isEmptyCol` method
2
isEmptyCol(visualColumnIndex) {
3
   // your custom method
4
   ...
5
},

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. The function receives a visual row index and must return a boolean.

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

Category: Core
Example

1
// overwrite the built-in `isEmptyRow` method
2
isEmptyRow(visualRowIndex) {
3
   // your custom method
4
   ...
5
},

Param	Type	Description
row	`number`	Visual row index.

Configuration options

Description

Members

activeHeaderClassName

allowEmpty

allowHtml

allowInsertColumn

allowInsertRow

allowInvalid

allowRemoveColumn

allowRemoveRow

ariaTags

autoColumnSize

autoRowSize

autoWrapCol

autoWrapRow

bindRowsWithHeaders

cell

cells

checkedTemplate

className

colHeaders

collapsibleColumns

columnHeaderHeight

columns

columnSorting

columnSummary

colWidths

commentedCellClassName

comments

contextMenu

copyable

copyPaste

copyPaste: Additional options

correctFormat Deprecated

currentColClassName

currentHeaderClassName

currentRowClassName

customBorders

data

dataDotNotation

dataProvider

dataSchema

dateFormat

datePickerConfig Deprecated

defaultDate

dialog

dialog: Additional options

disableVisualSelection

dragToScroll

dropdownMenu

editor

emptyDataState

enterBeginsEditing

enterCommits

enterMoves

exportFile

fillHandle

filter

filteringCaseSensitive

filters

filterSelectedItems

fixedColumnsStart

fixedRowsBottom

fixedRowsTop

formulas

fragmentSelection

headerClassName

height

How 'auto' differs from leaving height unset

hiddenColumns

hiddenRows

imeFastEdit

initialState

injectCoreCss

invalidCellClassName

label

language

layoutDirection

licenseKey

How `'auto'` differs from leaving `height` unset