handsontable
Version:
Handsontable is a JavaScript Data Grid available for React, Angular and Vue.
1,002 lines (1,000 loc) • 246 kB
JavaScript
"use strict";
exports.__esModule = true;
var _mixed = require("../../helpers/mixed");
var _object = require("../../helpers/object");
/* eslint-disable jsdoc/require-description-complete-sentence */
/**
* @alias Options
* @class Options
* @description
*
* [Configuration options](@/guides/getting-started/configuration-options/configuration-options.md) let you heavily customize your Handsontable instance. For example, you can:
*
* - Enable and disable built-in features
* - Enable and configure additional [plugins](@/api/plugins.md)
* - Personalize Handsontable's look
* - Adjust Handsontable's behavior
* - Implement your own custom features
*
* ::: only-for javascript
*
* To apply [configuration options](@/guides/getting-started/configuration-options/configuration-options.md), pass them as
* a second argument of the [Handsontable constructor](@/guides/getting-started/installation/installation.md#initialize-handsontable),
* using the [object literal notation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer):
*
* Read more on the [Configuration options](@/guides/getting-started/configuration-options/configuration-options.md) page.
*
* ```js
* const container = document.getElementById('example');
*
* const hot = new Handsontable(container, {
* // configuration options, in the object literal notation
* licenseKey: 'non-commercial-and-evaluation',
* data: [
* ['A1', 'B1', 'C1', 'D1', 'E1'],
* ['A2', 'B2', 'C2', 'D2', 'E2'],
* ['A3', 'B3', 'C3', 'D3', 'E3'],
* ['A4', 'B4', 'C4', 'D4', 'E4'],
* ['A5', 'B5', 'C5', 'D5', 'E5'],
* ],
* width: 400,
* height: 300,
* colHeaders: true,
* rowHeaders: true,
* customBorders: true,
* dropdownMenu: true,
* multiColumnSorting: true,
* filters: true,
* manualRowMove: true,
* });
* ```
* :::
*
* ::: only-for react
*
* To apply configuration options, pass them as individual props
* of the [`HotTable`](@/guides/getting-started/installation/installation.md#_4-use-the-hottable-component)
* or [`HotColumn`](@/guides/columns/react-hot-column/react-hot-column.md) components.
*
* Read more on the [Configuration options](@/guides/getting-started/configuration-options/configuration-options.md) page.
*
* ```jsx
* <HotTable
* // configuration options, in the object literal notation
* licenseKey='non-commercial-and-evaluation'
* data={[
* ['A1', 'B1', 'C1', 'D1', 'E1'],
* ['A2', 'B2', 'C2', 'D2', 'E2'],
* ['A3', 'B3', 'C3', 'D3', 'E3'],
* ['A4', 'B4', 'C4', 'D4', 'E4'],
* ['A5', 'B5', 'C5', 'D5', 'E5'],
* ]}
* width={400}
* height={300}
* colHeaders={true}
* rowHeaders={true}
* customBorders={true}
* dropdownMenu={true}
* multiColumnSorting={true}
* filters={true}
* manualRowMove={true}
* />
* ```
* :::
*
* ::: only-for angular
* ```ts
* settings = {
* data: [
* ["A1", "B1", "C1", "D1", "E1"],
* ["A2", "B2", "C2", "D2", "E2"],
* ["A3", "B3", "C3", "D3", "E3"],
* ["A4", "B4", "C4", "D4", "E4"],
* ["A5", "B5", "C5", "D5", "E5"],
* ],
* width: 400,
* height: 300,
* colHeaders: true,
* rowHeaders: true,
* customBorders: true,
* dropdownMenu: true,
* multiColumnSorting: true,
* filters: true,
* manualRowMove: true,
* };
* ```
*
* ```html
* <hot-table [settings]="settings" />
* ```
* :::
*
* Depending on your needs, you can apply [configuration options](@/api/options.md) to different elements of your grid:
* - [The entire grid](@/guides/getting-started/configuration-options/configuration-options.md#set-grid-options)
* - [Individual columns](@/guides/getting-started/configuration-options/configuration-options.md#set-column-options)
* - [Individual rows](@/guides/getting-started/configuration-options/configuration-options.md#set-row-options)
* - [Individual cells](@/guides/getting-started/configuration-options/configuration-options.md#set-cell-options)
* - [Individual grid elements, based on any logic you implement](@/guides/getting-started/configuration-options/configuration-options.md#implementing-custom-logic)
*
* Read more:
* - [Configuration options](@/guides/getting-started/configuration-options/configuration-options.md)
*/
var _default = () => {
return {
/* eslint-disable jsdoc/require-description-complete-sentence */
/**
* Information on which of the meta properties were added automatically.
* For example: setting the `renderer` property directly won't extend the `_automaticallyAssignedMetaProps`
* entry, but setting a `type` will modify it to `Set(3) {'renderer', 'editor', 'validator', ...}`.
*
* @private
* @type {Set}
* @default undefined
*/
_automaticallyAssignedMetaProps: undefined,
/**
* The `activeHeaderClassName` option lets you add a CSS class name
* to every currently-active, currently-selected header (when a whole column or row is selected).
*
* Read more:
* - [`currentRowClassName`](#currentRowClassName)
* - [`currentColClassName`](#currentColClassName)
* - [`currentHeaderClassName`](#currentHeaderClassName)
* - [`invalidCellClassName`](#invalidCellClassName)
* - [`readOnlyCellClassName`](#readOnlyCellClassName)
* - [`commentedCellClassName`](#commentedCellClassName)
* - [`noWordWrapClassName`](#noWordWrapClassName)
* - [`TableClassName`](#TableClassName)
* - [`className`](#className)
*
* @memberof Options#
* @type {string}
* @since 0.38.2
* @default 'ht__active_highlight'
* @category Core
*
* @example
* ```js
* // add an `ht__active_highlight` CSS class name
* // to every currently-active, currently-selected header
* activeHeaderClassName: 'ht__active_highlight',
* ```
*/
activeHeaderClassName: 'ht__active_highlight',
/**
* The `allowEmpty` option determines whether Handsontable accepts the following values:
* - `null`
* - `undefined`
* - `''`
*
* You can set the `allowEmpty` option to one of the following:
*
* | Setting | Description |
* | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
* | `true` (default) | - Accept `null`, `undefined` and `''` values<br>- Mark cells that contain `null`, `undefined` or `''` values as `valid` |
* | `false` | - Don't accept `null`, `undefined` and `''` values<br>- Mark cells that contain `null`, `undefined` or `''` values with as `invalid` |
*
* ::: tip
* To use the [`allowEmpty`](#allowempty) option, you need to set the [`validator`](#validator) option (or the [`type`](#type) option).
* :::
*
* @memberof Options#
* @type {boolean}
* @default true
* @category Core
*
* @example
* ```js
* // allow empty values in each cell of the entire grid
* allowEmpty: true,
*
* // or
* columns: [
* {
* type: 'date',
* dateFormat: 'DD/MM/YYYY',
* // allow empty values in each cell of the 'date' column
* allowEmpty: true
* }
* ],
* ```
*/
allowEmpty: true,
/**
* The `allowHtml` option configures whether [`autocomplete`](@/guides/cell-types/autocomplete-cell-type/autocomplete-cell-type.md)
* and [`dropdown`](@/guides/cell-types/dropdown-cell-type/dropdown-cell-type.md) cells' [`source`](#source) data
* is treated as HTML.
*
* You can set the `allowHtml` option to one of the following:
*
* | Setting | Description |
* | ----------------- | --------------------------------------------------- |
* | `false` (default) | The [`source`](#source) data is not treated as HTML |
* | `true` | The [`source`](#source) data is treated as HTML |
*
* __Warning:__ Setting the `allowHtml` option to `true` can cause serious XSS vulnerabilities.
*
* Read more:
* - [Autocomplete cell type](@/guides/cell-types/autocomplete-cell-type/autocomplete-cell-type.md)
* - [Dropdown cell type](@/guides/cell-types/dropdown-cell-type/dropdown-cell-type.md)
* - [`source`](#source)
*
* @memberof Options#
* @type {boolean}
* @default false
* @category Core
*
* @example
* ```js
* columns: [
* {
* // set the `type` of each cell in this column to `autocomplete`
* type: 'autocomplete',
* // set options available in every `autocomplete` cell of this column
* source: ['<strong>foo</strong>', '<strong>bar</strong>']
* // use HTML in the `source` list
* allowHtml: true,
* },
* ],
* ```
*/
allowHtml: false,
/**
* If set to `true`, the `allowInsertColumn` option adds the following menu items to the [context menu](@/guides/accessories-and-menus/context-menu/context-menu.md):
* - **Insert column left**
* - **Insert column right**
*
* @memberof Options#
* @type {boolean}
* @default true
* @category Core
*
* @example
* ```js
* // hide the 'Insert column left' and 'Insert column right' menu items from the context menu
* allowInsertColumn: false,
* ```
*/
allowInsertColumn: true,
/**
* If set to `true`, the `allowInsertRow` option adds the following menu items to the [context menu](@/guides/accessories-and-menus/context-menu/context-menu.md):
* - **Insert row above**
* - **Insert row below**
*
* @memberof Options#
* @type {boolean}
* @default true
* @category Core
*
* @example
* ```js
* // hide the 'Insert row above' and 'Insert row below' menu items from the context menu
* allowInsertRow: false,
* ```
*/
allowInsertRow: true,
/**
* The `allowInvalid` option determines whether Handsontable accepts values
* that were marked as `invalid` by the [cell validator](@/guides/cell-functions/cell-validator/cell-validator.md).
*
* You can set the `allowInvalid` option to one of the following:
*
* | Setting | Description |
* | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
* | `true` (default) | - Accept `invalid` values<br>- Allow the user to close the [cell editor](@/guides/cell-functions/cell-editor/cell-editor.md) with `invalid` values<br>- Save `invalid` values into the data source |
* | `false` | - Don't accept `invalid` values<br>- Don't allow the user to close the [cell editor](@/guides/cell-functions/cell-editor/cell-editor.md) with `invalid` values<br>- Don't save `invalid` values into the data source |
*
* Setting the `allowInvalid` option to `false` can be useful when used with the [Autocomplete strict mode](@/guides/cell-types/autocomplete-cell-type/autocomplete-cell-type.md#autocomplete-strict-mode).
*
* Read more:
* - [Cell validator](@/guides/cell-functions/cell-validator/cell-validator.md)
* - [Cell editor](@/guides/cell-functions/cell-editor/cell-editor.md)
* - [Autocomplete strict mode](@/guides/cell-types/autocomplete-cell-type/autocomplete-cell-type.md#autocomplete-strict-mode)
*
* @memberof Options#
* @type {boolean}
* @default true
* @category Core
*
* @example
* ```js
* // don't accept `invalid` values
* // don't allow the user to close the cell editor
* // don't save `invalid` values into the data source
* allowInvalid: false,
* ```
*/
allowInvalid: true,
/**
* If set to `true`, the `allowRemoveColumn` option adds the following menu items to the [context menu](@/guides/accessories-and-menus/context-menu/context-menu.md):
* - **Remove column**
*
* Read more:
* - [Context menu](@/guides/accessories-and-menus/context-menu/context-menu.md)
*
* @memberof Options#
* @type {boolean}
* @default true
* @category Core
*
* @example
* ```js
* // hide the 'Remove column' menu item from the context menu
* allowRemoveColumn: false,
* ```
*/
allowRemoveColumn: true,
/**
* If set to `true`, the `allowRemoveRow` option adds the following menu items to the [context menu](@/guides/accessories-and-menus/context-menu/context-menu.md):
* - **Remove row**
*
* Read more:
* - [Context menu](@/guides/accessories-and-menus/context-menu/context-menu.md)
*
* @memberof Options#
* @type {boolean}
* @default true
* @category Core
*
* @example
* ```js
* // hide the 'Remove row' menu item from the context menu
* allowRemoveRow: false,
* ```
*/
allowRemoveRow: true,
/**
* If set to `true`, the accessibility-related ARIA tags will be added to the table. If set to `false`, they
* will be omitted.
* Defaults to `true`.
*
* @memberof Options#
* @type {boolean}
* @default true
* @category Core
* @since 14.0.0
*/
ariaTags: true,
/**
* The `autoColumnSize` option configures the [`AutoColumnSize`](@/api/autoColumnSize.md) plugin.
*
* You can set the `autoColumnSize` option to one of the following:
*
* | Setting | Description |
* | --------- | -------------------------------------------------------------------------------------------- |
* | `false` | Disable the [`AutoColumnSize`](@/api/autoColumnSize.md) plugin |
* | `true` | Enable the [`AutoColumnSize`](@/api/autoColumnSize.md) plugin with the default configuration |
* | An object | Enable the [`AutoColumnSize`](@/api/autoColumnSize.md) plugin and modify the plugin options |
*
* If you set the `autoColumnSize` option to an object, you can set the following [`AutoColumnSize`](@/api/autoColumnSize.md) plugin options:
*
* | Property | Possible values | Description |
* | ----------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------- |
* | `syncLimit` | A number \| A percentage string | The number/percentage of columns to keep in sync<br>(default: `50`) |
* | `useHeaders` | `true` \| `false` | When calculating column widths:<br>`true`: use column headers<br>`false`: don't use column headers |
* | `samplingRatio` | A number | The number of samples of the same length to be used in column width calculations |
* | `allowSampleDuplicates` | `true` \| `false` | When calculating column widths:<br>`true`: Allow duplicate samples<br>`false`: Don't allow duplicate samples |
*
* By default, the `autoColumnSize` option is set to `undefined`,
* but the [`AutoColumnSize`](@/api/autoColumnSize.md) plugin acts as enabled.
* To disable the [`AutoColumnSize`](@/api/autoColumnSize.md) plugin completely,
* set the `autoColumnSize` option to `false`.
*
* Using the [`colWidths`](#colWidths) option forcibly disables the [`AutoColumnSize`](@/api/autoColumnSize.md) plugin.
*
* Read more:
* - [Plugins: `AutoColumnSize`](@/api/autoColumnSize.md)
*
* @memberof Options#
* @type {object|boolean}
* @default undefined
* @category AutoColumnSize
*
* @example
* ```js
* autoColumnSize: {
* // keep 40% of columns in sync (the rest of columns: async)
* syncLimit: '40%',
* // when calculating column widths, use column headers
* useHeaders: true,
* // when calculating column widths, use 10 samples of the same length
* samplingRatio: 10,
* // when calculating column widths, allow duplicate samples
* allowSampleDuplicates: true
* },
* ```
*/
autoColumnSize: undefined,
/**
* The `autoRowSize` option configures the [`AutoRowSize`](@/api/autoRowSize.md) plugin.
*
* You can set the `autoRowSize` option to one of the following:
*
* | Setting | Description |
* | --------- | -------------------------------------------------------------------------------------- |
* | `false` | Disable the [`AutoRowSize`](@/api/autoRowSize.md) plugin |
* | `true` | Enable the [`AutoRowSize`](@/api/autoRowSize.md) plugin with the default configuration |
* | An object | Enable the [`AutoRowSize`](@/api/autoRowSize.md) plugin and modify the plugin options |
*
* To give Handsontable's scrollbar a proper size, set the `autoRowSize` option to `true`.
*
* If you set the `autoRowSize` option to an object, you can set the following [`AutoRowSize`](@/api/autoRowSize.md) plugin options:
*
* | Property | Possible values | Description |
* | ----------- | ------------------------------- | ----------------------------------------------------------------- |
* | `syncLimit` | A number \| A percentage string | The number/percentage of rows to keep in sync<br>(default: `500`) |
*
* Using the [`rowHeights`](#rowHeights) option forcibly disables the [`AutoRowSize`](@/api/autoRowSize.md) plugin.
*
* Read more:
* - [Plugins: `AutoRowSize`](@/api/autoRowSize.md)
*
* @memberof Options#
* @type {object|boolean}
* @default undefined
* @category AutoRowSize
*
* @example
* ```js
* autoRowSize: {
* // keep 40% of rows in sync (the rest of rows: async)
* syncLimit: '40%'
* },
* ```
*/
autoRowSize: undefined,
/**
* | Setting | Description |
* | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
* | `false` (default) | When you select a bottom-most cell, pressing <kbd>**↓**</kbd> doesn't do anything.<br><br>When you select a top-most cell, pressing <kbd>**↑**</kbd> doesn't do anything. |
* | `true` | When you select a bottom-most cell, pressing <kbd>**↓**</kbd> takes you to the top-most cell of the next column.<br><br>When you select a top-most cell, pressing <kbd>**↑**</kbd> takes you to the bottom-most cell of the previous column. |
*
* @memberof Options#
* @type {boolean}
* @default false
* @category Core
*
* @example
* ```js
* // when you select a bottom-most cell, pressing ⬇ doesn't do anything
* // when you select a top-most cell, pressing ⬆ doesn't do anything
* autoWrapCol: false, // default setting
*
* // when you select a bottom-most cell, pressing ⬇ takes you to the top-most cell of the next column
* // when you select a top-most cell, pressing ⬆ takes you to the bottom-most cell of the previous column
* autoWrapCol: true,
* ```
*/
autoWrapCol: false,
/**
* | Setting | Description |
* | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
* | `false` (default) | When you select the first cell of a row, pressing <kbd>**←**</kbd>* (or <kbd>**Shift**</kbd>+<kbd>**Tab**</kbd>\*\*) doesn't do anything.<br><br>When you select the last cell of a row, pressing <kbd>**→**</kbd>* (or <kbd>**Tab**</kbd>**) doesn't do anything. |
* | `true` | When you select the first cell of a row, pressing <kbd>**←**</kbd>* (or <kbd>**Shift**</kbd>+<kbd>**Tab**</kbd>\*\*) takes you to the last cell of the row above.<br><br>When you select the last cell of a row, pressing <kbd>**→**</kbd>* (or <kbd>**Tab**</kbd>**) takes you to the first cell of the row below. |
*
* \* The exact key depends on your [`layoutDirection`](#layoutdirection) configuration.<br>
* \*\* Unless [`tabNavigation`](#tabnavigation) is set to `false`.
*
* @memberof Options#
* @type {boolean}
* @default false
* @category Core
*
* @example
* ```js
* // when you select the first cell of a row, pressing ⬅ (or Shift+Tab) doesn't do anything
* // when you select the last cell of a row, pressing ➡ (or Tab) doesn't do anything
* autoWrapRow: false, // default setting
*
* // when you select the first cell of a row, pressing ⬅ (or Shift+Tab) takes you to the last cell of the row above
* // when you select the last cell of a row, pressing ➡ (or Tab) takes you to the first cell of the row below
* autoWrapRow: true,
* ```
*/
autoWrapRow: false,
/**
* @description
* The `bindRowsWithHeaders` option configures the [`BindRowsWithHeaders`](@/api/bindRowsWithHeaders.md) plugin.
*
* You can set the `bindRowsWithHeaders` option to one of the following:
*
* | Setting | Description |
* | ------- | ---------------------------------------------------------------------------- |
* | `false` | Disable the the [`BindRowsWithHeaders`](@/api/bindRowsWithHeaders.md) plugin |
* | `true` | Enable the the [`BindRowsWithHeaders`](@/api/bindRowsWithHeaders.md) plugin |
*
* Read more:
* - [Plugins: `BindRowsWithHeaders`](@/api/bindRowsWithHeaders.md)
*
* @memberof Options#
* @type {boolean|string}
* @default undefined
* @category BindRowsWithHeaders
*
* @example
* ```js
* // enable the `BindRowsWithHeaders` plugin
* bindRowsWithHeaders: true
* ```
*/
bindRowsWithHeaders: undefined,
/**
* The `cell` option lets you apply [configuration options](@/guides/getting-started/configuration-options/configuration-options.md) to individual cells.
*
* The `cell` option overwrites the [top-level grid options](@/guides/getting-started/configuration-options/configuration-options.md#set-grid-options),
* and the [`columns`](#columns) options.
*
* Read more:
* - [Configuration options: Setting cell options](@/guides/getting-started/configuration-options/configuration-options.md#set-cell-options)
* - [`columns`](#columns)
*
* @memberof Options#
* @type {Array[]}
* @default []
* @category Core
*
* @example
* ```js
* // set the `cell` option to an array of objects
* cell: [
* // make the cell with coordinates (0, 0) read-only
* {
* row: 0,
* col: 0,
* readOnly: true
* }
* ],
* ```
*/
cell: [],
/**
* @description
* The `cells` option lets you apply any other [configuration options](@/guides/getting-started/configuration-options/configuration-options.md) to
* individual grid elements (columns, rows, cells), based on any logic you implement.
*
* The `cells` option overwrites all other options (including options set by [`columns`](#columns) and [`cell`](#cell)).
* It takes the following parameters:
*
* | Parameter | Required | Type | Description |
* | --------- | -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
* | `row` | Yes | Number | A physical row index |
* | `column` | Yes | Number | A physical column index |
* | `prop` | No | String \| Number | If [`data`](#data) is set to an [array of arrays](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-arrays), `prop` is the same number as `column`.<br><br>If [`data`](#data) is set to an [array of objects](@/guides/getting-started/binding-to-data/binding-to-data.md#array-of-objects), `prop` is a property name for the column's data object. |
*
* Read more:
* - [Configuration options: Implementing custom logic](@/guides/getting-started/configuration-options/configuration-options.md#implement-custom-logic)
* - [Configuration options: Setting row options](@/guides/getting-started/configuration-options/configuration-options.md#set-row-options)
* - [`columns`](#columns)
* - [`cell`](#cell)
*
* @memberof Options#
* @type {Function}
* @default undefined
* @category Core
*
* @example
* ```js
* // set the `cells` option to your custom function
* cells(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;
* },
* ```
*/
cells: undefined,
/**
* The `checkedTemplate` option lets you configure what value
* a checked [`checkbox`](@/guides/cell-types/checkbox-cell-type/checkbox-cell-type.md) cell has.
*
* You can set the `checkedTemplate` option to one of the following:
*
* | Setting | Description |
* | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
* | `true` (default) | If a [`checkbox`](@/guides/cell-types/checkbox-cell-type/checkbox-cell-type.md) cell is checked,<br>the [`getDataAtCell`](@/api/core.md#getDataAtCell) method for this cell returns `true` |
* | A string | If a [`checkbox`](@/guides/cell-types/checkbox-cell-type/checkbox-cell-type.md) cell is checked,<br>the [`getDataAtCell`](@/api/core.md#getDataAtCell) method for this cell returns a string of your choice |
*
* Read more:
* - [Checkbox cell type: Checkbox template](@/guides/cell-types/checkbox-cell-type/checkbox-cell-type.md#checkbox-template)
* - [`getDataAtCell()`](@/api/core.md#getDataAtCell)
* - [`uncheckedTemplate`](#uncheckedTemplate)
*
* @memberof Options#
* @type {boolean|string|number}
* @default true
* @category Core
*
* @example
* ```js
* columns: [
* {
* // set the `type` of each cell in this column to `checkbox`
* // when checked, the cell's value is `true`
* // when unchecked, the cell's value is `false`
* type: 'checkbox',
* },
* {
* // set the `type` of each cell in this column to `checkbox`
* type: 'checkbox',
* // when checked, the cell's value is `'Yes'`
* checkedTemplate: 'Yes',
* // when unchecked, the cell's value is `'No'`
* uncheckedTemplate: 'No'
* }
* ],
* ```
*/
checkedTemplate: undefined,
/**
* The `className` option lets you add CSS class names to every currently-selected element.
*
* You can set the `className` option to one of the following:
*
* | Setting | Description |
* | ------------------- | ---------------------------------------------------------------- |
* | A string | Add a single CSS class name to every currently-selected element |
* | An array of strings | Add multiple CSS class names to every currently-selected element |
*
* ::: tip
* Don't change the `className` metadata of the [column summary](@/guides/columns/column-summary/column-summary.md) row.
* To style the summary row, use the class name assigned automatically by the [`ColumnSummary`](@/api/columnSummary.md) plugin: `columnSummaryResult`.
* :::
*
* To apply different CSS class names on different levels, use Handsontable's [cascading configuration](@/guides/getting-started/configuration-options/configuration-options.md#cascading-configuration).
*
* Read more:
* - [Configuration options: Cascading configuration](@/guides/getting-started/configuration-options/configuration-options.md#cascading-configuration)
* - [`currentRowClassName`](#currentRowClassName)
* - [`currentColClassName`](#currentColClassName)
* - [`currentHeaderClassName`](#currentHeaderClassName)
* - [`activeHeaderClassName`](#activeHeaderClassName)
* - [`invalidCellClassName`](#invalidCellClassName)
* - [`placeholderCellClassName`](#placeholderCellClassName)
* - [`commentedCellClassName`](#commentedCellClassName)
* - [`noWordWrapClassName`](#noWordWrapClassName)
* - [`readOnlyCellClassName`](#readOnlyCellClassName)
* - [`TableClassName`](#TableClassName)
*
* @memberof Options#
* @type {string|string[]}
* @default undefined
* @category Core
*
* @example
* ```js
* // add a `your-class-name` CSS class name
* // to every currently-selected element
* className: 'your-class-name',
*
* // add `first-class-name` and `second-class-name` CSS class names
* // to every currently-selected element
* className: ['first-class-name', 'second-class-name'],
* ```
*/
className: undefined,
/**
* The `colHeaders` option configures your grid's column headers.
*
* You can set the `colHeaders` option to one of the following:
*
* | Setting | Description |
* | -------- | -------------------------------------------------------------------- |
* | `true` | Enable the default column headers ('A', 'B', 'C', ...) |
* | `false` | Disable column headers |
* | An array | Define your own column headers (e.g. `['One', 'Two', 'Three', ...]`) |
* | A function | Define your own column headers, using a function |
*
* Read more:
* - [Column header](@/guides/columns/column-header/column-header.md)
*
* @memberof Options#
* @type {boolean|string[]|Function}
* @default null
* @category Core
*
* @example
* ```js
* // enable the default column headers
* colHeaders: true,
*
* // set your own column headers
* colHeaders: ['One', 'Two', 'Three'],
*
* // set your own column headers, using a function
* colHeaders: function(visualColumnIndex) {
* return `${visualColumnIndex} + : AB`;
* },
* ```
*/
colHeaders: null,
/**
* @description
* The `collapsibleColumns` option configures the [`CollapsibleColumns`](@/api/collapsibleColumns.md) plugin.
*
* You can set the `collapsibleColumns` option to one of the following:
*
* | Setting | Description |
* | -------------------- | ------------------------------------------------------------------------------------------------- |
* | `false` | Disable the [`CollapsibleColumns`](@/api/collapsibleColumns.md) plugin |
* | `true` | Enable the [`CollapsibleColumns`](@/api/collapsibleColumns.md) plugin |
* | An array of objects | Enable the [`CollapsibleColumns`](@/api/collapsibleColumns.md) plugin for selected column headers |
*
* Read more:
* - [Plugins: `CollapsibleColumns`](@/api/collapsibleColumns.md)
*
* @memberof Options#
* @type {boolean|object[]}
* @default undefined
* @category CollapsibleColumns
*
* @example
* ```js
* // enable column collapsing for all headers
* collapsibleColumns: true,
*
* // enable column collapsing for selected headers
* collapsibleColumns: [
* {row: -4, col: 1, collapsible: true},
* {row: -3, col: 5, collapsible: true}
* ],
* ```
*/
collapsibleColumns: undefined,
/**
* @description
* The `columnHeaderHeight` option configures the height of column headers.
*
* You can set the `columnHeaderHeight` option to one of the following:
*
* | Setting | Description |
* | -------- | --------------------------------------------------- |
* | A number | Set the same height for every column header |
* | An array | Set different heights for individual column headers |
*
* @memberof Options#
* @type {number|number[]}
* @default undefined
* @category Core
*
* @example
* ```js
* // set the same height for every column header
* columnHeaderHeight: 25,
*
* // set different heights for individual column headers
* columnHeaderHeight: [25, 30, 55],
* ```
*/
columnHeaderHeight: undefined,
/**
* @description
* The `columns` option lets you apply any other [configuration options](@/guides/getting-started/configuration-options/configuration-options.md) to individual columns (or ranges of columns).
*
* You can set the `columns` option to one of the following:
* - An array of objects (each object represents one column)
* - A function that returns an array of objects
*
* The `columns` option overwrites the [top-level grid options](@/guides/getting-started/configuration-options/configuration-options.md#set-grid-options).
*
* When you use `columns`, the [`startCols`](#startCols), [`minCols`](#minCols), and [`maxCols`](#maxCols) options are ignored.
*
* Read more:
* - [Configuration options: Setting column options](@/guides/getting-started/configuration-options/configuration-options.md#set-column-options)
* - [`startCols`](#startCols)
* - [`minCols`](#minCols)
* - [`maxCols`](#maxCols)
* - [`data`](#data)
*
* @memberof Options#
* @type {object[]|Function}
* @default undefined
* @category Core
*
* @example
* ```js
* // set the `columns` option to an array of objects
* // each object represents one column
* columns: [
* {
* // column options for the first (by physical index) column
* type: 'numeric',
* numericFormat: {
* pattern: '0,0.00 $'
* }
* },
* {
* // column options for the second (by physical index) column
* type: 'text',
* readOnly: true
* }
* ],
*
* // or set the `columns` option to a function, based on physical indexes
* columns(index) {
* return {
* type: index > 0 ? 'numeric' : 'text',
* readOnly: index < 1
* }
* }
* ```
*/
columns: undefined,
/**
* @description
* The `columnSorting` option configures the [`ColumnSorting`](@/api/columnSorting.md) plugin.
*
* You can set the `columnSorting` option to one of the following:
*
* | Setting | Description |
* | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
* | `true` | Enable the [`ColumnSorting`](@/api/columnSorting.md) plugin with the default configuration |
* | `false` | Disable the [`ColumnSorting`](@/api/columnSorting.md) plugin |
* | An object | - Enable the [`ColumnSorting`](@/api/columnSorting.md) plugin<br>- Modify the [`ColumnSorting`](@/api/columnSorting.md) plugin options |
*
* If you set the `columnSorting` option to an object,
* you can set the following [`ColumnSorting`](@/api/columnSorting.md) plugin options:
*
* | Option | Possible settings |
* | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
* | `indicator` | `true`: Display the arrow icon in the column header, to indicate a sortable column<br>`false`: Don't display the arrow icon in the column header |
* | `headerAction` | `true`: Enable clicking on the column header to sort the column<br>`false`: Disable clicking on the column header to sort the column |
* | `sortEmptyCells` | `true`: Sort empty cells as well<br>`false`: Place empty cells at the end |
* | `compareFunctionFactory` | A [custom compare function](@/guides/rows/rows-sorting/rows-sorting.md#add-a-custom-comparator) |
*
* If you set the `columnSorting` option to an object,
* you can also sort individual columns at Handsontable's initialization.
* In the `columnSorting` object, add an object named `initialConfig`,
* with the following properties:
*
* | Option | Possible settings | Description |
* | ----------- | ------------------- | ---------------------------------------------------------------- |
* | `column` | A number | The index of the column that you want to sort at initialization |
* | `sortOrder` | `'asc'` \| `'desc'` | The sorting order:<br>`'asc'`: ascending<br>`'desc'`: descending |
*
* Read more:
* - [Rows sorting](@/guides/rows/rows-sorting/rows-sorting.md)
* - [Rows sorting: Custom compare functions](@/guides/rows/rows-sorting/rows-sorting.md#add-a-custom-comparator)
* - [`multiColumnSorting`](#multiColumnSorting)
*
* @memberof Options#
* @type {boolean|object}
* @default undefined
* @category ColumnSorting
*
* @example
* ```js
* // enable the `ColumnSorting` plugin
* columnSorting: true
*
* // enable the `ColumnSorting` plugin with custom configuration
* columnSorting: {
* // sort empty cells as well
* sortEmptyCells: true,
* // display the arrow icon in the column header
* indicator: true,
* // disable clicking on the column header to sort the column
* headerAction: false,
* // add a custom compare function
* compareFunctionFactory(sortOrder, columnMeta) {
* return function(value, nextValue) {
* // some value comparisons which will return -1, 0 or 1...
* }
* }
* }
*
* // enable the `ColumnSorting` plugin
* columnSorting: {
* // at initialization, sort column 1 in ascending order
* initialConfig: {
* column: 1,
* sortOrder: 'asc'
* },
* // at initialization, sort column 2 in descending order
* initialConfig: {
* column: 2,
* sortOrder: 'desc'
* }
* }
* ```
*/
columnSorting: undefined,
/**
* @description
* The `columnSummary` option configures the [`ColumnSummary`](@/api/columnSummary.md) plugin.
*
* You can set the `columnSummary` option to an array of objects.
* Each object configures a single column summary, using the following properties:
*
* | Property | Possible values | Description |
* | ------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
* | `sourceColumn` | A number | [Column to summarize](@/guides/columns/column-summary/column-summary.md#step-2-select-cells-that-you-want-to-summarize) |
* | `ranges` | An array | [Ranges of rows to summarize](@/guides/columns/column-summary/column-summary.md#step-2-select-cells-that-you-want-to-summarize) |
* | `type` | `'sum'` \| `'min'` \| `'max'` \| `'count'` \| `'average'` \| `'custom'` | [Summary function](@/guides/columns/column-summary/column-summary.md#step-3-calculate-your-summary) |
* | `destinationRow` | A number | [Destination cell's row coordinate](@/guides/columns/column-summary/column-summary.md#step-4-provide-the-destination-cell-s-coordinates) |
* | `destinationColumn` | A number | [Destination cell's column coordinate](@/guides/columns/column-summary/column-summary.md#step-4-provide-the-destination-cell-s-coordinates) |
* | `forceNumeric` | `true` \| `false` | [Treat non-numerics as numerics](@/guides/columns/column-summary/column-summary.md#force-numeric-values) |
* | `reversedRowCoords` | `true` \| `false` | [Reverse row coordinates](@/guides/columns/column-summary/column-summary.md#step-5-make-room-for-the-destination-cell) |
* | `suppressDataTypeErrors` | `true` \| `false` | [Suppress data type errors](@/guides/columns/column-summary/column-summary.md#throw-data-type-errors) |
* | `readOnly` | `true` \| `false` | Make summary cell read-only |
* | `roundFloat` | `true` \| `false` \| A number | [Round summary result](@/guides/columns/column-summary/column-summary.md#round-a-column-summary-result) |
* | `customFunction` | A function | [Custom summary function](@/guides/columns/column-summary/column-summary.md#implement-a-custom-summary-function) |
*
* Read more:
* - [Column summary](@/guides/columns/column-summary/column-summary.md)
* - [Plugins: `ColumnSummary`](@/api/columnSummary.md)
*
* @memberof Options#
* @type {object[]|Function}
* @default undefined
* @category ColumnSummary
*
* @example
* ```js
* columnSummary: [
* {
* sourceColumn: 0,
* ranges: [
* [0, 2], [4], [6, 8]
* ],
* type: 'custom',
* destinationRow: 4,
* destinationColumn: 1,
* forceNumeric: true,
* reversedRowCoords: true,
* suppressDataTypeErrors: false,
* readOnly: true,
* roundFloat: false,
* customFunction(endpoint) {
* return 100;
* }
* }
* ],
* ```
*/
columnSummary: undefined,
/**
* The `colWidths` option sets columns' widths, in pixels.
*
* The default column width is 50px. To change it, set the `colWidths` option to one of the following:
*
* | Setting | Description | Example |
* | ----------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
* | A number | Set the same width for every column | `colWidths: 100` |
* | A string | Set the same width for every column | `colWidths: '100px'` |
* | An array | Set widths separately for each column | `colWidths: [100, 120, undefined]` |
* | A function | Set column widths dynamically,<br>on each render | `colWidths(visualColumnIndex) { return visualColumnIndex * 10; }` |
* | `undefined` | Used by the [modifyColWidth](@/api/hooks.md#modifyColWidth) hook,<br>to detect column width changes. | `colWidths: undefined` |
*
* Setting `colWidths` even for a single column disables the {@link AutoColumnSize} plugin
* for all columns. For this reason, if you use `colWidths`, we recommend you set a width for each one
* of your columns. Otherwise, every column with an undefined width defaults back to 50px,
* which may cut longer columns names.
*
* Read more:
* - [Column width](@/guides/columns/column-width/column-width.md)
* - [Hooks: `modifyColWidth`](@/api/hooks.md#modifyColWidth)
* - [`autoColumnSize`](#autoColumnSize)
*
* @memberof Options#
* @type {number|number[]|string|string[]|Array<undefined>|Function}
* @default undefined
* @category Core
*
* @example
* ```js
* // set every column's width to 100px
* colWidths: 100,
*
* // set every column's width to 100px
* colWidths: '100px',
*
* // set the first (by visual index) column's width to 100
* // set the second (by visual index) column's width to 120
* // set the third (by visual index) column's width to `undefined`, so that it defaults to 50px
* // set any other column's width to the default 50px (note that longer cell values and column