Skip to content

Setting options

Configure your grid down to each column, row, and cell, using various built-in options that control Handsontable DataGrid’s behavior and user interface.

Overview

To apply configuration options, pass them as individual props of the HotTable or HotColumn components.

<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
autoWrapRow={true}
autoWrapCol={true}
data={[
['A1', 'B1', 'C1', 'D1'],
['A2', 'B2', 'C2', 'D2'],
['A3', 'B3', 'C3', 'D3'],
]}
width={400}
height={300}
colHeaders={true}
rowHeaders={true}
customBorders={true}
dropdownMenu={true}
multiColumnSorting={true}
filters={true}
manualRowMove={true}
/>

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

For the full list of available configuration options, see the configuration options’ API reference.

Cascading configuration

Handsontable’s configuration cascades down:

  • From the top-level grid options (GlobalMeta)
  • Through the mid-level column options (ColumnMeta)
  • To the bottom-level cell options (CellMeta)

When you modify the mid-level column options (using the columns option):

  • The options that you change overwrite the top-level grid options.
  • The options that you change cascade down to the bottom-level cell options.
  • Any unchanged options are inherited from the top-level grid options.

When you modify the bottom-level cell options (using the cell option):

  • The options that you change overwrite the top-level grid options.
  • The options that you change overwrite the mid-level column options.
  • Any unchanged options are inherited from the mid-level column options or the top-level grid options.

When you modify any options with the cells function, the changes overwrite all other options.

Not every option takes effect at every level. Most work at all of them, but some are read only from the grid settings, so setting them per column or per cell has no effect. Each option’s reference entry states the levels it can be set at, and Option levels lists them all in one searchable table.

For how a cell inherits values from the levels above it, and where each value comes from, see Understanding metadata and inheritance. For the implementation, see the MetaManager class.

To read configuration at runtime, use the method that matches the level you need:

Plugin options

Configuration options come from:

If you use Handsontable through modules: to use an option that comes from a Handsontable plugin, you need to import and register that plugin when initializing your Handsontable instance.

To find out if an option comes from a plugin, check the Category label in the configuration options’ API reference.

Set grid options

To apply configuration options to the entire grid, pass your options as individual props of the HotTable or HotColumn components.

A prop set to undefined counts as a prop you did not pass, so the option keeps its default value. If a prop that had a value changes to undefined, the option returns to its default.

For example, to set the entire grid’s width and height:

<HotTable width={400} height={300} />

Example

To configure each cell in the grid as read-only, apply the readOnly option as a top-level grid option.

The top-level grid options cascade down:

  • To the mid-level column options
  • To the bottom-level cell options

As a result, each cell in the grid is read-only:

JavaScript
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modules
registerAllModules();
const ExampleComponent = () => {
const data = [
['A1', 'B1', 'C1', 'D1', 'E1', 'F1', 'G1', 'H1', 'I1', 'J1'],
['A2', 'B2', 'C2', 'D2', 'E2', 'F2', 'G2', 'H2', 'I2', 'J2'],
['A3', 'B3', 'C3', 'D3', 'E3', 'F3', 'G3', 'H3', 'I3', 'J3'],
['A4', 'B4', 'C4', 'D4', 'E4', 'F4', 'G4', 'H4', 'I4', 'J4'],
['A5', 'B5', 'C5', 'D5', 'E5', 'F5', 'G5', 'H5', 'I5', 'J5'],
];
return (
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
autoWrapRow={true}
autoWrapCol={true}
data={data}
readOnly={true}
width="auto"
height="auto"
rowHeaders={true}
colHeaders={true}
/>
);
};
export default ExampleComponent;
TypeScript
import { FC } from 'react';
import { HotTable, HotTableProps } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
import Handsontable from 'handsontable/base';
// register Handsontable's modules
registerAllModules();
const ExampleComponent: FC = () => {
const data: Handsontable.CellValue[][] = [
['A1', 'B1', 'C1', 'D1', 'E1', 'F1', 'G1', 'H1', 'I1', 'J1'],
['A2', 'B2', 'C2', 'D2', 'E2', 'F2', 'G2', 'H2', 'I2', 'J2'],
['A3', 'B3', 'C3', 'D3', 'E3', 'F3', 'G3', 'H3', 'I3', 'J3'],
['A4', 'B4', 'C4', 'D4', 'E4', 'F4', 'G4', 'H4', 'I4', 'J4'],
['A5', 'B5', 'C5', 'D5', 'E5', 'F5', 'G5', 'H5', 'I5', 'J5'],
];
return (
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
autoWrapRow={true}
autoWrapCol={true}
data={data}
readOnly={true}
width="auto"
height="auto"
rowHeaders={true}
colHeaders={true}
/>
);
};
export default ExampleComponent;

Set column options

To apply configuration options to an individual column (or a range of columns), use the columns option.

<HotTable
columns={[
{width: 100}, // column options for the first (by physical index) column
{width: 100}, // column options for the second (by physical index) column
{width: 100}, // column options for the third (by physical index) column
]}
/>

Alternatively, you can use the HotColumn component to configure columns declaratively:

<HotTable>
<HotColumn width={100}/>
<HotColumn width={100}/>
<HotColumn width={100}/>
</HotTable>

Example

In the example below, the columns option is set to a function.

The function applies the readOnly: true option to each column that has a physical index of either 2 or 8.

The modified mid-level column options:

  • Overwrite the top-level grid options
  • Cascade down to the bottom-level cell options

As a result, each cell in the third and ninth columns is read-only:

JavaScript
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modules
registerAllModules();
const ExampleComponent = () => {
const data = [
['A1', 'B1', 'C1', 'D1', 'E1', 'F1', 'G1', 'H1', 'I1', 'J1'],
['A2', 'B2', 'C2', 'D2', 'E2', 'F2', 'G2', 'H2', 'I2', 'J2'],
['A3', 'B3', 'C3', 'D3', 'E3', 'F3', 'G3', 'H3', 'I3', 'J3'],
['A4', 'B4', 'C4', 'D4', 'E4', 'F4', 'G4', 'H4', 'I4', 'J4'],
['A5', 'B5', 'C5', 'D5', 'E5', 'F5', 'G5', 'H5', 'I5', 'J5'],
];
return (
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
autoWrapRow={true}
autoWrapCol={true}
data={data}
width="auto"
height="auto"
rowHeaders={true}
colHeaders={true}
readOnly={false}
columns={(index) => ({
readOnly: index === 2 || index === 8,
})}
/>
);
};
export default ExampleComponent;
TypeScript
import { FC } from 'react';
import { HotTable, HotTableProps } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
import Handsontable from 'handsontable/base';
// register Handsontable's modules
registerAllModules();
const ExampleComponent: FC = () => {
const data: Handsontable.CellValue[][] = [
['A1', 'B1', 'C1', 'D1', 'E1', 'F1', 'G1', 'H1', 'I1', 'J1'],
['A2', 'B2', 'C2', 'D2', 'E2', 'F2', 'G2', 'H2', 'I2', 'J2'],
['A3', 'B3', 'C3', 'D3', 'E3', 'F3', 'G3', 'H3', 'I3', 'J3'],
['A4', 'B4', 'C4', 'D4', 'E4', 'F4', 'G4', 'H4', 'I4', 'J4'],
['A5', 'B5', 'C5', 'D5', 'E5', 'F5', 'G5', 'H5', 'I5', 'J5'],
];
return (
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
autoWrapRow={true}
autoWrapCol={true}
data={data}
width="auto"
height="auto"
rowHeaders={true}
colHeaders={true}
readOnly={false}
columns={(index: number) => ({
readOnly: index === 2 || index === 8,
})}
/>
);
};
export default ExampleComponent;

Set row options

To apply configuration options to an individual row (or a range of rows), use the cells option.

Any options modified through cells overwrite all other options.

The function can take three arguments:

  • row: a row coordinate (a physical index)
  • col: a column coordinate (a physical index)
  • prop: if your data is an array of objects, prop is a property name for a column’s data source object.
    If your data is an array of arrays, prop is the same as col.
<HotTable cells={(row, col, prop) => {
if (row === 1 || row === 4) {
return {
// row options, which apply to each cell of the second row
// and to each cell of the fifth row
readOnly: true,
};
}
}}/>

The arrow function passed to cells does not bind this, so this.instance is not available inside it. To access the Handsontable instance, use the component’s ref: hotTableRef.current.hotInstance.

Example

In the example below, the cells option sets each cell in the first and fourth row as readOnly.

Options modified through cells overwrite all other options.

JavaScript
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modules
registerAllModules();
const ExampleComponent = () => {
const data = [
['A1', 'B1', 'C1', 'D1', 'E1', 'F1', 'G1', 'H1', 'I1', 'J1'],
['A2', 'B2', 'C2', 'D2', 'E2', 'F2', 'G2', 'H2', 'I2', 'J2'],
['A3', 'B3', 'C3', 'D3', 'E3', 'F3', 'G3', 'H3', 'I3', 'J3'],
['A4', 'B4', 'C4', 'D4', 'E4', 'F4', 'G4', 'H4', 'I4', 'J4'],
['A5', 'B5', 'C5', 'D5', 'E5', 'F5', 'G5', 'H5', 'I5', 'J5'],
];
return (
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
autoWrapRow={true}
autoWrapCol={true}
data={data}
width="auto"
height="auto"
rowHeaders={true}
colHeaders={true}
cells={(row, col) => {
if (row === 1 || row === 4) {
return { readOnly: true };
}
return {};
}}
/>
);
};
export default ExampleComponent;
TypeScript
import { FC } from 'react';
import { HotTable, HotTableProps } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
import Handsontable from 'handsontable/base';
// register Handsontable's modules
registerAllModules();
const ExampleComponent: FC = () => {
const data: Handsontable.CellValue[][] = [
['A1', 'B1', 'C1', 'D1', 'E1', 'F1', 'G1', 'H1', 'I1', 'J1'],
['A2', 'B2', 'C2', 'D2', 'E2', 'F2', 'G2', 'H2', 'I2', 'J2'],
['A3', 'B3', 'C3', 'D3', 'E3', 'F3', 'G3', 'H3', 'I3', 'J3'],
['A4', 'B4', 'C4', 'D4', 'E4', 'F4', 'G4', 'H4', 'I4', 'J4'],
['A5', 'B5', 'C5', 'D5', 'E5', 'F5', 'G5', 'H5', 'I5', 'J5'],
];
return (
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
autoWrapRow={true}
autoWrapCol={true}
data={data}
width="auto"
height="auto"
rowHeaders={true}
colHeaders={true}
cells={(row: number, col: number) => {
if (row === 1 || row === 4) {
return { readOnly: true };
}
return {};
}}
/>
);
};
export default ExampleComponent;

Set cell options

To apply configuration options to individual cells, use the cell option.

Each entry’s row and col are visual indexes (unlike the cells option, whose row and column are physical indexes).

<HotTable cell={[
{ // bottom-level cell options overwrite the top-level grid options
// apply only to a cell with coordinates (0, 0)
row: 0,
col: 0,
},
{
// bottom-level cell options overwrite the top-level grid options
// apply only to a cell with coordinates (1, 1)
row: 1,
col: 1,
}
]}/>

Example

In the example below, the cell option sets cell A1(0, 0) and cell B2(1, 1) as readOnly.

The modified cell options:

  • Overwrite the top-level grid options
  • Overwrite mid-level column options
JavaScript
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modules
registerAllModules();
const ExampleComponent = () => {
const data = [
['A1', 'B1', 'C1', 'D1', 'E1', 'F1', 'G1', 'H1', 'I1', 'J1'],
['A2', 'B2', 'C2', 'D2', 'E2', 'F2', 'G2', 'H2', 'I2', 'J2'],
['A3', 'B3', 'C3', 'D3', 'E3', 'F3', 'G3', 'H3', 'I3', 'J3'],
['A4', 'B4', 'C4', 'D4', 'E4', 'F4', 'G4', 'H4', 'I4', 'J4'],
['A5', 'B5', 'C5', 'D5', 'E5', 'F5', 'G5', 'H5', 'I5', 'J5'],
];
return (
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
data={data}
autoWrapRow={true}
autoWrapCol={true}
width="auto"
height="auto"
rowHeaders={true}
colHeaders={true}
readOnly={false}
cell={[
{
// bottom-level cell options overwrite the top-level grid options
// apply only to a cell with coordinates (0, 0)
row: 0,
col: 0,
readOnly: true,
},
{
// bottom-level cell options overwrite the top-level grid options
// apply only to a cell with coordinates (1, 1)
row: 1,
col: 1,
readOnly: true,
},
]}
/>
);
};
export default ExampleComponent;
TypeScript
import { FC } from 'react';
import { HotTable, HotTableProps } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
import Handsontable from 'handsontable/base';
// register Handsontable's modules
registerAllModules();
const ExampleComponent: FC = () => {
const data: Handsontable.CellValue[][] = [
['A1', 'B1', 'C1', 'D1', 'E1', 'F1', 'G1', 'H1', 'I1', 'J1'],
['A2', 'B2', 'C2', 'D2', 'E2', 'F2', 'G2', 'H2', 'I2', 'J2'],
['A3', 'B3', 'C3', 'D3', 'E3', 'F3', 'G3', 'H3', 'I3', 'J3'],
['A4', 'B4', 'C4', 'D4', 'E4', 'F4', 'G4', 'H4', 'I4', 'J4'],
['A5', 'B5', 'C5', 'D5', 'E5', 'F5', 'G5', 'H5', 'I5', 'J5'],
];
return (
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
data={data}
autoWrapRow={true}
autoWrapCol={true}
width="auto"
height="auto"
rowHeaders={true}
colHeaders={true}
readOnly={false}
cell={[
{
// bottom-level cell options overwrite the top-level grid options
// apply only to a cell with coordinates (0, 0)
row: 0,
col: 0,
readOnly: true,
},
{
// bottom-level cell options overwrite the top-level grid options
// apply only to a cell with coordinates (1, 1)
row: 1,
col: 1,
readOnly: true,
},
]}
/>
);
};
export default ExampleComponent;

Read cell options

When Handsontable is running, you can check a cell’s current options, using the getCellMeta() method.

The getCellMeta() method returns an object with:

For example:

// Consider the HotTable component with the `cell` option declared:
<HotTable
cell={[
{
row: 1,
col: 1,
readOnly: true,
}
]}
/>;
// for cell (0, 0), the `readOnly` option is the default (`false`)
// returns `false`
hot.getCellMeta(0, 0).readOnly;
// for cell (1, 1), the `cell` option overwrote the default `readOnly` value
// returns `true`
hot.getCellMeta(1, 1).readOnly;

Change cell options

When Handsontable is running, you can change the initial cell options, using the setCellMeta() method.

For example:

// changes the `readOnly` option of cell (1, 1) back to `false`
hot.setCellMeta(1, 1, 'readOnly', false);
// returns `false`
hot.getCellMeta(1, 1).readOnly;

setCellMeta() updates a cell’s metadata but doesn’t repaint the grid on its own. To make a visual change appear — such as a new className, type, or readOnly state — call render() afterward. If you change several cells at once, wrap the calls in batch() so the grid renders only once.

Implement custom logic

You can apply configuration options to individual grid elements (columns, rows, cells), based on any logic you implement, using the cells option.

The cells option overwrites all other options.

Handsontable merges the object that cells returns into the cell’s meta. It doesn’t replace the meta. A key that the function returned before and doesn’t return now keeps its last value. For example, a cell stays readOnly: true after cells returns {}.

To avoid this, do one of the following:

  • Return the value for every key on every call. For example, return readOnly: false in the branch where the cell is editable.
  • Outside the cells function, call removeCellMeta() with the cell’s visual coordinates to remove the key. The key comes back if cells returns it again.

The meta resets in three cases:

  • Any updateSettings() call that carries cells, cell, or columns resets it. In React, that happens when you pass cells as a new function.
  • A loadData() call resets it. updateData() and updateSettings({ data }) don’t.
  • A row that scrolls more than one viewport out of view and back resets it, unless it is the row of the selected cell. Cells with meta you set with setCellMeta() or the cell option, and cells marked invalid, keep their meta. Horizontal scrolling doesn’t reset it.

For how cells merges its result, see The cells function.

The function can take three arguments:

  • row: a row coordinate (a physical index)
  • col: a column coordinate (a physical index)
  • prop: if your data is an array of objects, prop is a property name for a column’s data source object.
    If your data is an array of arrays, prop is the same as col.
<HotTable
cells={(row, col) => {
if ((row === 1 || row === 5) && col === 1) {
return {
readOnly: true,
};
}
}}
/>

The arrow function passed to cells does not bind this, so this.instance is not available inside it. To access the Handsontable instance, use the component’s ref: hotTableRef.current.hotInstance.

Example

In the example below, the modified cells options overwrite the top-level grid options.

// for cell (0, 0), the `readOnly` option is the default (`false`)
// returns `false`
hot.getCellMeta(0, 0).readOnly;
// for cell (1, 1), the `cell` option overwrote the default `readOnly` value
// returns `true`
hot.getCellMeta(1, 1).readOnly;
// changes the `readOnly` option of cell (1, 1) back to `false`
hot.setCellMeta(1, 1, 'readOnly', false);
// returns `false`
hot.getCellMeta(1, 1).readOnly;

Configuration example

In the example below, some cells are read-only, and some cells are editable:

  • By default, all cells are read-only (as set in the top-level grid options).
  • For the first column, the mid-level column options overwrite the top-level grid options.
    As a result, the first column cells are editable.
  • For cell A1 (0, 0), the bottom-level cell options overwrite both the mid-level column options, and the top-level grid options.
    As a result, cell A1 (0, 0) is read-only, despite being part of the editable first column.
  • For cell C3 (3, 3), the cells option overwrites all other options.
    As a result, cell C3 (3, 3) is editable, despite not being part of the editable first column.
JavaScript
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modules
registerAllModules();
const ExampleComponent = () => {
const data = [
['A1', 'B1', 'C1', 'D1', 'E1', 'F1', 'G1', 'H1', 'I1', 'J1'],
['A2', 'B2', 'C2', 'D2', 'E2', 'F2', 'G2', 'H2', 'I2', 'J2'],
['A3', 'B3', 'C3', 'D3', 'E3', 'F3', 'G3', 'H3', 'I3', 'J3'],
['A4', 'B4', 'C4', 'D4', 'E4', 'F4', 'G4', 'H4', 'I4', 'J4'],
['A5', 'B5', 'C5', 'D5', 'E5', 'F5', 'G5', 'H5', 'I5', 'J5'],
];
return (
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
data={data}
autoWrapRow={true}
autoWrapCol={true}
readOnly={true}
width="auto"
height="auto"
rowHeaders={true}
colHeaders={true}
columns={[
// each cell in the first (by physical index) column is editable
{ readOnly: false, className: '' },
{},
{},
{},
{},
{},
{},
{},
{},
{},
]}
cell={[
// cell (0, 0) is read-only
{ row: 0, col: 0, readOnly: true },
]}
cells={(row, col) => {
// cell (2, 2) is editable
if (row === 2 && col === 2) {
return { readOnly: false, className: '' };
}
return {};
}}
/>
);
};
export default ExampleComponent;
TypeScript
import { FC } from 'react';
import { HotTable, HotTableProps } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
import Handsontable from 'handsontable/base';
// register Handsontable's modules
registerAllModules();
const ExampleComponent: FC = () => {
const data: Handsontable.CellValue[][] = [
['A1', 'B1', 'C1', 'D1', 'E1', 'F1', 'G1', 'H1', 'I1', 'J1'],
['A2', 'B2', 'C2', 'D2', 'E2', 'F2', 'G2', 'H2', 'I2', 'J2'],
['A3', 'B3', 'C3', 'D3', 'E3', 'F3', 'G3', 'H3', 'I3', 'J3'],
['A4', 'B4', 'C4', 'D4', 'E4', 'F4', 'G4', 'H4', 'I4', 'J4'],
['A5', 'B5', 'C5', 'D5', 'E5', 'F5', 'G5', 'H5', 'I5', 'J5'],
];
return (
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
data={data}
autoWrapRow={true}
autoWrapCol={true}
readOnly={true}
width="auto"
height="auto"
rowHeaders={true}
colHeaders={true}
columns={[
// each cell in the first (by physical index) column is editable
{ readOnly: false, className: '' },
{},
{},
{},
{},
{},
{},
{},
{},
{},
]}
cell={[
// cell (0, 0) is read-only
{ row: 0, col: 0, readOnly: true },
]}
cells={(row: number, col: number) => {
// cell (2, 2) is editable
if (row === 2 && col === 2) {
return { readOnly: false, className: '' };
}
return {};
}}
/>
);
};
export default ExampleComponent;

Non-idempotent options

A non-idempotent option is one that produces different results when applied multiple times. In the context of Handsontable and <HotTable/> component, options like manualColumnMove=[1, 0] will swap columns every time they’re applied - first application swaps columns, second application swaps them back, third swaps again, and so on.

Problem

Non-idempotent options like manualColumnMove and manualRowMove cause unwanted visual changes on every React re-render because they operate on visual indexes.

// Problem: Columns swap on EVERY re-render
const ExampleComponent = () => {
const [state, setState] = React.useState(0);
return (
<>
<button onClick={() => setState(state + 1)}>{state}</button>
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
manualColumnMove={[1, 0]} // Columns keep swapping!
data={[['A', 'B'], [0, 1]]}
/>
</>
);
};

Solution

Use initialState to apply these options only during initialization:

<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
initialState={{
manualColumnMove: [1, 0] // Applied only once
}}
data={[['A', 'B'], [0, 1]]}
rowHeaders={true}
colHeaders={true}
/>

Result

Your grid now applies configuration options at the scope you specified — grid-wide, per column, per row, or per individual cell — using Handsontable’s cascading configuration system.

Configuration options

Core methods

Hooks