# Options

Table of contents

# 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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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:

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 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 (opens new window)

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 (opens new window)

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 (opens new window)

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:

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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,
Source code (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

options.formulas : boolean | object

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

Default: undefined
Category: Formulas
Example

// enable formulas plugin
formulas: true,

// or as an object with custom variables to be used in formula expressions
formulas: {
  variables: {
    FOO: 64,
    BAR: 'baz',
  }
},

# fragmentSelection

Source code (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

options.manualColumnFreeze : boolean

Disables or enables ManualColumnFreeze plugin.

Default: undefined
Category: ManualColumnFreeze
Example

// enable fixed columns
manualColumnFreeze: true,

# manualColumnMove

Source code (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

options.readOnly : boolean

Makes cell, column or comment read only.

Default: false
Category: Core
Example

// set as read only
readOnly: true,

# readOnlyCellClassName

Source code (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 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;
},
Source code (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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.
Last Updated: Jul 8, 2021