This page covers a non-latest version of Handsontable.

# Options

Description
Applying options to different elements of the grid
Members
Methods
- isEmptyCol
- isEmptyRow

# Description

Handsontable provides many options to choose from. They come either from the Core features or plugins hooks.

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.

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:

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

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 Since: 0.38.2 Example

// this will add a 'ht__active_highlight' class name to appropriate table headers.
activeHeaderClassName: 'ht__active_highlight',

# allowEmpty

Source code

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 Example

// allow empty values for all cells (whole table)
allowEmpty: true,

// or
columns: [
  {
    data: 'date',
    dateFormat: 'DD/MM/YYYY',
    // allow empty values only for the 'date' column
    allowEmpty: true
  }
],

# allowHtml

Source code

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

Default: false Category: Core Example

columns: [{
  type: 'autocomplete',
  // use HTML in the source list
  allowHtml: true,
  source: ['<strong>foo</strong>', '<strong>bar</strong>']
}],

# allowInsertColumn

Source code

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 Example

// hide "Insert column left" and "Insert column right" options from the Context Menu
allowInsertColumn: false,

# allowInsertRow

Source code

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 Example

// hide "Insert row above" and "Insert row below" options from the Context Menu
allowInsertRow: false,

# allowInvalid

Source code

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 Example

// don't save the invalid values
allowInvalid: false,

# allowRemoveColumn

Source code

options.allowRemoveColumn : boolean

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

Default: true Category: Core Example

// hide "Remove column" option from the Context Menu
allowRemoveColumn: false,

# allowRemoveRow

Source code

options.allowRemoveRow : boolean

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

Default: true Category: Core Example

// hide "Remove row" option from the Context Menu
allowRemoveRow: false,

# autoColumnSize

Source code

options.autoColumnSize : object | boolean

Enables or disables the AutoColumnSize 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 option will forcibly disable AutoColumnSize.

Default: undefined Category: AutoColumnSize Example

// as a number (300 columns in sync, rest async)
autoColumnSize: { syncLimit: 300 },

// as a string (percent)
autoColumnSize: { syncLimit: '40%' },

// use headers width while calculating the column width
autoColumnSize: { useHeaders: true },

// 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

options.autoRowSize : object | boolean

Enables or disables AutoRowSize 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 Example

// as a number (300 rows in sync, rest async)
autoRowSize: {syncLimit: 300},

// as a string (percent)
autoRowSize: {syncLimit: '40%'},

# autoWrapCol

Source code

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 Example

// stop ENTER key navigation on the last row
autoWrapCol: false,

# autoWrapRow

Source code

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 Example

// stop TAB key navigation on the last column
autoWrapRow: false,

# bindRowsWithHeaders

Source code

options.bindRowsWithHeaders : boolean | string

Enables the functionality of the BindRowsWithHeaders plugin which allows binding the table rows with their headers. If the plugin is enabled, the table row headers will "stick" to the rows, when they are hidden/moved. Basically, if at the initialization row 0 has a header titled "A", it will have it no matter what you do with the table.

Default: undefined Category: BindRowsWithHeaders Example

// keep row data and row headers in sync
bindRowsWithHeaders: true

# cell

Source code

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 Example

// make cell with coordinates (0, 0) read only
cell: [
  {
    row: 0,
    col: 0,
    readOnly: true
  }
],

# cells

Source code

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
the same number as col, when dataset is an array of arrays.

Default: undefined Category: Core Example

cells: function(row, column, prop) {
  const cellProperties = { readOnly: false };
  const visualRowIndex = this.instance.toVisualRow(row);
  const visualColIndex = this.instance.toVisualColumn(column);

  if (visualRowIndex === 0 && visualColIndex === 0) {
    cellProperties.readOnly = true;
  }

  return cellProperties;
},

# checkedTemplate

Source code

options.checkedTemplate : boolean | string | number

Data template for 'checkbox' type when checkbox is checked.

Default: true Category: Core Example

checkedTemplate: 'good'

// if a checkbox-typed cell is checked, then getDataAtCell(x, y),
// where x and y are the coordinates of the cell will return 'good'.

# className

Source code

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

// 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

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 Example

// as a boolean
colHeaders: true,

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

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

# collapsibleColumns

Source code

options.collapsibleColumns : boolean | Array<object>

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

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

Setting the collapsibleColumns property to true will display a "collapse/expand" button in every header with a defined colspan` property.

To limit this functionality to a smaller group of headers, define the collapsibleColumns property as an array of objects, as in the example below.

Default: undefined Category: CollapsibleColumns Example

// enable collapsing for all headers
collapsibleColumns: true,

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

# columnHeaderHeight

Source code

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 Example

// set shared height for all headers
columnHeaderHeight: 35,

// or
// set height for each header individually
columnHeaderHeight: [35, 20, 55],

// or
// skipped headers will fallback to default value
columnHeaderHeight: [35, undefined, 55],

# columns

Source code

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 for examples.

Default: undefined Category: Core Example

// as an array of objects
// order of the objects in array is representation of physical indexes.
columns: [
  {
    // column options for the first column
    type: 'numeric',
    numericFormat: {
      pattern: '0,0.00 $'
    }
  },
  {
    // column options for the second column
    type: 'text',
    readOnly: true
  }
],

// or as a function, based on physical indexes
columns: function(index) {
  return {
    type: index > 0 ? 'numeric' : 'text',
    readOnly: index < 1
  }
}

# columnSorting

Source code

options.columnSorting : boolean | object

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

initialConfig - Object with predefined keys:
- column - sorted 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) 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 Example

// as boolean
columnSorting: true

// as an object with initial sort config (sort ascending for column at index 1)
columnSorting: {
  initialConfig: {
    column: 1,
    sortOrder: 'asc'
  }
}

// as an object which define specific sorting options for all columns
columnSorting: {
  sortEmptyCells: true, // true = the table sorts empty cells, false = the table moves all empty cells to the end of the table
  indicator: true, // true = shows indicator for all columns, false = don't show indicator for columns
  headerAction: false, // true = allow to click on the headers to sort, false = turn off possibility to click on the headers to sort
  compareFunctionFactory: function(sortOrder, columnMeta) {
    return function(value, nextValue) {
      // Some value comparisons which will return -1, 0 or 1...
    }
  }
}

# columnSummary

Source code

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.

Default: undefined Category: ColumnSummary Example

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

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 hook if plugin or setting changed the default size.

Note: This option will forcely disable AutoColumnSize plugin.

Default: undefined Category: Core Example

// 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

options.commentedCellClassName : string

CSS class name added to the commented cells.

Default: "htCommentCell" Category: Core Example

// set custom class for commented cells
commentedCellClassName: 'has-comment',

# comments

Source code

options.comments : boolean | Array<object>

If true, enables the Comments plugin, which enables an option to apply cell comments through the context menu (configurable with context menu keys commentsAddEdit, commentsRemove).

To initialize Handsontable with predefined comments, provide cell coordinates and comment text values in a form of an array.

See Comments demo for examples.

Default: false Category: Comments Example

// enable comments plugin
comments: true,

// or an object with extra predefined plugin config:

comments: {
  displayDelay: 1000
}

// or
// enable comments plugin and add predefined comments
const hot = new Handsontable(document.getElementById('example'), {
  data: getData(),
  comments: true,
  cell: [
    { row: 1, col: 1, comment: { value: 'Foo' } },
    { row: 2, col: 2, comment: { value: 'Bar' } }
  ]
});

# contextMenu

Source code

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. Possible values:

true (to enable default options),
false (to disable completely)
an array of predefined options,
an object with defined structure.

If the value is an object, you can also customize the options with:

disableSelection - 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 for examples.

Default: undefined Category: ContextMenu Example

// as a boolean
contextMenu: true,

// as an array
contextMenu: ['row_above', 'row_below', '---------', 'undo', 'redo'],

// as an object (`name` attribute is required in the custom keys)
contextMenu: {
  items: {
    "option1": {
      name: "option1"
    },
    "option2": {
      name: "option2",
      submenu: {
        items: [
          {
            key: "option2:suboption1",
            name: "option2:suboption1",
            callback: function(key, options) {
              ...
            }
          },
          ...
        ]
      }
    }
  }
},

# copyable

Source code

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 Example

cells: [
  {
    cell: 0,
    row: 0,
    // cell with coordinates (0, 0) can't be copied
    copyable: false,
  }
],

# copyPaste

Source code

options.copyPaste : object | boolean

Disables or enables the copy/paste functionality.

Default: true Category: CopyPaste Example

// disable copy and paste
copyPaste: false,

// enable copy and paste with custom configuration
copyPaste: {
  columnsLimit: 25,
  rowsLimit: 50,
  pasteMode: 'shift_down',
  uiContainer: document.body,
},

# correctFormat

Source code

options.correctFormat : boolean

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

Note, this option only works for date-typed cells.

Default: false Category: Core Example

columns: [{
  type: 'date',
  dateFormat: 'YYYY-MM-DD',
  // force selected date format
  correctFormat: true
}],

# currentColClassName

Source code

options.currentColClassName : string

Class name for all visible columns in the current selection.

Default: undefined Category: Core Example

// This will add a 'currentColumn' class name to appropriate table cells.
currentColClassName: 'currentColumn',

# currentHeaderClassName

Source code

options.currentHeaderClassName : string

Class name for all visible headers in current selection.

Default: "ht__highlight" Category: Core Example

// This will add a 'ht__highlight' class name to appropriate table headers.
currentHeaderClassName: 'ht__highlight',

# currentRowClassName

Source code

options.currentRowClassName : string

Class name for all visible rows in the current selection.

Default: undefined Category: Core Example

// This will add a 'currentRow' class name to appropriate table cells.
currentRowClassName: 'currentRow',

# customBorders

Source code

options.customBorders : boolean | Array<object>

If true, enables the CustomBorders plugin, which enables an option to apply custom borders through the context menu (configurable with context menu key borders). To initialize Handsontable with predefined custom borders, provide cell coordinates and border styles in a form of an array.

See Custom Borders demo for examples.

Default: false Category: CustomBorders Example

// enable custom borders
customBorders: true,

// or
// enable custom borders and start with predefined left border
customBorders: [
  {
    range: {
      from: {
        row: 1,
        col: 1
      },
      to: {
        row: 3,
        col: 4
      }
    },
    left: {
      width: 2,
      color: 'red'
    },
    right: {},
    top: {},
    bottom: {}
  }
],

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

# data

Source code

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.

Default: undefined Category: Core Example

// as an array of arrays
data: [
  ['A', 'B', 'C'],
  ['D', 'E', 'F'],
  ['G', 'H', 'J']
]

// as an array of objects
data: [
  {id: 1, name: 'Ted Right'},
  {id: 2, name: 'Frank Honest'},
  {id: 3, name: 'Joan Well'},
  {id: 4, name: 'Gail Polite'},
  {id: 5, name: 'Michael Fair'},
]

# dataSchema

Source code

options.dataSchema : object

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

See data-schema for more options.

Default: undefined Category: Core Example

// with data schema we can start with an empty table
data: null,
dataSchema: {id: null, name: {first: null, last: null}, address: null},
colHeaders: ['ID', 'First Name', 'Last Name', 'Address'],
columns: [
  {data: 'id'},
  {data: 'name.first'},
  {data: 'name.last'},
  {data: 'address'}
],
startRows: 5,
minSpareRows: 1

# dateFormat

Source code

options.dateFormat : string

Date validation format.

Note, this option only works for date-typed cells.

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

columns: [{
  type: 'date',
  // localise date format
  dateFormat: 'MM/DD/YYYY'
}],

# defaultDate

Source code

options.defaultDate : string

Definition of default value which will fill the empty cells.

Note, this option only works for date-typed cells.

Default: undefined Category: Core Example

columns: [
  {
    type: 'date',
    // always set this date for empty cells
    defaultDate: '2015-02-02'
  }
],

# disableVisualSelection

Source code

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 Example

// as a boolean
disableVisualSelection: true,

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

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

# dragToScroll

Source code

options.dragToScroll : boolean

Disables or enables the drag to scroll functionality.

Default: true Category: DragToScroll Example

// don't scroll the viewport when selection gets to the viewport edge
dragToScroll: false,

# dropdownMenu

Source code

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, but is triggered by clicking the button in the header.

Default: undefined Category: DropdownMenu Example

// enable dropdown menu
dropdownMenu: true,

// or
// enable and configure dropdown menu options
dropdownMenu: ['remove_col', '---------', 'make_read_only', 'alignment']

# editor

Source code

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:

Or you can register the custom editor under specified name and use its name as an alias in your configuration.

To disable cell editing completely set editor property to false.

Default: undefined Category: Core Example

columns: [
  {
    // set editor for the first column
    editor: 'select'
  },
  {
    // disable editor for the second column
    editor: false
  }
],

# enterBeginsEditing

Source code

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 Example

enterBeginsEditing: false,

# enterMoves

Source code

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 Example

// move selection diagonal by 1 cell in x and y axis
enterMoves: {col: 1, row: 1},
// or as a function
enterMoves: function(event) {
  return {col: 1, row: 1};
},

# fillHandle

Source code

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 Example

// enable plugin in all directions and with autoInsertRow as true
fillHandle: true,

// or
// enable plugin in vertical direction and with autoInsertRow as true
fillHandle: 'vertical',

// or
fillHandle: {
  // enable plugin in both directions and with autoInsertRow as false
  autoInsertRow: false,
},

// or
fillHandle: {
  // enable plugin in vertical direction and with autoInsertRow as false
  autoInsertRow: false,
  direction: 'vertical'
},

# filter

Source code

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

Default: true Category: Core Example

columns: [
  {
    type: 'autocomplete',
    source: [ ... ],
    // don't hide options that don't match search query
    filter: false
  }
],

# filteringCaseSensitive

Source code

options.filteringCaseSensitive : boolean

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

Note, this option only works for autocomplete-typed cells.

Default: false Category: Core Example

columns: [
  {
    type: 'autocomplete',
    source: [ ... ],
    // match case while searching autocomplete options
    filteringCaseSensitive: true
  }
],

# filters

Source code

options.filters : boolean

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

Default: undefined Category: Filters Example

// enable filters
filters: true,

# fixedColumnsLeft

Source code

options.fixedColumnsLeft : number

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

Default: 0 Category: Core Example

// freeze first 3 columns of the table.
fixedColumnsLeft: 3,

# fixedRowsBottom

Source code

options.fixedRowsBottom : number

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

Default: 0 Category: Core Example

// freeze the last 3 rows of the table.
fixedRowsBottom: 3,

# fixedRowsTop

Source code

options.fixedRowsTop : number

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

Default: 0 Category: Core Example

// freeze the first 3 rows of the table.
fixedRowsTop: 3,

# formulas

Source code

options.formulas : boolean | object

The Formulas plugin allows Handsontable to process formula expressions defined in the provided data.

Default: undefined Category: Formulas Example

// in Handsontable's `formulas` configuration option, add the `HyperFormula` class
formulas: {
  engine: HyperFormula,
  // the `Formulas` plugin configuration
}

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

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

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 Example

// enable text selection within table
fragmentSelection: true,

// or
// enable text selection within cells only
fragmentSelection: 'cell',

# height

Source code

options.height : number | string | function

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

Default: undefined Category: Core Example

// as a number
height: 500,

// as a string
height: '75vh',

// as a function
height: function() {
  return 500;
},

# hiddenColumns

Source code

options.hiddenColumns : boolean | object

The HiddenColumns plugin allows hiding of certain columns. You can pass additional configuration with an object notation. Options that are then available are:

columns - an array of rows that should be hidden on plugin initialization
indicators - enables small ui markers to indicate where are hidden columns.

Default: undefined Category: HiddenColumns Example

// enable column hiding
hiddenColumns: true,

// or
hiddenColumns: {
  // set columns that are hidden by default
  columns: [5, 10, 15],
  // show where are hidden columns
  indicators: true
}

# hiddenRows

Source code

options.hiddenRows : boolean | object

The HiddenRows plugin allows hiding of certain rows. You can pass additional configuration with an object notation. Options that are then available are:

rows - an array of rows that should be hidden on plugin initialization
indicators - enables small ui markers to indicate where are hidden columns.

Default: undefined Category: HiddenRows Example

// enable row hiding
hiddenRows: true,

// or
hiddenRows: {
  // set rows that are hidden by default
  rows: [5, 10, 15],
  // show where are hidden rows
  indicators: true
}

# invalidCellClassName

Source code

options.invalidCellClassName : string

CSS class name for cells that did not pass validation.

Default: "htInvalid" Category: Core Example

// set custom validation error class
invalidCellClassName: 'highlight--error',

# label

Source code

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

By default the checkbox renderer renders the checkbox without a label.

Possible object properties:

property - Defines the property name of the data object, which will to be used as a label. (eg. label: {property: 'name.last'}). This option works only if data was passed as an array of objects.
position - String which describes where to place the label text (before or after checkbox element). Valid values are 'before' and 'after' (defaults to 'after').
value - String or a Function which will be used as label text.
separated - Boolean which describes that checkbox & label elements are separated or not. Default value is false.

Default: undefined Category: Core Example

columns: [{
  type: 'checkbox',
  // add "My label:" after the checkbox
  label: { position: 'after', value: 'My label: ', separated: true }
}],

# language

Source code

options.language : string

Language for Handsontable translation. Possible language codes are listed here.

Default: "en-US" Category: Core Example

// set Polish language
language: 'pl-PL',

# licenseKey

Source code

options.licenseKey : string

License key for commercial version of Handsontable.

Default: undefined Category: Core Example

licenseKey: '00000-00000-00000-00000-00000',
// or
licenseKey: 'non-commercial-and-evaluation',

# manualColumnFreeze

Source code

options.manualColumnFreeze : boolean

Disables or enables ManualColumnFreeze plugin.

Default: undefined Category: ManualColumnFreeze Example

// enable fixed columns
manualColumnFreeze: true,

# manualColumnMove

Source code

options.manualColumnMove : boolean | Array<number>

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

Default: undefined Category: ManualColumnMove Example

// as a boolean to enable column move
manualColumnMove: true,

// as a array with initial order
// (move column index at 0 to 1 and move column index at 1 to 4)
manualColumnMove: [1, 4],

# manualColumnResize

Source code

options.manualColumnResize : boolean | Array<number>

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

Default: undefined Category: ManualColumnResize Example

// as a boolean to enable column resize
manualColumnResize: true,

// as a array with initial widths
// (column at 0 index has 40px and column at 1 index has 50px)
manualColumnResize: [40, 50],

# manualRowMove

Source code

options.manualRowMove : boolean | Array<number>

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

Default: undefined Category: ManualRowMove Example

// as a boolean
manualRowMove: true,

// as a array with initial order
// (move row index at 0 to 1 and move row index at 1 to 4)
manualRowMove: [1, 4],

# manualRowResize

Source code

options.manualRowResize : boolean | Array<number>

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

Default: undefined Category: ManualRowResize Example

// as a boolean to enable row resize
manualRowResize: true,

// as an array to set initial heights
// (row at 0 index has 40px and row at 1 index has 50px)
manualRowResize: [40, 50],

# maxCols

Source code

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 Example

// limit table size to maximum 300 columns
maxCols: 300,

# maxRows

Source code

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 Example

// limit table size to maximum 300 rows
maxRows: 300,

# mergeCells

Source code

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.

Default: false Category: MergeCells Example

// enables the mergeCells plugin
margeCells: true,

// declares a list of merged sections
mergeCells: [
  // rowspan and colspan properties declare the width and height of a merged section in cells
  {row: 1, col: 1, rowspan: 3, colspan: 3},
  {row: 3, col: 4, rowspan: 2, colspan: 2},
  {row: 5, col: 6, rowspan: 3, colspan: 3}
],

# minCols

Source code

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 Example

// set minimum table size to 10 columns
minCols: 10,

# minRows

Source code

options.minRows : number

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

Default: 0 Category: Core Example

// set minimum table size to 10 rows
minRows: 10,

# minSpareCols

Source code

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 Example

// always add 3 empty columns at the table end
minSpareCols: 3,

# minSpareRows

Source code

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 Example

// always add 3 empty rows at the table end
minSpareRows: 3,

# multiColumnSorting

Source code

options.multiColumnSorting : boolean | object

Turns on Multi-column sorting. Can be either a boolean (true / false) or an object with a declared sorting options:

initialConfig - Array containing objects, every with predefined keys:
- column - sorted 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) 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 Example

// as boolean
multiColumnSorting: true

// as an object with initial sort config (sort ascending for column at index 1 and then sort descending for column at index 0)
multiColumnSorting: {
  initialConfig: [{
    column: 1,
    sortOrder: 'asc'
  }, {
    column: 0,
    sortOrder: 'desc'
  }]
}

// as an object which define specific sorting options for all columns
multiColumnSorting: {
  sortEmptyCells: true, // true = the table sorts empty cells, false = the table moves all empty cells to the end of the table
  indicator: true, // true = shows indicator for all columns, false = don't show indicator for columns
  headerAction: false, // true = allow to click on the headers to sort, false = turn off possibility to click on the headers to sort
  compareFunctionFactory: function(sortOrder, columnMeta) {
    return function(value, nextValue) {
      // Some value comparisons which will return -1, 0 or 1...
    }
  }
}

# nestedHeaders

Source code

options.nestedHeaders : Array<Array>

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

Default: undefined Category: NestedHeaders Example

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

# nestedRows

Source code

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.

Default: false Category: NestedRows Example

nestedRows: true,

# noWordWrapClassName

Source code

options.noWordWrapClassName : string

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

Default: "htNoWrap" Category: Core Example

// set custom class for cells which content won't be wrapped
noWordWrapClassName: 'is-noWrapCell',

# numericFormat

Source code

options.numericFormat : object

Display format for numeric typed renderers.

Note, this option only works for numeric-typed 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 (opens new window).
culture - Handled by numbro for purpose of formatting currencies. Examples showing how it works can be found here (opens new window). List of supported cultures can be found here (opens new window).

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 (opens new window) as a main library for numbers formatting.

Default: undefined Category: Core Since: 0.35.0 Example

columns: [
  {
    type: 'numeric',
    // set desired format pattern and
    numericFormat: {
      pattern: '0,00',
      culture: 'en-US'
    }
  }
],

# observeDOMVisibility

Source code

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 Example

// don't rerender the table on visibility changes
observeDOMVisibility: false,

# outsideClickDeselects

Source code

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 Example

// don't clear current selection when mouse click was outside the grid
outsideClickDeselects: false,

// or
outsideClickDeselects: function(event) {
  return false;
}

# persistentState

Source code

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 Example

// enable the persistent state plugin
persistentState: true,

# placeholder

Source code

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 Example

// add custom placeholder content to empty cells
placeholder: 'Empty Cell',

# placeholderCellClassName

Source code

options.placeholderCellClassName : string

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

Default: "htPlaceholder" Category: Core Example

// set custom placeholder class
placeholderCellClassName: 'has-placeholder',

# preventOverflow

Source code

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 Example

preventOverflow: 'horizontal',

# readOnly

Source code

options.readOnly : boolean

Makes cell, column or comment read only.

Default: false Category: Core Example

// set as read only
readOnly: true,

# readOnlyCellClassName

Source code

options.readOnlyCellClassName : string

CSS class name for read-only cells.

Default: "htDimmed" Category: Core Example

// set custom read-only class
readOnlyCellClassName: 'is-readOnly',

# renderAllRows

Source code

options.renderAllRows : boolean

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

Default: undefined Category: Core Example

// disable virtual rows rendering
renderAllRows: true,

# renderer

Source code

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 the custom renderer under specified name and use its name as an alias in your configuration.

If a function is provided, it will receive the following arguments:

function(instance, TD, row, col, prop, value, cellProperties) {}

You can read more about custom renderes in the documentation.

Default: undefined Category: Core Example

// register custom renderer
Handsontable.renderers.registerRenderer('my.renderer', function(instance, TD, row, col, prop, value, cellProperties) {
  TD.innerHTML = value;
});

// use it for selected column:
columns: [
  {
    // as a string with the name of build in renderer
    renderer: 'autocomplete',
    editor: 'select'
  },
  {
    // as an alias to custom renderer registered above
    renderer: 'my.renderer'
  },
  {
    // renderer as custom function
    renderer: function(hotInstance, TD, row, col, prop, value, cellProperties) {
      TD.style.color = 'blue';
      TD.innerHTML = value;
    }
  }
],

# rowHeaders

Source code

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 Example

// as a boolean
rowHeaders: true,

// as an array
rowHeaders: ['1', '2', '3'],

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

# rowHeaderWidth

Source code

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 Example

// set width for all row headers
rowHeaderWidth: 25,

// or
// set width for selected headers only
rowHeaderWidth: [25, 30, 55],

# rowHeights

Source code

Defines row heights in pixels. Accepts numbers, strings (that will be converted into a number), array of numbers (if you want to define row height separately for each row) or a function (if you want to set row height dynamically on each render).

If the ManualRowResize or AutoRowSize plugins are enabled, this is also the minimum height that can be set via either of those two plugins.

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 hook if plugin or setting changed the default size.

Default: undefined Category: Core Example

// as a number, the same for all rows
rowHeights: 100,

// as a string, the same for all row
rowHeights: '100px',

// as an array, based on visual indexes. The rest of the rows have a default height
rowHeights: [100, 120, 90],

// as a function, based on visual indexes
rowHeights: function(index) {
  return index * 10;
},

# search

Source code

options.search : boolean

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

Default: false Category: Search Example

// enable search plugin
search: true,

// or
// as an object with detailed configuration
search: {
  searchResultClass: 'customClass',
  queryMethod: function(queryStr, value) {
    ...
  },
  callback: function(instance, row, column, value, result) {
    ...
  }
}

# selectionMode

Source code

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.

Default: "multiple" Category: Core Example

// only one cell can be selected at a time
selectionMode: 'single',

# selectOptions

Source code

options.selectOptions : Array<string>

Data source for select-typed cells.

Note, this option only works for select-typed cells.

Default: undefined Category: Core Example

columns: [
  {
    editor: 'select',
    // add three select options to choose from
    selectOptions: ['A', 'B', 'C'],
  }
],

# skipColumnOnPaste

Source code

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 Example

columns: [
  {
    // don't paste data to this column
    skipColumnOnPaste: true
  }
],

# skipRowOnPaste

Source code

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 Example

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

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

Default: true Category: Core Example

columns: [
  {
    type: 'autocomplete',
    source: [ ... ],
    // keep options order as they were defined
    sortByRelevance: false
  }
],

# source

Source code

options.source : Array | function

Defines data source for Autocomplete or Dropdown cell types.

Default: undefined Category: Core Example

// source as a array
columns: [{
  type: 'autocomplete',
  source: ['A', 'B', 'C', 'D']
}],

// source as a function
columns: [{
  type: 'autocomplete',
  source: function(query, callback) {
    fetch('https://example.com/query?q=' + query, function(response) {
      callback(response.items);
    })
  }
}],

# startCols

Source code

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 Example

// start with 15 empty columns
startCols: 15,

# startRows

Source code

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 Example

// start with 15 empty rows
startRows: 15,

# stretchH

Source code

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 mode. Possible values:

'none' Disable stretching
'last' Stretch only the last column
'all' Stretch all the columns evenly.

Default: "none" Category: Core Example

// fit table to the container
stretchH: 'all',

# strict

Source code

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

Default: undefined Category: Core Example

columns: [{
  type: 'autocomplete',
  source: ['A', 'B', 'C'],
  // force selected value to match the source list
  strict: true
}],

# tableClassName

Source code

options.tableClassName : string | Array<string>

Class name for all tables inside container element.

Default: undefined Category: Core Example

// set custom class for table element
tableClassName: 'your__class--name',

// or
tableClassName: ['first-class-name', 'second-class-name'],

# tabMoves

Source code

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 Example

// move selection 2 cells away after TAB pressed.
tabMoves: {row: 2, col: 2},
// or as a function
tabMoves: function(event) {
  return {row: 2, col: 2};
},

# title

Source code

options.title : string

Defines the column header name.

Default: undefined Category: Core Example

// set header names for every column
columns: [
  {
    title: 'First name',
    type: 'text',
  },
  {
    title: 'Last name',
    type: 'text',
  }
],

# trimDropdown

Source code

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 Example

columns: [
  {
    type: 'autocomplete',
    // don't trim dropdown width with column width
    trimDropdown: false,
  }
],

# trimRows

Source code

options.trimRows : boolean | Array<number>

Plugin allowing hiding of certain rows.

Default: undefined Category: TrimRows Example

// enable plugin
trimRows: true,

// or
// trim selected rows on table initialization
trimRows: [5, 10, 15],

# trimWhitespace

Source code

options.trimWhitespace : boolean

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

Default: true Category: Core Example

columns: [
  {
    // don't remove whitespace
    trimWhitespace: false
  }
]

# type

Source code

options.type : string

Shortcut to define the combination of the cell renderer, editor and validator for the column, cell or whole table.

Possible values:

Or you can register the custom cell type under specified name and use its name as an alias in your configuration.

Default: "text" Category: Core Example

// register custom cell type:
Handsontable.cellTypes.registerCellType('my.type', {
  editor: MyEditorClass,
  renderer: function(hot, td, row, col, prop, value, cellProperties) {
    td.innerHTML = value;
  },
  validator: function(value, callback) {
    callback(value === 'foo' ? true : false);
  }
});

// use it in column settings:
columns: [
  {
    type: 'text'
  },
  {
    // an alias to custom type
    type: 'my.type'
  },
  {
    type: 'checkbox'
  }
],

# uncheckedTemplate

Source code

options.uncheckedTemplate : boolean | string | number

Data template for 'checkbox' type when checkbox is unchecked.

Default: false Category: Core Example

uncheckedTemplate: 'bad'

// if a checkbox-typed cell is not checked, then getDataAtCell(x,y),
// where x and y are the coordinates of the cell will return 'bad'.

# undo

Source code

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 Example

// enable undo and redo
undo: true,

# validator

Source code

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 the validator function under specified name and use its name as an alias in your configuration.

See more in the demo.

Default: undefined Category: Core Example

columns: [
   {
     // as a function
     validator: function(value, callback) {
         ...
     }
   },
   {
     // regular expression
     validator: /^[0-9]$/
   },
   {
     // as a string
     validator: 'numeric'
   }
],

# viewportColumnRenderingOffset

Source code

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 Example

viewportColumnRenderingOffset: 70,

# viewportRowRenderingOffset

Source code

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 Example

viewportRowRenderingOffset: 70,

# visibleRows

Source code

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 Example

columns: [
  {
    type: 'autocomplete',
    // set autocomplete options list height
    visibleRows: 15,
  }
],

# width

Source code

options.width : number | string | function

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

Default: undefined Category: Core Example

// as a number
width: 500,

// as a string
width: '75vw',

// as a function
width: function() {
  return 500;
},

# wordWrap

Source code

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 Example

colWidths: 100,
columns: [
  {
    // fixed column width is set but don't wrap the content
    wordWrap: false,
  }
],

# Methods

# isEmptyCol

Source code

options.isEmptyCol(col) ⇒ boolean

Overwrites the default isEmptyCol method, which checks if column at the provided index is empty.

Category: Core Example

// define custom checks for empty column
isEmptyCol: function(column) {
   return false;
},

Param	Type	Description
col	`number`	Visual column index.

# isEmptyRow

Source code

options.isEmptyRow(row) ⇒ boolean

Overwrites the default isEmptyRow method, which checks if row at the provided index is empty.

Category: Core Example

// define custom checks for empty row
isEmptyRow: function(row) {
   ...
},

Param	Type	Description
row	`number`	Visual row index.

← Hooks AutoColumnSize →