---
title: Options
metaTitle: Options - API Reference - Handsontable Documentation
permalink: /9.0/api/options
canonicalUrl: /api/options
editLink: false
---
# Options
[[toc]]
## Description
Handsontable provides many options to choose from. They come either from the [Core](@/api/core.md) features or [plugins hooks](@/api/pluginHooks.md).
You can pass options in an object iteral notation (a comma-separated list of name-value pairs wrapped in curly braces) as a second argument of the Handsontable constructor.
In the further documentation, and in Guides, we prefer calling this object a `Settings` object or `configuration` object.
```js
const container = document.getElementById('example');
const hot = new Handsontable(container, {
data: myArray,
width: 400,
height: 300
});
```
## Applying options to different elements of the grid
Options can set for many different parts of the data grid:
- The entire grid
- A column or range of columns
- A row or range of rows
- A cell or range of cells
Options use the cascading configuration to make that possible.
Take a look at the following example:
```js
const container = document.getElementById('example');
const hot = new Handsontable(container, {
readOnly: true,
columns: [
{ readOnly: false },
{},
{},
],
cells: function(row, col, prop) {
var cellProperties = {};
if (row === 0 && col === 0) {
cellProperties.readOnly = true;
}
return cellProperties;
}
});
```
In the above example we first set the `read-only` option for the entire grid. Then we make two exceptions of this rule:
- We exclude the first column by passing `readOnly: false`, which in result makes it editable.
- We exclude the cell in the top left corner, just like we did it with the first column.
To learn more about how to use cascading settings go to the [Setting Options](@/guides/getting-started/setting-options.md) page.
::: tip
In order for the data separation to work properly, make sure that each instance of Handsontable has a unique `id`.
:::
## Members
### activeHeaderClassName
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1067
:::
_options.activeHeaderClassName : string_
Class name for all active headers in selections. The header will be marked with this class name
only when a whole column or row will be selected.
**Default**: "ht__active_highlight"
**Category**: [Core](@/api/core.md)
**Since**: 0.38.2
**Example**
```js
// this will add a 'ht__active_highlight' class name to appropriate table headers.
activeHeaderClassName: 'ht__active_highlight',
```
### allowEmpty
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1264
:::
_options.allowEmpty : boolean_
If set to `true`, Handsontable will accept values that are empty (`null`, `undefined` or `''`). If set
to `false`, Handsontable will *not* accept the empty values and mark cell as invalid.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
// allow empty values for all cells (whole table)
allowEmpty: true,
// or
columns: [
{
data: 'date',
dateFormat: 'DD/MM/YYYY',
// allow empty values only for the 'date' column
allowEmpty: true
}
],
```
### allowHtml
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2559
:::
_options.allowHtml : boolean_
If set to `true`, data defined in `source` of the autocomplete or dropdown cell will be treated as HTML.
__Warning:__ Enabling this option can cause serious XSS vulnerabilities.
__Note__, this option only works for [autocomplete-typed](@/guides/cell-types/autocomplete-cell-type.md) cells.
**Default**: false
**Category**: [Core](@/api/core.md)
**Example**
```js
columns: [{
type: 'autocomplete',
// use HTML in the source list
allowHtml: true,
source: ['foo', 'bar']
}],
```
### allowInsertColumn
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L697
:::
_options.allowInsertColumn : boolean_
If set to `false`, there won't be an option to insert new columns in the Context Menu.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
// hide "Insert column left" and "Insert column right" options from the Context Menu
allowInsertColumn: false,
```
### allowInsertRow
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L681
:::
_options.allowInsertRow : boolean_
If set to `false`, there won't be an option to insert new rows in the Context Menu.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
// hide "Insert row above" and "Insert row below" options from the Context Menu
allowInsertRow: false,
```
### allowInvalid
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1237
:::
_options.allowInvalid : boolean_
If set to `true`, Handsontable will accept values that were marked as invalid by the cell `validator`. It will
result with *invalid* cells being treated as *valid* (will save the *invalid* value into the Handsontable data source).
If set to `false`, Handsontable will *not* accept the invalid values and won't allow the user to close the editor.
This option will be particularly useful when used with the Autocomplete's `strict` mode.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
// don't save the invalid values
allowInvalid: false,
```
### allowRemoveColumn
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L729
:::
_options.allowRemoveColumn : boolean_
If set to `false`, there won't be an option to remove columns in the Context Menu.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
// hide "Remove column" option from the Context Menu
allowRemoveColumn: false,
```
### allowRemoveRow
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L713
:::
_options.allowRemoveRow : boolean_
If set to `false`, there won't be an option to remove rows in the Context Menu.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
// hide "Remove row" option from the Context Menu
allowRemoveRow: false,
```
### autoColumnSize
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2417
:::
_options.autoColumnSize : object | boolean_
Enables or disables the [AutoColumnSize](@/api/autoColumnSize.md) plugin. Default value `undefined`
is an equivalent of `true`, sets `syncLimit` to 50.
Disabling this plugin can increase performance, as no size-related calculations would be done.
To disable plugin it's necessary to set `false`.
Column width calculations are divided into sync and async part. Each of those parts has their own advantages and
disadvantages. Synchronous calculations are faster but they block the browser UI, while the slower asynchronous
operations don't block the browser UI.
To configure the sync/async distribution, you can pass an absolute value (number of columns) or a percentage value.
You can also use the `useHeaders` option to take the column headers width into calculation.
Note: Using [Core#colWidths](@/api/core.md#colwidths) option will forcibly disable [AutoColumnSize](@/api/autoColumnSize.md).
**Default**: undefined
**Category**: [AutoColumnSize](@/api/autoColumnSize.md)
**Example**
```js
// as a number (300 columns in sync, rest async)
autoColumnSize: { syncLimit: 300 },
// as a string (percent)
autoColumnSize: { syncLimit: '40%' },
// use headers width while calculating the column width
autoColumnSize: { useHeaders: true },
// defines how many samples for the same length will be caught to calculations
autoColumnSize: { samplingRatio: 10 },
// defines if duplicated samples are allowed in calculations
autoColumnSize: { allowSampleDuplicates: true },
```
### autoRowSize
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2445
:::
_options.autoRowSize : object | boolean_
Enables or disables [AutoRowSize](@/api/autoRowSize.md) plugin. Default value is `undefined`, which has the same effect as `false`
(disabled). Enabling this plugin can decrease performance, as size-related calculations would be performed.
__Note:__ the default `syncLimit` value is set to 500 when the plugin is manually enabled by declaring it as: `autoRowSize: true`.
Row height calculations are divided into sync and async stages. Each of these stages has their own advantages and
disadvantages. Synchronous calculations are faster but they block the browser UI, while the slower asynchronous
operations don't block the browser UI.
To configure the sync/async distribution, you can pass an absolute value (number of rows) or a percentage value.
**Default**: undefined
**Category**: [AutoRowSize](@/api/autoRowSize.md)
**Example**
```js
// as a number (300 rows in sync, rest async)
autoRowSize: {syncLimit: 300},
// as a string (percent)
autoRowSize: {syncLimit: '40%'},
```
### autoWrapCol
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L959
:::
_options.autoWrapCol : boolean_
If `true`, pressing ENTER or down arrow in the last row will move to the first row in the next column.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
// stop ENTER key navigation on the last row
autoWrapCol: false,
```
### autoWrapRow
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L943
:::
_options.autoWrapRow : boolean_
If `true`, pressing TAB or right arrow in the last column will move to first column in next row.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
// stop TAB key navigation on the last column
autoWrapRow: false,
```
### bindRowsWithHeaders
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2631
:::
_options.bindRowsWithHeaders : boolean | string_
Enables the functionality of the [BindRowsWithHeaders](@/api/bindRowsWithHeaders.md) plugin which allows binding the table rows with their headers.
If the plugin is enabled, the table row headers will "stick" to the rows, when they are hidden/moved. Basically,
if at the initialization row 0 has a header titled "A", it will have it no matter what you do with the table.
**Default**: undefined
**Category**: [BindRowsWithHeaders](@/api/bindRowsWithHeaders.md)
**Example**
```js
// keep row data and row headers in sync
bindRowsWithHeaders: true
```
### cell
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L460
:::
_options.cell : Array<Array>_
Any constructor or column option may be overwritten for a particular cell (row/column combination), using `cell`
array passed to the Handsontable constructor.
**Default**: []
**Category**: [Core](@/api/core.md)
**Example**
```js
// make cell with coordinates (0, 0) read only
cell: [
{
row: 0,
col: 0,
readOnly: true
}
],
```
### cells
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L437
:::
_options.cells : function_
Defines the cell properties for given `row`, `col`, `prop` coordinates. Any constructor or column option may be
overwritten for a particular cell (row/column combination) using the `cells` property in the Handsontable constructor.
__Note:__ Parameters `row` and `col` always represent __physical indexes__. Example below show how to execute
operations based on the __visual__ representation of Handsontable.
Possible values of `prop`:
- property name for column's data source object, when dataset is an [array of objects](@/guides/getting-started/binding-to-data.md#array-of-objects)
- the same number as `col`, when dataset is an [array of arrays](@/guides/getting-started/binding-to-data.md#array-of-arrays).
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
cells: function(row, column, prop) {
const cellProperties = { readOnly: false };
const visualRowIndex = this.instance.toVisualRow(row);
const visualColIndex = this.instance.toVisualColumn(column);
if (visualRowIndex === 0 && visualColIndex === 0) {
cellProperties.readOnly = true;
}
return cellProperties;
},
```
### checkedTemplate
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2252
:::
_options.checkedTemplate : boolean | string | number_
Data template for `'checkbox'` type when checkbox is checked.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
checkedTemplate: 'good'
// if a checkbox-typed cell is checked, then getDataAtCell(x, y),
// where x and y are the coordinates of the cell will return 'good'.
```
### className
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1089
:::
_options.className : string | Array<string>_
Class name for the current element.
The interpretation depends on the level on which this option is provided in the [cascading configuration](@/guides/getting-started/setting-options.md).
If `className` is provided on the first (constructor) level, it is the applied to the Handsontable container.
If `className` is provided on the second (`column`) or the third (`cell` or `cells`) level, it is applied to the table cell.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// can be set as a string
className: 'your__class--name',
// or as an array of strings
className: ['first-class-name', 'second-class-name'],
```
### colHeaders
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L288
:::
_options.colHeaders : boolean | Array<string> | function_
Setting `true` or `false` will enable or disable the default column headers (A, B, C).
You can also define an array `['One', 'Two', 'Three', ...]` or a function to define the headers.
If a function is set, then the index of the column is passed as a parameter.
**Default**: null
**Category**: [Core](@/api/core.md)
**Example**
```js
// as a boolean
colHeaders: true,
// as an array
colHeaders: ['A', 'B', 'C'],
// as a function
colHeaders: function(index) {
return index + ': AB';
},
```
### collapsibleColumns
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2664
:::
_options.collapsibleColumns : boolean | Array<object>_
The [CollapsibleColumns](@/api/collapsibleColumns.md) plugin allows collapsing of columns, covered by a header with the `colspan` property
defined.
Clicking the "collapse/expand" button collapses (or expands) all "child" headers except the first one.
Setting the `collapsibleColumns` property to `true` will display a "collapse/expand" button in every
header with a defined colspan` property.
To limit this functionality to a smaller group of headers, define the `collapsibleColumns` property
as an array of objects, as in the example below.
**Default**: undefined
**Category**: [CollapsibleColumns](@/api/collapsibleColumns.md)
**Example**
```js
// enable collapsing for all headers
collapsibleColumns: true,
// or
// enable collapsing for selected headers
collapsibleColumns: [
{row: -4, col: 1, collapsible: true},
{row: -3, col: 5, collapsible: true}
],
```
### columnHeaderHeight
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2908
:::
_options.columnHeaderHeight : number | Array<number>_
Allows setting a custom height of the column headers. You can provide a number or an array of heights, if many
column header levels are defined.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// set shared height for all headers
columnHeaderHeight: 35,
// or
// set height for each header individually
columnHeaderHeight: [35, 20, 55],
// or
// skipped headers will fallback to default value
columnHeaderHeight: [35, undefined, 55],
```
### columns
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L403
:::
_options.columns : Array<object> | function_
Defines the cell properties and data binding for certain columns.
__Note:__ Using this option sets a fixed number of columns (options `startCols`, `minCols`, `maxCols` will be ignored).
See [documentation -> datasources.html](@/guides/getting-started/binding-to-data.md#array-of-objects-with-column-mapping) for examples.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// as an array of objects
// order of the objects in array is representation of physical indexes.
columns: [
{
// column options for the first column
type: 'numeric',
numericFormat: {
pattern: '0,0.00 $'
}
},
{
// column options for the second column
type: 'text',
readOnly: true
}
],
// or as a function, based on physical indexes
columns: function(index) {
return {
type: index > 0 ? 'numeric' : 'text',
readOnly: index < 1
}
}
```
### columnSorting
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1866
:::
_options.columnSorting : boolean | object_
Turns on [Column sorting](@/guides/rows/row-sorting.md). Can be either a boolean (`true` / `false`) or an object with a declared sorting options:
* `initialConfig` - Object with predefined keys:
* `column` - sorted column
* `sortOrder` - order in which column will be sorted
* `'asc'` = ascending
* `'desc'` = descending
* `indicator` - display status for sorting order indicator (an arrow icon in the column header, specifying the sorting order).
* `true` = show sort indicator for sorted columns
* `false` = don't show sort indicator for sorted columns
* `headerAction` - allow to click on the headers to sort
* `true` = turn on possibility to click on the headers to sort
* `false` = turn off possibility to click on the headers to sort
* `sortEmptyCells` - how empty values ([more information here](@/api/metaSchema.md#allowempty)) should be handled
* `true` = the table sorts empty cells
* `false` = the table moves all empty cells to the end of the table
* `compareFunctionFactory` - curry function returning compare function; compare function should work in the same way as function which is handled by native `Array.sort` method); please take a look at below examples for more information.
**Default**: undefined
**Category**: [ColumnSorting](@/api/columnSorting.md)
**Example**
```js
// as boolean
columnSorting: true
// as an object with initial sort config (sort ascending for column at index 1)
columnSorting: {
initialConfig: {
column: 1,
sortOrder: 'asc'
}
}
// as an object which define specific sorting options for all columns
columnSorting: {
sortEmptyCells: true, // true = the table sorts empty cells, false = the table moves all empty cells to the end of the table
indicator: true, // true = shows indicator for all columns, false = don't show indicator for columns
headerAction: false, // true = allow to click on the headers to sort, false = turn off possibility to click on the headers to sort
compareFunctionFactory: function(sortOrder, columnMeta) {
return function(value, nextValue) {
// Some value comparisons which will return -1, 0 or 1...
}
}
}
```
### columnSummary
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2704
:::
_options.columnSummary : Array<object> | function_
Allows making pre-defined calculations on the cell values and display the results within Handsontable.
Possible types:
* `'sum'`
* `'min'`
* `'max'`
* `'count'`
* `'average'`
* `'custom'` - add `customFunction`.
[See the demo for more information](@/guides/columns/column-summary.md).
**Default**: undefined
**Category**: [ColumnSummary](@/api/columnSummary.md)
**Example**
```js
columnSummary: [
{
destinationRow: 4,
destinationColumn: 1,
forceNumeric: true,
reversedRowCoords: true,
suppressDataTypeErrors: false,
readOnly: true,
roundFloat: false,
type: 'custom',
customFunction: function(endpoint) {
return 100;
}
}
],
```
### colWidths
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L323
:::
_options.colWidths : number | Array<number> | string | Array<string> | Array<undefined> | function_
Defines column widths in pixels. Accepts number, string (that will be converted to a number), array of numbers
(if you want to define column width separately for each column) or a function (if you want to set column width
dynamically on each render).
The default width for columns in the rendering process equals 50px.
An `undefined` value is for detection in [Hooks#modifyColWidth](@/api/pluginHooks.md#modifycolwidth) hook if plugin or setting changed the default size.
Note: This option will forcely disable [AutoColumnSize](@/api/autoColumnSize.md) plugin.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// as a number, for each column.
colWidths: 100,
// as a string, for each column.
colWidths: '100px',
// as an array, based on visual indexes. Unspecified columns have a default width.
colWidths: [100, 120, undefined, 90],
// as a function, based on visual indexes.
colWidths: function(index) {
return index * 10;
},
```
### commentedCellClassName
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1403
:::
_options.commentedCellClassName : string_
CSS class name added to the commented cells.
**Default**: "htCommentCell"
**Category**: [Core](@/api/core.md)
**Example**
```js
// set custom class for commented cells
commentedCellClassName: 'has-comment',
```
### comments
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L500
:::
_options.comments : boolean | Array<object>_
If `true`, enables the [Comments](@/api/comments.md) plugin, which enables an option to apply cell comments through the context menu
(configurable with context menu keys `commentsAddEdit`, `commentsRemove`).
To initialize Handsontable with predefined comments, provide cell coordinates and comment text values in a form of
an array.
See [Comments](@/guides/cell-features/comments.md) demo for examples.
**Default**: false
**Category**: [Comments](@/api/comments.md)
**Example**
```js
// enable comments plugin
comments: true,
// or an object with extra predefined plugin config:
comments: {
displayDelay: 1000
}
// or
// enable comments plugin and add predefined comments
const hot = new Handsontable(document.getElementById('example'), {
data: getData(),
comments: true,
cell: [
{ row: 1, col: 1, comment: { value: 'Foo' } },
{ row: 2, col: 2, comment: { value: 'Bar' } }
]
});
```
### contextMenu
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1772
:::
_options.contextMenu : boolean | Array<string> | object_
Defines if the right-click context menu should be enabled. Context menu allows to create new row or column at any
place in the grid among [other features](@/guides/accessories-and-menus/context-menu.md).
Possible values:
* `true` (to enable default options),
* `false` (to disable completely)
* an array of [predefined options](@/guides/accessories-and-menus/context-menu.md#context-menu-with-specific-options),
* an object [with defined structure](@/guides/accessories-and-menus/context-menu.md#context-menu-with-fully-custom-configuration).
If the value is an object, you can also customize the options with:
* `disableSelection` - a `boolean`, if set to true it prevents mouseover from highlighting the item for selection
* `isCommand` - a `boolean`, if set to false it prevents clicks from executing the command and closing the menu.
See [the context menu demo](@/guides/accessories-and-menus/context-menu.md) for examples.
**Default**: undefined
**Category**: [ContextMenu](@/api/contextMenu.md)
**Example**
```js
// as a boolean
contextMenu: true,
// as an array
contextMenu: ['row_above', 'row_below', '---------', 'undo', 'redo'],
// as an object (`name` attribute is required in the custom keys)
contextMenu: {
items: {
"option1": {
name: "option1"
},
"option2": {
name: "option2",
submenu: {
items: [
{
key: "option2:suboption1",
name: "option2:suboption1",
callback: function(key, options) {
...
}
},
...
]
}
}
}
},
```
### copyable
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1595
:::
_options.copyable : boolean_
Makes a cell copyable (pressing CTRL + C on your keyboard moves its value to system clipboard).
__Note:__ this setting is `false` by default for cells with type `password`.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
cells: [
{
cell: 0,
row: 0,
// cell with coordinates (0, 0) can't be copied
copyable: false,
}
],
```
### copyPaste
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1796
:::
_options.copyPaste : object | boolean_
Disables or enables the copy/paste functionality.
**Default**: true
**Category**: [CopyPaste](@/api/copyPaste.md)
**Example**
```js
// disable copy and paste
copyPaste: false,
// enable copy and paste with custom configuration
copyPaste: {
columnsLimit: 25,
rowsLimit: 50,
pasteMode: 'shift_down',
uiContainer: document.body,
},
```
### correctFormat
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2488
:::
_options.correctFormat : boolean_
If `true` then dates will be automatically formatted to match the desired format.
__Note__, this option only works for [date-typed](@/guides/cell-types/date-cell-type.md) cells.
**Default**: false
**Category**: [Core](@/api/core.md)
**Example**
```js
columns: [{
type: 'date',
dateFormat: 'YYYY-MM-DD',
// force selected date format
correctFormat: true
}],
```
### currentColClassName
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1033
:::
_options.currentColClassName : string_
Class name for all visible columns in the current selection.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// This will add a 'currentColumn' class name to appropriate table cells.
currentColClassName: 'currentColumn',
```
### currentHeaderClassName
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1049
:::
_options.currentHeaderClassName : string_
Class name for all visible headers in current selection.
**Default**: "ht__highlight"
**Category**: [Core](@/api/core.md)
**Example**
```js
// This will add a 'ht__highlight' class name to appropriate table headers.
currentHeaderClassName: 'ht__highlight',
```
### currentRowClassName
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1017
:::
_options.currentRowClassName : string_
Class name for all visible rows in the current selection.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// This will add a 'currentRow' class name to appropriate table cells.
currentRowClassName: 'currentRow',
```
### customBorders
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L563
:::
_options.customBorders : boolean | Array<object>_
If `true`, enables the [CustomBorders](@/api/customBorders.md) plugin, which enables an option to apply custom borders through the context
menu (configurable with context menu key `borders`). To initialize Handsontable with predefined custom borders,
provide cell coordinates and border styles in a form of an array.
See [Custom Borders](@/guides/cell-features/formatting-cells.md#custom-cell-borders) demo for examples.
**Default**: false
**Category**: [CustomBorders](@/api/customBorders.md)
**Example**
```js
// enable custom borders
customBorders: true,
// or
// enable custom borders and start with predefined left border
customBorders: [
{
range: {
from: {
row: 1,
col: 1
},
to: {
row: 3,
col: 4
}
},
left: {
width: 2,
color: 'red'
},
right: {},
top: {},
bottom: {}
}
],
// or
customBorders: [
{
row: 2,
col: 2,
left: {
width: 2,
color: 'red'
},
right: {
width: 1,
color: 'green'
},
top: '',
bottom: ''
}
],
```
### data
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L121
:::
_options.data : Array<Array> | Array<object>_
Initial data source that will be bound to the data grid __by reference__ (editing data grid alters the data source).
Can be declared as an array of arrays or an array of objects.
See [Understanding binding as reference](@/guides/getting-started/binding-to-data.md#understand-binding-as-a-reference).
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// as an array of arrays
data: [
['A', 'B', 'C'],
['D', 'E', 'F'],
['G', 'H', 'J']
]
// as an array of objects
data: [
{id: 1, name: 'Ted Right'},
{id: 2, name: 'Frank Honest'},
{id: 3, name: 'Joan Well'},
{id: 4, name: 'Gail Polite'},
{id: 5, name: 'Michael Fair'},
]
```
### dataSchema
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L150
:::
_options.dataSchema : object_
Defines the structure of a new row when data source is an array of objects.
See [data-schema](@/guides/getting-started/binding-to-data.md#array-of-objects-with-custom-data-schema) for more options.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// with data schema we can start with an empty table
data: null,
dataSchema: {id: null, name: {first: null, last: null}, address: null},
colHeaders: ['ID', 'First Name', 'Last Name', 'Address'],
columns: [
{data: 'id'},
{data: 'name.first'},
{data: 'name.last'},
{data: 'address'}
],
startRows: 5,
minSpareRows: 1
```
### dateFormat
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2466
:::
_options.dateFormat : string_
Date validation format.
__Note__, this option only works for [date-typed](@/guides/cell-types/date-cell-type.md) cells.
**Default**: "DD/MM/YYYY"
**Category**: [Core](@/api/core.md)
**Example**
```js
columns: [{
type: 'date',
// localise date format
dateFormat: 'MM/DD/YYYY'
}],
```
### defaultDate
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2511
:::
_options.defaultDate : string_
Definition of default value which will fill the empty cells.
__Note__, this option only works for [date-typed](@/guides/cell-types/date-cell-type.md) cells.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
columns: [
{
type: 'date',
// always set this date for empty cells
defaultDate: '2015-02-02'
}
],
```
### disableVisualSelection
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2143
:::
_options.disableVisualSelection : boolean | string | Array<string>_
Disables visual cells selection.
Possible values:
* `true` - Disables any type of visual selection (current, header and area selection),
* `false` - Enables any type of visual selection. This is default value.
* `'current'` - Disables the selection of a currently selected cell, the area selection is still present.
* `'area'` - Disables the area selection, the currently selected cell selection is still present.
* `'header'` - Disables the headers selection, the currently selected cell selection is still present.
**Default**: false
**Category**: [Core](@/api/core.md)
**Example**
```js
// as a boolean
disableVisualSelection: true,
// as a string ('current', 'area' or 'header')
disableVisualSelection: 'current',
// as an array
disableVisualSelection: ['current', 'area'],
```
### dragToScroll
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2999
:::
_options.dragToScroll : boolean_
Disables or enables the [drag to scroll](@/api/dragToScroll.md) functionality.
**Default**: true
**Category**: [DragToScroll](@/api/dragToScroll.md)
**Example**
```js
// don't scroll the viewport when selection gets to the viewport edge
dragToScroll: false,
```
### dropdownMenu
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2725
:::
_options.dropdownMenu : boolean | object | Array<string>_
This plugin allows adding a configurable dropdown menu to the table's column headers. The dropdown menu acts like
the [Options#contextMenu](@/api/metaSchema.md#contextmenu), but is triggered by clicking the button in the header.
**Default**: undefined
**Category**: [DropdownMenu](@/api/dropdownMenu.md)
**Example**
```js
// enable dropdown menu
dropdownMenu: true,
// or
// enable and configure dropdown menu options
dropdownMenu: ['remove_col', '---------', 'make_read_only', 'alignment']
```
### editor
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1635
:::
_options.editor : string | function | boolean_
Defines the editor for the table/column/cell.
If a string is provided, it may be one of the following predefined values:
* [autocomplete](@/guides/cell-types/autocomplete-cell-type.md)
* [checkbox](@/guides/cell-types/checkbox-cell-type.md)
* [date](@/guides/cell-types/date-cell-type.md)
* [dropdown](@/guides/cell-types/dropdown-cell-type.md)
* [handsontable](@/guides/cell-types/handsontable-cell-type.md)
* mobile
* [password](@/guides/cell-types/password-cell-type.md)
* [select](@/guides/cell-types/select-cell-type.md)
* text.
Or you can [register](@/guides/cell-functions/cell-editor.md#registering-an-editor) the custom editor under specified name and use its name as an alias in your
configuration.
To disable cell editing completely set `editor` property to `false`.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
columns: [
{
// set editor for the first column
editor: 'select'
},
{
// disable editor for the second column
editor: false
}
],
```
### enterBeginsEditing
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L881
:::
_options.enterBeginsEditing : boolean_
If `true`, ENTER begins editing mode (like in Google Docs). If `false`, ENTER moves to next
row (like Excel) and adds a new row if necessary. TAB adds new column if necessary.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
enterBeginsEditing: false,
```
### enterMoves
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L904
:::
_options.enterMoves : object | function_
Defines the cursor movement after ENTER was pressed (SHIFT + ENTER uses a negative vector). Can
be an object or a function that returns an object. The event argument passed to the function is a DOM Event object
received after the ENTER key has been pressed. This event object can be used to check whether user pressed
ENTER or SHIFT + ENTER.
**Default**: {col: 0, row: 1}
**Category**: [Core](@/api/core.md)
**Example**
```js
// move selection diagonal by 1 cell in x and y axis
enterMoves: {col: 1, row: 1},
// or as a function
enterMoves: function(event) {
return {col: 1, row: 1};
},
```
### fillHandle
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L793
:::
_options.fillHandle : boolean | string | object_
Enables the fill handle (drag-down and copy-down) functionality, which shows a small rectangle in bottom
right corner of the selected area, that let's you expand values to the adjacent cells.
Setting to `true` enables the fillHandle plugin. Possible values: `true` (to enable in all directions),
`'vertical'` or `'horizontal'` (to enable in one direction), `false` (to disable completely), an object with
options: `autoInsertRow`, `direction`.
If `autoInsertRow` option is `true`, fill-handler will create new rows till it reaches the last row.
It is enabled by default.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
// enable plugin in all directions and with autoInsertRow as true
fillHandle: true,
// or
// enable plugin in vertical direction and with autoInsertRow as true
fillHandle: 'vertical',
// or
fillHandle: {
// enable plugin in both directions and with autoInsertRow as false
autoInsertRow: false,
},
// or
fillHandle: {
// enable plugin in vertical direction and with autoInsertRow as false
autoInsertRow: false,
direction: 'vertical'
},
```
### filter
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2959
:::
_options.filter : boolean_
If defined as `true`, when the user types into the input area the Autocomplete's suggestion list is updated to only
include those choices starting with what has been typed; if defined as `false` all suggestions remain shown, with
those matching what has been typed marked in bold.
__Note__, this option only works for [autocomplete-typed](@/guides/cell-types/autocomplete-cell-type.md) cells.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
columns: [
{
type: 'autocomplete',
source: [ ... ],
// don't hide options that don't match search query
filter: false
}
],
```
### filteringCaseSensitive
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2983
:::
_options.filteringCaseSensitive : boolean_
If defined as `true`, filtering in the Autocomplete Editor will be case-sensitive.
__Note__, this option only works for [autocomplete-typed](@/guides/cell-types/autocomplete-cell-type.md) cells.
**Default**: false
**Category**: [Core](@/api/core.md)
**Example**
```js
columns: [
{
type: 'autocomplete',
source: [ ... ],
// match case while searching autocomplete options
filteringCaseSensitive: true
}
],
```
### filters
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2741
:::
_options.filters : boolean_
The [Filters](@/api/filters.md) plugin allows filtering the table data either by the built-in component or with the API.
**Default**: undefined
**Category**: [Filters](@/api/filters.md)
**Example**
```js
// enable filters
filters: true,
```
### fixedColumnsLeft
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L843
:::
_options.fixedColumnsLeft : number_
Allows to specify the number of fixed (or *frozen*) columns on the left of the table.
**Default**: 0
**Category**: [Core](@/api/core.md)
**Example**
```js
// freeze first 3 columns of the table.
fixedColumnsLeft: 3,
```
### fixedRowsBottom
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L827
:::
_options.fixedRowsBottom : number_
Allows to specify the number of fixed (or *frozen*) rows at the bottom of the table.
**Default**: 0
**Category**: [Core](@/api/core.md)
**Example**
```js
// freeze the last 3 rows of the table.
fixedRowsBottom: 3,
```
### fixedRowsTop
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L811
:::
_options.fixedRowsTop : number_
Allows to specify the number of fixed (or *frozen*) rows at the top of the table.
**Default**: 0
**Category**: [Core](@/api/core.md)
**Example**
```js
// freeze the first 3 rows of the table.
fixedRowsTop: 3,
```
### formulas
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2765
:::
_options.formulas : boolean | object_
The [Formulas](@/api/formulas.md) plugin allows Handsontable to process formula expressions defined in the provided data.
**Default**: undefined
**Category**: [Formulas](@/api/formulas.md)
**Example**
```js
// in Handsontable's `formulas` configuration option, add the `HyperFormula` class
formulas: {
engine: HyperFormula,
// the `Formulas` plugin configuration
}
// or, add a HyperFormula instance
const hyperformulaInstance = HyperFormula.buildEmpty({})
formulas: {
engine: hyperformulaInstance,
// the `Formulas` plugin configuration
}
// use the same HyperFormula instance in multiple Handsontable instances
// a Handsontable instance `hot1`
formulas: {
engine: HyperFormula,
// the `Formulas` plugin configuration
}
// a Handsontable instance `hot2`
formulas: {
engine: hot1.getPlugin('formulas').engine,
// the `Formulas` plugin configuration
}
```
### fragmentSelection
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1425
:::
_options.fragmentSelection : boolean | string_
If set to `true`, it enables the browser's native selection of a fragment of the text within a single cell, between
adjacent cells or in a whole table. If set to `'cell'`, it enables the possibility of selecting a fragment of the
text within a single cell's body.
**Default**: false
**Category**: [Core](@/api/core.md)
**Example**
```js
// enable text selection within table
fragmentSelection: true,
// or
// enable text selection within cells only
fragmentSelection: 'cell',
```
### height
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L198
:::
_options.height : number | string | function_
Height of the grid. Can be a number or a function that returns a number.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// as a number
height: 500,
// as a string
height: '75vh',
// as a function
height: function() {
return 500;
},
```
### hiddenColumns
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2792
:::
_options.hiddenColumns : boolean | object_
The [HiddenColumns](@/api/hiddenColumns.md) plugin allows hiding of certain columns. You can pass additional configuration with an
object notation. Options that are then available are:
* `columns` - an array of rows that should be hidden on plugin initialization
* `indicators` - enables small ui markers to indicate where are hidden columns.
**Default**: undefined
**Category**: [HiddenColumns](@/api/hiddenColumns.md)
**Example**
```js
// enable column hiding
hiddenColumns: true,
// or
hiddenColumns: {
// set columns that are hidden by default
columns: [5, 10, 15],
// show where are hidden columns
indicators: true
}
```
### hiddenRows
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2819
:::
_options.hiddenRows : boolean | object_
The [HiddenRows](@/api/hiddenRows.md) plugin allows hiding of certain rows. You can pass additional configuration with an
object notation. Options that are then available are:
* `rows` - an array of rows that should be hidden on plugin initialization
* `indicators` - enables small ui markers to indicate where are hidden columns.
**Default**: undefined
**Category**: [HiddenRows](@/api/hiddenRows.md)
**Example**
```js
// enable row hiding
hiddenRows: true,
// or
hiddenRows: {
// set rows that are hidden by default
rows: [5, 10, 15],
// show where are hidden rows
indicators: true
}
```
### invalidCellClassName
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1280
:::
_options.invalidCellClassName : string_
CSS class name for cells that did not pass validation.
**Default**: "htInvalid"
**Category**: [Core](@/api/core.md)
**Example**
```js
// set custom validation error class
invalidCellClassName: 'highlight--error',
```
### label
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2302
:::
_options.label : object_
Object which describes if renderer should create checkbox element with label element as a parent.
__Note__, this option only works for [checkbox-typed](@/guides/cell-types/checkbox-cell-type.md) cells.
By default the [checkbox](@/guides/cell-types/checkbox-cell-type.md) renderer renders the checkbox without a label.
Possible object properties:
* `property` - Defines the property name of the data object, which will to be used as a label.
(eg. `label: {property: 'name.last'}`). This option works only if data was passed as an array of objects.
* `position` - String which describes where to place the label text (before or after checkbox element).
Valid values are `'before'` and '`after`' (defaults to `'after'`).
* `value` - String or a Function which will be used as label text.
* `separated` - Boolean which describes that checkbox & label elements are separated or not. Default value is `false`.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
columns: [{
type: 'checkbox',
// add "My label:" after the checkbox
label: { position: 'after', value: 'My label: ', separated: true }
}],
```
### language
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2353
:::
_options.language : string_
Language for Handsontable translation. Possible language codes are [listed here](@/guides/internationalization/internationalization-i18n.md#list-of-available-languages).
**Default**: "en-US"
**Category**: [Core](@/api/core.md)
**Example**
```js
// set Polish language
language: 'pl-PL',
```
### licenseKey
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L88
:::
_options.licenseKey : string_
License key for commercial version of Handsontable.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
licenseKey: '00000-00000-00000-00000-00000',
// or
licenseKey: 'non-commercial-and-evaluation',
```
### manualColumnFreeze
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2159
:::
_options.manualColumnFreeze : boolean_
Disables or enables [ManualColumnFreeze](@/api/manualColumnFreeze.md) plugin.
**Default**: undefined
**Category**: [ManualColumnFreeze](@/api/manualColumnFreeze.md)
**Example**
```js
// enable fixed columns
manualColumnFreeze: true,
```
### manualColumnMove
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1886
:::
_options.manualColumnMove : boolean | Array<number>_
Turns on [Manual column move](@/guides/columns/column-moving.md), if set to a boolean or define initial column order (as an array of column indexes).
**Default**: undefined
**Category**: [ManualColumnMove](@/api/manualColumnMove.md)
**Example**
```js
// as a boolean to enable column move
manualColumnMove: true,
// as a array with initial order
// (move column index at 0 to 1 and move column index at 1 to 4)
manualColumnMove: [1, 4],
```
### manualColumnResize
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1907
:::
_options.manualColumnResize : boolean | Array<number>_
Turns on [Manual column resize](@/guides/columns/column-width.md#column-stretching), if set to a boolean or define initial column resized widths (an an array of widths).
**Default**: undefined
**Category**: [ManualColumnResize](@/api/manualColumnResize.md)
**Example**
```js
// as a boolean to enable column resize
manualColumnResize: true,
// as a array with initial widths
// (column at 0 index has 40px and column at 1 index has 50px)
manualColumnResize: [40, 50],
```
### manualRowMove
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1928
:::
_options.manualRowMove : boolean | Array<number>_
Turns on [Manual row move](@/guides/columns/column-moving.md), if set to a boolean or define initial row order (as an array of row indexes).
**Default**: undefined
**Category**: [ManualRowMove](@/api/manualRowMove.md)
**Example**
```js
// as a boolean
manualRowMove: true,
// as a array with initial order
// (move row index at 0 to 1 and move row index at 1 to 4)
manualRowMove: [1, 4],
```
### manualRowResize
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1949
:::
_options.manualRowResize : boolean | Array<number>_
Turns on [Manual row resize](@/guides/columns/column-width.md#column-stretching), if set to a boolean or define initial row resized heights (as an array of heights).
**Default**: undefined
**Category**: [ManualRowResize](@/api/manualRowResize.md)
**Example**
```js
// as a boolean to enable row resize
manualRowResize: true,
// as an array to set initial heights
// (row at 0 index has 40px and row at 1 index has 50px)
manualRowResize: [40, 50],
```
### maxCols
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L631
:::
_options.maxCols : number_
Maximum number of cols. If set to a value lower than the initial col count, the data will be trimmed to the provided
value as the number of cols.
**Default**: Infinity
**Category**: [Core](@/api/core.md)
**Example**
```js
// limit table size to maximum 300 columns
maxCols: 300,
```
### maxRows
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L614
:::
_options.maxRows : number_
Maximum number of rows. If set to a value lower than the initial row count, the data will be trimmed to the provided
value as the number of rows.
**Default**: Infinity
**Category**: [Core](@/api/core.md)
**Example**
```js
// limit table size to maximum 300 rows
maxRows: 300,
```
### mergeCells
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1975
:::
_options.mergeCells : boolean | Array<object>_
If set to `true`, it enables a possibility to merge cells. If set to an array of objects, it merges the cells provided
in the objects (see the example below). More information on [the demo page](@/guides/cell-features/merge-cells.md).
**Default**: false
**Category**: [MergeCells](@/api/mergeCells.md)
**Example**
```js
// enables the mergeCells plugin
margeCells: true,
// declares a list of merged sections
mergeCells: [
// rowspan and colspan properties declare the width and height of a merged section in cells
{row: 1, col: 1, rowspan: 3, colspan: 3},
{row: 3, col: 4, rowspan: 2, colspan: 2},
{row: 5, col: 6, rowspan: 3, colspan: 3}
],
```
### minCols
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L597
:::
_options.minCols : number_
Minimum number of columns. At least that number of columns will be created during initialization.
Works only with an array data source. When data source in an object, you can only have as many columns
as defined in the first data row, data schema, or the `columns` setting.
**Default**: 0
**Category**: [Core](@/api/core.md)
**Example**
```js
// set minimum table size to 10 columns
minCols: 10,
```
### minRows
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L579
:::
_options.minRows : number_
Minimum number of rows. At least that number of rows will be created during initialization.
**Default**: 0
**Category**: [Core](@/api/core.md)
**Example**
```js
// set minimum table size to 10 rows
minRows: 10,
```
### minSpareCols
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L665
:::
_options.minSpareCols : number_
When set to 1 (or more), Handsontable will add a new column at the end of grid if there are no more empty columns.
(unless the number of rows exceeds the one set in the `maxCols` property).
**Default**: 0
**Category**: [Core](@/api/core.md)
**Example**
```js
// always add 3 empty columns at the table end
minSpareCols: 3,
```
### minSpareRows
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L648
:::
_options.minSpareRows : number_
When set to 1 (or more), Handsontable will add a new row at the end of grid if there are no more empty rows.
(unless the number of rows exceeds the one set in the `maxRows` property).
**Default**: 0
**Category**: [Core](@/api/core.md)
**Example**
```js
// always add 3 empty rows at the table end
minSpareRows: 3,
```
### multiColumnSorting
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2030
:::
_options.multiColumnSorting : boolean | object_
Turns on [Multi-column sorting](@/guides/rows/row-sorting.md). Can be either a boolean (`true` / `false`) or an object with a declared sorting options:
* `initialConfig` - Array containing objects, every with predefined keys:
* `column` - sorted column
* `sortOrder` - order in which column will be sorted
* `'asc'` = ascending
* `'desc'` = descending
* `indicator` - display status for sorting order indicator (an arrow icon in the column header, specifying the sorting order).
* `true` = show sort indicator for sorted columns
* `false` = don't show sort indicator for sorted columns
* `headerAction` - allow to click on the headers to sort
* `true` = turn on possibility to click on the headers to sort
* `false` = turn off possibility to click on the headers to sort
* `sortEmptyCells` - how empty values ([more information here](@/api/metaSchema.md#allowempty)) should be handled
* `true` = the table sorts empty cells
* `false` = the table moves all empty cells to the end of the table
* `compareFunctionFactory` - curry function returning compare function; compare function should work in the same way as function which is handled by native `Array.sort` method); please take a look at below examples for more information.
**Default**: undefined
**Category**: [MultiColumnSorting](@/api/multiColumnSorting.md)
**Example**
```js
// as boolean
multiColumnSorting: true
// as an object with initial sort config (sort ascending for column at index 1 and then sort descending for column at index 0)
multiColumnSorting: {
initialConfig: [{
column: 1,
sortOrder: 'asc'
}, {
column: 0,
sortOrder: 'desc'
}]
}
// as an object which define specific sorting options for all columns
multiColumnSorting: {
sortEmptyCells: true, // true = the table sorts empty cells, false = the table moves all empty cells to the end of the table
indicator: true, // true = shows indicator for all columns, false = don't show indicator for columns
headerAction: false, // true = allow to click on the headers to sort, false = turn off possibility to click on the headers to sort
compareFunctionFactory: function(sortOrder, columnMeta) {
return function(value, nextValue) {
// Some value comparisons which will return -1, 0 or 1...
}
}
}
```
### nestedHeaders
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2839
:::
_options.nestedHeaders : Array<Array>_
Allows creating a nested header structure, using the HTML's colspan attribute.
**Default**: undefined
**Category**: [NestedHeaders](@/api/nestedHeaders.md)
**Example**
```js
nestedHeaders: [
['A', {label: 'B', colspan: 8}, 'C'],
['D', {label: 'E', colspan: 4}, {label: 'F', colspan: 4}, 'G'],
['H', 'I', 'J', 'K', 'L', 'M', 'N', 'R', 'S', 'T']
],
```
### nestedRows
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L3016
:::
_options.nestedRows : boolean_
Disable or enable the nested rows functionality - displaying nested structures in a two-dimensional data table.
See [quick setup of the Nested rows](@/guides/rows/row-parent-child.md).
**Default**: false
**Category**: [NestedRows](@/api/nestedRows.md)
**Example**
```js
nestedRows: true,
```
### noWordWrapClassName
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1716
:::
_options.noWordWrapClassName : string_
CSS class name added to cells with cell meta `wordWrap: false`.
**Default**: "htNoWrap"
**Category**: [Core](@/api/core.md)
**Example**
```js
// set custom class for cells which content won't be wrapped
noWordWrapClassName: 'is-noWrapCell',
```
### numericFormat
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2337
:::
_options.numericFormat : object_
Display format for numeric typed renderers.
__Note__, this option only works for [numeric-typed](@/guides/cell-types/numeric-cell-type.md) cells.
Format is described by two properties:
* `pattern` - Handled by `numbro` for purpose of formatting numbers to desired pattern. List of supported patterns can be found [here](https://numbrojs.com/format.html#numbers).
* `culture` - Handled by `numbro` for purpose of formatting currencies. Examples showing how it works can be found [here](https://numbrojs.com/format.html#currency). List of supported cultures can be found [here](https://numbrojs.com/languages.html#supported-languages).
__Note:__ Please keep in mind that this option is used only to format the displayed output! It has no effect on the input data provided for the cell. The numeric data can be entered to the table only as floats (separated by a dot or a comma) or integers, and are stored in the source dataset as JavaScript numbers.
Handsontable uses [numbro](https://numbrojs.com/) as a main library for numbers formatting.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Since**: 0.35.0
**Example**
```js
columns: [
{
type: 'numeric',
// set desired format pattern and
numericFormat: {
pattern: '0,00',
culture: 'en-US'
}
}
],
```
### observeDOMVisibility
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1218
:::
_options.observeDOMVisibility : boolean_
When set to `true`, the table is re-rendered when it is detected that it was made visible in DOM.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
// don't rerender the table on visibility changes
observeDOMVisibility: false,
```
### outsideClickDeselects
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L865
:::
_options.outsideClickDeselects : boolean | function_
If `true`, mouse click outside the grid will deselect the current selection. Can be a function that takes the
click event target and returns a boolean.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
// don't clear current selection when mouse click was outside the grid
outsideClickDeselects: false,
// or
outsideClickDeselects: function(event) {
return false;
}
```
### persistentState
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1001
:::
_options.persistentState : boolean_
Turns on saving the state of column sorting, column positions and column sizes in local storage.
You can save any sort of data in local storage to preserve table state between page reloads. In order to enable
data storage mechanism, `persistentState` option must be set to `true` (you can set it either during Handsontable
initialization or using the `updateSettings` method). When `persistentState` is enabled it exposes 3 hooks:
__persistentStateSave__ (key: String, value: Mixed).
* Saves value under given key in browser local storage.
__persistentStateLoad__ (key: String, valuePlaceholder: Object).
* Loads `value`, saved under given key, form browser local storage. The loaded `value` will be saved in
`valuePlaceholder.value` (this is due to specific behaviour of `Hooks.run()` method). If no value have
been saved under key `valuePlaceholder.value` will be `undefined`.
__persistentStateReset__ (key: String).
* Clears the value saved under `key`. If no `key` is given, all values associated with table will be cleared.
__Note:__ The main reason behind using `persistentState` hooks rather than regular LocalStorage API is that it
ensures separation of data stored by multiple Handsontable instances. In other words, if you have two (or more)
instances of Handsontable on one page, data saved by one instance won't be accessible by the second instance.
Those two instances can store data under the same key and no data would be overwritten.
__Important:__ In order for the data separation to work properly, make sure that each instance of Handsontable has a unique `id`.
**Default**: false
**Category**: [PersistentState](@/api/persistentState.md)
**Example**
```js
// enable the persistent state plugin
persistentState: true,
```
### placeholder
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1297
:::
_options.placeholder : string_
When set to an non-empty string, displayed as the cell content for empty cells. If a value of a different type is provided,
it will be stringified and applied as a string.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// add custom placeholder content to empty cells
placeholder: 'Empty Cell',
```
### placeholderCellClassName
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1313
:::
_options.placeholderCellClassName : string_
CSS class name for cells that have a placeholder in use.
**Default**: "htPlaceholder"
**Category**: [Core](@/api/core.md)
**Example**
```js
// set custom placeholder class
placeholderCellClassName: 'has-placeholder',
```
### preventOverflow
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2596
:::
_options.preventOverflow : string | boolean_
Prevents table to overlap outside the parent element. If `'horizontal'` option is chosen then table will show
a horizontal scrollbar if parent's width is narrower then table's width.
Possible values:
* `false` - Disables functionality.
* `horizontal` - Prevents horizontal overflow table.
* `vertical` - Prevents vertical overflow table.
**Default**: false
**Category**: [Core](@/api/core.md)
**Example**
```js
preventOverflow: 'horizontal',
```
### readOnly
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1442
:::
_options.readOnly : boolean_
Makes cell, column or comment [read only](@/guides/cell-features/disabled-cells.md#read-only-columns).
**Default**: false
**Category**: [Core](@/api/core.md)
**Example**
```js
// set as read only
readOnly: true,
```
### readOnlyCellClassName
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1329
:::
_options.readOnlyCellClassName : string_
CSS class name for read-only cells.
**Default**: "htDimmed"
**Category**: [Core](@/api/core.md)
**Example**
```js
// set custom read-only class
readOnlyCellClassName: 'is-readOnly',
```
### renderAllRows
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2575
:::
_options.renderAllRows : boolean_
If typed `true` then virtual rendering mechanism for handsontable will be disabled.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// disable virtual rows rendering
renderAllRows: true,
```
### renderer
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1385
:::
_options.renderer : string | function_
If a string is provided, it may be one of the following predefined values:
* `autocomplete`,
* `checkbox`,
* `html`,
* `numeric`,
* `password`.
* `text`.
Or you can [register](@/guides/cell-functions/cell-renderer.md) the custom renderer under specified name and use its name as an alias in your
configuration.
If a function is provided, it will receive the following arguments:
```js
function(instance, TD, row, col, prop, value, cellProperties) {}
```
You can read more about custom renderes [in the documentation](@/guides/cell-functions/cell-renderer.md).
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// register custom renderer
Handsontable.renderers.registerRenderer('my.renderer', function(instance, TD, row, col, prop, value, cellProperties) {
TD.innerHTML = value;
});
// use it for selected column:
columns: [
{
// as a string with the name of build in renderer
renderer: 'autocomplete',
editor: 'select'
},
{
// as an alias to custom renderer registered above
renderer: 'my.renderer'
},
{
// renderer as custom function
renderer: function(hotInstance, TD, row, col, prop, value, cellProperties) {
TD.style.color = 'blue';
TD.innerHTML = value;
}
}
],
```
### rowHeaders
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L262
:::
_options.rowHeaders : boolean | Array<string> | function_
Setting `true` or `false` will enable or disable the default row headers (1, 2, 3).
You can also define an array `['One', 'Two', 'Three', ...]` or a function to define the headers.
If a function is set the index of the row is passed as a parameter.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// as a boolean
rowHeaders: true,
// as an array
rowHeaders: ['1', '2', '3'],
// as a function
rowHeaders: function(index) {
return index + ': AB';
},
```
### rowHeaderWidth
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2882
:::
_options.rowHeaderWidth : number | Array<number>_
Allows setting a custom width of the row headers. You can provide a number or an array of widths, if many row
header levels are defined.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// set width for all row headers
rowHeaderWidth: 25,
// or
// set width for selected headers only
rowHeaderWidth: [25, 30, 55],
```
### rowHeights
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L360
:::
_options.rowHeights : number | Array<number> | string | Array<string> | Array<undefined> | function_
Defines row heights in pixels. Accepts numbers, strings (that will be converted into a number), array of numbers
(if you want to define row height separately for each row) or a function (if you want to set row height dynamically
on each render).
If the [ManualRowResize](@/api/manualRowResize.md) or [AutoRowSize](@/api/autoRowSize.md) plugins are enabled, this is also the minimum height that can
be set via either of those two plugins.
The default height for rows in the rendering process equals 23px.
Height should be equal or greater than 23px. Table is rendered incorrectly if height is less than 23px.
An `undefined` value is for detection in [Hooks#modifyRowHeight](@/api/pluginHooks.md#modifyrowheight) hook if plugin or setting changed the default size.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// as a number, the same for all rows
rowHeights: 100,
// as a string, the same for all row
rowHeights: '100px',
// as an array, based on visual indexes. The rest of the rows have a default height
rowHeights: [100, 120, 90],
// as a function, based on visual indexes
rowHeights: function(index) {
return index * 10;
},
```
### search
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1517
:::
_options.search : boolean_
Setting to `true` enables the [Search](@/api/search.md) plugin (see [demo](@/guides/accessories-and-menus/searching-values.md)).
**Default**: false
**Category**: [Search](@/api/search.md)
**Example**
```js
// enable search plugin
search: true,
// or
// as an object with detailed configuration
search: {
searchResultClass: 'customClass',
queryMethod: function(queryStr, value) {
...
},
callback: function(instance, row, column, value, result) {
...
}
}
```
### selectionMode
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L752
:::
_options.selectionMode : string_
Defines how the table selection reacts. The selection support three different behaviors defined as:
* `'single'` Only a single cell can be selected.
* `'range'` Multiple cells within a single range can be selected.
* `'multiple'` Multiple ranges of cells can be selected.
To see how to interact with selection by getting selected data or change styles of the selected cells go to
[Selecting Ranges](@/guides/cell-features/selection.md).
**Default**: "multiple"
**Category**: [Core](@/api/core.md)
**Example**
```js
// only one cell can be selected at a time
selectionMode: 'single',
```
### selectOptions
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2376
:::
_options.selectOptions : Array<string>_
Data source for [select-typed](@/guides/cell-types/select-cell-type.md) cells.
__Note__, this option only works for [select-typed](@/guides/cell-types/select-cell-type.md) cells.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
columns: [
{
editor: 'select',
// add three select options to choose from
selectOptions: ['A', 'B', 'C'],
}
],
```
### skipColumnOnPaste
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1463
:::
_options.skipColumnOnPaste : boolean_
When added to a `column` property, it skips the column on paste and pastes the data on the next column to the right.
**Default**: false
**Category**: [Core](@/api/core.md)
**Example**
```js
columns: [
{
// don't paste data to this column
skipColumnOnPaste: true
}
],
```
### skipRowOnPaste
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1488
:::
_options.skipRowOnPaste : boolean_
When added to a cell property, it skips the row on paste and pastes the data on the following row.
**Default**: false
**Category**: [Core](@/api/core.md)
**Example**
```js
cells: function(row, column) {
const cellProperties = {};
// don't paste data to the second row
if (row === 1) {
cellProperties.skipRowOnPaste = true;
}
return cellProperties;
}
```
### sortByRelevance
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2933
:::
_options.sortByRelevance : boolean_
If defined as `true`, the Autocomplete's suggestion list would be sorted by relevance (the closer to the left the
match is, the higher the suggestion).
__Note__, this option only works for [autocomplete-typed](@/guides/cell-types/autocomplete-cell-type.md) cells.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
columns: [
{
type: 'autocomplete',
source: [ ... ],
// keep options order as they were defined
sortByRelevance: false
}
],
```
### source
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2208
:::
_options.source : Array | function_
Defines data source for Autocomplete or Dropdown cell types.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// source as a array
columns: [{
type: 'autocomplete',
source: ['A', 'B', 'C', 'D']
}],
// source as a function
columns: [{
type: 'autocomplete',
source: function(query, callback) {
fetch('https://example.com/query?q=' + query, function(response) {
callback(response.items);
})
}
}],
```
### startCols
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L236
:::
_options.startCols : number_
Initial number of columns.
__Note:__ This option only has effect in Handsontable constructor and only if `data` option is not provided.
**Default**: 5
**Category**: [Core](@/api/core.md)
**Example**
```js
// start with 15 empty columns
startCols: 15,
```
### startRows
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L217
:::
_options.startRows : number_
Initial number of rows.
__Note:__ This option only has effect in Handsontable constructor and only if `data` option is not provided.
**Default**: 5
**Category**: [Core](@/api/core.md)
**Example**
```js
// start with 15 empty rows
startRows: 15,
```
### stretchH
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1129
:::
_options.stretchH : string_
Defines how the columns react, when the declared table width is different than the calculated sum of all column widths.
[See more](@/guides/columns/column-width.md#column-stretching) mode. Possible values:
* `'none'` Disable stretching
* `'last'` Stretch only the last column
* `'all'` Stretch all the columns evenly.
**Default**: "none"
**Category**: [Core](@/api/core.md)
**Example**
```js
// fit table to the container
stretchH: 'all',
```
### strict
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2535
:::
_options.strict : boolean_
If set to `true`, the value entered into the cell must match (case-sensitive) the autocomplete source.
Otherwise, cell won't pass the validation. When filtering the autocomplete source list, the editor will
be working in case-insensitive mode.
__Note__, this option only works for [autocomplete-typed](@/guides/cell-types/autocomplete-cell-type.md) cells.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
columns: [{
type: 'autocomplete',
source: ['A', 'B', 'C'],
// force selected value to match the source list
strict: true
}],
```
### tableClassName
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1108
:::
_options.tableClassName : string | Array<string>_
Class name for all tables inside container element.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// set custom class for table element
tableClassName: 'your__class--name',
// or
tableClassName: ['first-class-name', 'second-class-name'],
```
### tabMoves
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L927
:::
_options.tabMoves : object | function_
Defines the cursor movement after TAB is pressed (SHIFT + TAB uses a negative vector). Can
be an object or a function that returns an object. The event argument passed to the function is a DOM Event object
received after the TAB key has been pressed. This event object can be used to check whether user pressed
TAB or SHIFT + TAB.
**Default**: {row: 0, col: 1}
**Category**: [Core](@/api/core.md)
**Example**
```js
// move selection 2 cells away after TAB pressed.
tabMoves: {row: 2, col: 2},
// or as a function
tabMoves: function(event) {
return {row: 2, col: 2};
},
```
### title
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2234
:::
_options.title : string_
Defines the column header name.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// set header names for every column
columns: [
{
title: 'First name',
type: 'text',
},
{
title: 'Last name',
type: 'text',
}
],
```
### trimDropdown
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1679
:::
_options.trimDropdown : boolean_
Makes autocomplete or dropdown width the same as the edited cell width. If `false` then editor will be scaled
according to its content.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
columns: [
{
type: 'autocomplete',
// don't trim dropdown width with column width
trimDropdown: false,
}
],
```
### trimRows
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2860
:::
_options.trimRows : boolean | Array<number>_
Plugin allowing hiding of certain rows.
**Default**: undefined
**Category**: [TrimRows](@/api/trimRows.md)
**Example**
```js
// enable plugin
trimRows: true,
// or
// trim selected rows on table initialization
trimRows: [5, 10, 15],
```
### trimWhitespace
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2179
:::
_options.trimWhitespace : boolean_
Defines whether Handsontable should trim the whitespace at the beginning and the end of the cell contents.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
columns: [
{
// don't remove whitespace
trimWhitespace: false
}
]
```
### type
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1570
:::
_options.type : string_
Shortcut to define the combination of the cell renderer, editor and validator for the column, cell or whole table.
Possible values:
* [autocomplete](@/guides/cell-types/autocomplete-cell-type.md)
* [checkbox](@/guides/cell-types/checkbox-cell-type.md)
* [date](@/guides/cell-types/date-cell-type.md)
* [dropdown](@/guides/cell-types/dropdown-cell-type.md)
* [handsontable](@/guides/cell-types/handsontable-cell-type.md)
* [numeric](@/guides/cell-types/numeric-cell-type.md)
* [password](@/guides/cell-types/password-cell-type.md)
* text
* [time](@/guides/cell-types/time-cell-type.md).
Or you can register the custom cell type under specified name and use
its name as an alias in your configuration.
**Default**: "text"
**Category**: [Core](@/api/core.md)
**Example**
```js
// register custom cell type:
Handsontable.cellTypes.registerCellType('my.type', {
editor: MyEditorClass,
renderer: function(hot, td, row, col, prop, value, cellProperties) {
td.innerHTML = value;
},
validator: function(value, callback) {
callback(value === 'foo' ? true : false);
}
});
// use it in column settings:
columns: [
{
type: 'text'
},
{
// an alias to custom type
type: 'my.type'
},
{
type: 'checkbox'
}
],
```
### uncheckedTemplate
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2270
:::
_options.uncheckedTemplate : boolean | string | number_
Data template for `'checkbox'` type when checkbox is unchecked.
**Default**: false
**Category**: [Core](@/api/core.md)
**Example**
```js
uncheckedTemplate: 'bad'
// if a checkbox-typed cell is not checked, then getDataAtCell(x,y),
// where x and y are the coordinates of the cell will return 'bad'.
```
### undo
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1814
:::
_options.undo : boolean_
If `true`, undo/redo functionality is enabled.
Note: `undefined` by default but it acts as enabled.
You need to switch it to `false` to disable it completely.
**Default**: undefined
**Category**: [UndoRedo](@/api/undoRedo.md)
**Example**
```js
// enable undo and redo
undo: true,
```
### validator
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2113
:::
_options.validator : function | RegExp | string_
A function, regular expression or a string, which will be used in the process of cell validation. If a function is
used, be sure to execute the callback argument with either `true` (`callback(true)`) if the validation passed
or with `false` (`callback(false)`), if the validation failed.
__Note__, that `this` in the function points to the `cellProperties` object.
If a string is provided, it may be one of the following predefined values:
* `autocomplete`,
* `date`,
* `numeric`,
* `time`.
Or you can [register](@/guides/cell-functions/cell-validator.md) the validator function under specified name and use its name as an alias in your
configuration.
See more [in the demo](@/guides/cell-functions/cell-validator.md).
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
columns: [
{
// as a function
validator: function(value, callback) {
...
}
},
{
// regular expression
validator: /^[0-9]$/
},
{
// as a string
validator: 'numeric'
}
],
```
### viewportColumnRenderingOffset
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2067
:::
_options.viewportColumnRenderingOffset : number | string_
Number of columns to be rendered outside of the visible part of the table. By default, it's set to `'auto'`, which
makes Handsontable try calculating the best offset performance-wise.
You may experiment with the value to find the one that works best for your specific implementation.
**Default**: 'auto'
**Category**: [Core](@/api/core.md)
**Example**
```js
viewportColumnRenderingOffset: 70,
```
### viewportRowRenderingOffset
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L2048
:::
_options.viewportRowRenderingOffset : number | string_
Number of rows to be rendered outside of the visible part of the table. By default, it's set to `'auto'`, which
makes Handsontable to attempt to calculate the best offset performance-wise.
You may test out different values to find the best one that works for your specific implementation.
**Default**: 'auto'
**Category**: [Core](@/api/core.md)
**Example**
```js
viewportRowRenderingOffset: 70,
```
### visibleRows
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1657
:::
_options.visibleRows : number_
Control number of choices for the autocomplete (or dropdown) typed cells. After exceeding it, a scrollbar for the
dropdown list of choices will appear.
**Default**: 10
**Category**: [Core](@/api/core.md)
**Example**
```js
columns: [
{
type: 'autocomplete',
// set autocomplete options list height
visibleRows: 15,
}
],
```
### width
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L174
:::
_options.width : number | string | function_
Width of the grid. Can be a value or a function that returns a value.
**Default**: undefined
**Category**: [Core](@/api/core.md)
**Example**
```js
// as a number
width: 500,
// as a string
width: '75vw',
// as a function
width: function() {
return 500;
},
```
### wordWrap
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1700
:::
_options.wordWrap : boolean_
When set to `true`, the text of the cell content is wrapped if it does not fit in the fixed column width.
**Default**: true
**Category**: [Core](@/api/core.md)
**Example**
```js
colWidths: 100,
columns: [
{
// fixed column width is set but don't wrap the content
wordWrap: false,
}
],
```
## Methods
### isEmptyCol
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1188
:::
_options.isEmptyCol(col) ⇒ boolean_
Overwrites the default `isEmptyCol` method, which checks if column at the provided index is empty.
**Category**: [Core](@/api/core.md)
**Example**
```js
// define custom checks for empty column
isEmptyCol: function(column) {
return false;
},
```
| Param | Type | Description |
| --- | --- | --- |
| col | `number` | Visual column index. |
### isEmptyRow
::: source-code-link https://github.com/handsontable/handsontable/blob/4d56e68f9cb6412b841663278b2e0eb3ad181233/src/dataMap/metaManager/metaSchema.js#L1148
:::
_options.isEmptyRow(row) ⇒ boolean_
Overwrites the default `isEmptyRow` method, which checks if row at the provided index is empty.
**Category**: [Core](@/api/core.md)
**Example**
```js
// define custom checks for empty row
isEmptyRow: function(row) {
...
},
```
| Param | Type | Description |
| --- | --- | --- |
| row | `number` | Visual row index. |