Skip to content

Cell type

Use Handsontable DataGrid’s built-in cell types such as autocomplete, date, time, and more, for consistent UI across cell renderer, editor, and validator.

Overview

There are three functions associated with every table cell: renderer, editor, and optionally validator. These functions are mostly used all together as they are strongly connected.

Example scenario - To store a date in a cell, you would:

  • Use a renderer to display the date using appropriate formatting dd/mm/yyyy, yyyy-mm-dd, etc.
  • Use an editor that displays a calendar instead of the default text input, allowing the user to easily pick the right date.
  • Use a validator to check if the value entered by a user is valid.

Cell type is represented by a string i.e. "text", "numeric", "date". Each string is internally mapped to functions associated with this type e.g., "numeric" type is associated with the following functions:

  • Handsontable.renderers.NumericRenderer
  • Handsontable.editors.TextEditor
  • Handsontable.validators.NumericValidator

When Handsontable encounters a cell with the type option defined, it checks which cell functions this type refers to and uses them. For example, when setting the column type to 'password':

columns={[{
type: 'password'
}]}

the functions editor, renderer, and copyable are automatically set as follows:

columns={[{
editor: Handsontable.editors.PasswordEditor
renderer: Handsontable.renderers.PasswordRenderer,
copyable: false,
}]}

Is an equivalent to defining them all:

columns={[{
editor: false,
renderer: Handsontable.renderers.TextRenderer,
className: 'my-cell',
readOnly: true,
myCustomProperty: 'foo',
}]}

Register custom cell type

When you create a custom cell type, best practice is to assign it as an alias that will refer to this particular type definition.

This gives users a convenient way of defining which cell type should be used for describing cell properties. The user doesn’t need to know which part of the code is responsible for rendering, validating, or editing the cell value. They do not even need to know that there are any functions at all. You can change the cell behavior associated with an alias without changing the code that defines a cell’s properties.

To register your own alias use Handsontable.cellTypes.registerCellType() function. It takes two arguments:

  • cellTypeName - a string representing the cell type object
  • type - an object represented by cellTypeName. It can include cell behavior callbacks, such as editor, renderer, and validator. It can also include Handsontable settings, such as readOnly, className, and allowInvalid, or custom properties, such as myCustomCellState, available through cellProperties.

If you’d like to register copyablePasswordType under alias copyable-password, you need to call:

Handsontable.cellTypes.registerCellType('copyable-password', {
editor: copyablePasswordEditor,
renderer: copyablePasswordRenderer,
});

Choose aliases wisely. If you register your cell type under name that is already registered, the target function will be overwritten:

Handsontable.cellTypes.registerCellType('password', {
editor: copyablePasswordEditor,
renderer: copyablePasswordRenderer,
});
// Now 'password' alias points to the newly created
// object, not Handsontable.cellTypes.password

Unless you intentionally want to overwrite an existing alias, try to choose a unique name. Best practice is to prefix your aliases with a custom name to minimize the possibility of name collisions. This is especially important if you want to publish your cell type as you never know what aliases have been registered by a user who uses your cell type.

Handsontable.cellTypes.registerCellType('copyable-password', {
editor: copyablePasswordEditor,
renderer: copyablePasswordRenderer,
});

Someone might already registered such alias. It would be better use a unique prefix:

Handsontable.cellTypes.registerCellType('my.copyable-password', {
editor: copyablePasswordEditor,
renderer: copyablePasswordRenderer,
});

To sum up, a well-prepared cell type object should look like this:

class MyEditor extends Handsontable.editors.TextEditor {}
function customRenderer(instance, td, row, column, prop, value, cellProperties) {
// ...renderer logic
}
function customValidator(query, callback) {
// ...validator logic
callback(/* Pass `true` or `false` */);
}
// Register an alias
Handsontable.cellTypes.registerCellType('my.custom', {
editor: MyEditor,
renderer: customRenderer,
validator: customValidator,
// You can add additional options to the cell type
// based on Handsontable settings
className: 'my-cell',
allowInvalid: true,
// Or you can add custom properties which
// will be accessible in `cellProperties`
myCustomCellState: 'complete',
});

Using an alias

The next step is to use the registered aliases to enable users to easily refer to them without the need to know what the actual cell type object is. Here’s an example of how you would use your cell definition:

<HotTable
ccolumns={[{
type: 'my.custom'
}]}
/>

Precedence

It is possible to define the type option together with options such as renderer, editor or validator. For example:

<HotTable
columns={[{
type: 'numeric',
// validator function defined elsewhere
validator: customValidator
}]}
/>

We defined thetype for all cells in a column to be numeric. We also defined a validator function directly. In Handsontable, cell functions that are defined directly always take precedence over functions associated with cell type, so the above configuration is equivalent to:

<HotTable
columns={[{
renderer: Handsontable.renderers.TextRenderer,
editor: Handsontable.editors.TextEditor,
validator: customValidator
}]}
/>

There is one more way you can define the configuration using types:

<HotTable
validator={customValidator}
columns={[{
type: 'my.custom'
}]}
/>

Using cascade configuration we define a table with two columns, with validator set to customValidator function. The stype of the first column is set to password. The Password cell type does not define a validator function:

{
renderer: Handsontable.renderers.PasswordRenderer,
editor: Handsontable.editors.PasswordEditor,
validator: undefined
}

Because type: 'password' is a more specific configuration for the cells in the first column than the validator: customValidator, cell functions associated with the password type take precedence over the functions defined on the higher level of configuration. Therefore, the equivalent configuration is:

function customValidator(query, callback) {
// ...validator logic
callback(/* Pass `true` or `false` */);
}
<HotTable
columns={[{
renderer: Handsontable.renderers.PasswordRenderer,
editor: Handsontable.editors.PasswordEditor,
validator: undefined
}, {
renderer: Handsontable.renderers.TextRenderer,
editor: Handsontable.editors.TextEditor,
validator: customValidator
},
/>;

Exception: editor: false

The editor option set to false is the one exception to this rule. editor: false doesn’t name an editor. It switches editing off, so a type set on a more specific level doesn’t re-enable editing. The type still applies its other functions, such as the renderer and the validator:

editor: false,
columns: [
// non-editable, but still rendered and validated as numeric
{ type: 'numeric' },
// editable: an `editor` set on the same level as the `type` opts the column back in
{ type: 'numeric', editor: 'numeric' }
]

A named editor isn’t an exception. For example, a grid-level editor: 'password' is still replaced by the editor of a column’s type.

Change the grid-level type at runtime

When you change the grid-level type with updateSettings(), the grid applies the new type’s editor, renderer, and validator, the same as a grid created with that type. The options of the previous type that the new type doesn’t set go back to their defaults. Cells that were already drawn also lose what the previous type’s renderer stored on them, such as the alignment class of the numeric type. The reset keeps the meta you set with setCellMeta() or the cell option. A className you set that way loses the classes the renderer added to it, such as htRight and htNumeric. It keeps the classes you chose. That includes an alignment you picked from the context menu or set yourself. If you read the rendered className with getCellMeta() and write it back, with or without an extra class, the renderer classes in it count as yours, and the cell keeps them. A property you write straight onto the object that getCellMeta() returns doesn’t survive the reset. The same goes for the Search results, so call query() again after the type change.

Any grid-level option you set earlier, or in the same call, keeps winning over the type. That includes an editor, a renderer, and a validator. An editor set to false keeps editing switched off, while the new type still supplies its renderer and validator. To let the type supply an option again, pass undefined for it (an option the grid was created with as undefined stays unset), or pass editor: true next to the new type. A column or cell with its own type isn’t affected. A type name that no cell type is registered under is ignored.

Built-in cell types example

The example below shows some of the built-in cell types, i.e. combinations of cell renderers and editors available in Handsontable. The example also shows the declaration of custom cell renderers, namely yellowRenderer and greenRenderer.

JavaScript
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
import { textRenderer } from 'handsontable/renderers/textRenderer';
// register Handsontable's modules
registerAllModules();
const data = [
{
id: 1,
name: 'Ted',
isActive: true,
color: 'orange',
date: '2015-01-01',
},
{ id: 2, name: 'John', isActive: false, color: 'black', date: null },
{ id: 3, name: 'Al', isActive: true, color: 'red', date: null },
{ id: 4, name: 'Ben', isActive: false, color: 'blue', date: null },
];
const ExampleComponent = () => {
const colors = ['yellow', 'red', 'orange', 'green', 'blue', 'gray', 'black', 'white'];
const yellowRenderer = (instance, td, ...rest) => {
textRenderer(instance, td, ...rest);
td.style.backgroundColor = 'yellow';
};
const greenRenderer = (instance, td, ...rest) => {
textRenderer(instance, td, ...rest);
td.style.backgroundColor = 'green';
};
return (
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
data={data}
colHeaders={true}
autoWrapRow={true}
autoWrapCol={true}
columns={[
{ data: 'id', type: 'text' },
// 'text' is default, you don't actually need to declare it
{ data: 'name', renderer: yellowRenderer },
// use default 'text' cell type but overwrite its renderer with yellowRenderer
{ data: 'isActive', type: 'checkbox' },
{
data: 'date',
type: 'intl-date',
locale: 'en-US',
dateFormat: { year: 'numeric', month: '2-digit', day: '2-digit' },
},
{ data: 'color', type: 'autocomplete', source: colors },
]}
cell={[{ row: 1, col: 0, renderer: greenRenderer }]}
cells={function (row, col) {
if (row === 0 && col === 0) {
this.renderer = greenRenderer;
return { renderer: this.renderer };
}
return {};
}}
height="auto"
/>
);
};
export default ExampleComponent;
TypeScript
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
import { textRenderer } from 'handsontable/renderers/textRenderer';
import { BaseRenderer } from 'handsontable/renderers';
// register Handsontable's modules
registerAllModules();
const data = [
{
id: 1,
name: 'Ted',
isActive: true,
color: 'orange',
date: '2015-01-01',
},
{ id: 2, name: 'John', isActive: false, color: 'black', date: null },
{ id: 3, name: 'Al', isActive: true, color: 'red', date: null },
{ id: 4, name: 'Ben', isActive: false, color: 'blue', date: null },
];
const ExampleComponent = () => {
const colors: string[] = ['yellow', 'red', 'orange', 'green', 'blue', 'gray', 'black', 'white'];
const yellowRenderer: BaseRenderer = (instance, td, ...rest) => {
textRenderer(instance, td, ...rest);
td.style.backgroundColor = 'yellow';
};
const greenRenderer: BaseRenderer = (instance, td, ...rest) => {
textRenderer(instance, td, ...rest);
td.style.backgroundColor = 'green';
};
return (
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
data={data}
colHeaders={true}
autoWrapRow={true}
autoWrapCol={true}
columns={[
{ data: 'id', type: 'text' },
// 'text' is default, you don't actually need to declare it
{ data: 'name', renderer: yellowRenderer },
// use default 'text' cell type but overwrite its renderer with yellowRenderer
{ data: 'isActive', type: 'checkbox' },
{ data: 'date', type: 'intl-date', locale: 'en-US', dateFormat: { year: 'numeric', month: '2-digit', day: '2-digit' } },
{ data: 'color', type: 'autocomplete', source: colors },
]}
cell={[{ row: 1, col: 0, renderer: greenRenderer }]}
cells={function (row, col) {
if (row === 0 && col === 0) {
this.renderer = greenRenderer;
return { renderer: this.renderer };
}
return {};
}}
height="auto"
/>
);
};
export default ExampleComponent;

Empty cells

It’s worth to mention that values such as '' (empty string), null and undefined are considered empty values. Cells with empty values are displayed in a similar way for most of the data types (see below).

The value of a cleared cell depends on how you cleared it. For every case, see Empty cell values.

A cell that you never filled in keeps the value it was loaded with, so it can differ from a cell you filled in and then cleared. To store one kind of empty value for every way of clearing a cell, set the emptyValue option.

JavaScript
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modules
registerAllModules();
const data = [
['empty string', '', '', '', '', ''],
['null', null, null, null, null, null],
['undefined', undefined, undefined, undefined, undefined, undefined],
['non-empty value', 'non-empty text', 13000, true, 'orange', 'password'],
];
const ExampleComponent = () => {
return (
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
autoWrapRow={true}
autoWrapCol={true}
data={data}
columnSorting={{
sortEmptyCells: true,
}}
columns={[
{
columnSorting: {
indicator: false,
headerAction: false,
compareFunctionFactory: function compareFunctionFactory() {
return function comparator() {
return 0; // Don't sort the first visual column.
};
},
},
readOnly: true,
},
{},
{
type: 'numeric',
locale: 'en-US',
numericFormat: {
style: 'currency',
currency: 'USD',
minimumFractionDigits: 2,
},
},
{ type: 'checkbox' },
{ type: 'dropdown', source: ['yellow', 'red', 'orange'] },
{ type: 'password' },
]}
preventOverflow="horizontal"
colHeaders={['value underneath', 'type:text', 'type:numeric', 'type:checkbox', 'type:dropdown', 'type:password']}
height="auto"
/>
);
};
export default ExampleComponent;
TypeScript
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modules
registerAllModules();
const data = [
['empty string', '', '', '', '', ''],
['null', null, null, null, null, null],
['undefined', undefined, undefined, undefined, undefined, undefined],
['non-empty value', 'non-empty text', 13000, true, 'orange', 'password'],
];
const ExampleComponent = () => {
return (
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
autoWrapRow={true}
autoWrapCol={true}
data={data}
columnSorting={{
sortEmptyCells: true,
}}
columns={[
{
columnSorting: {
indicator: false,
headerAction: false,
compareFunctionFactory: function compareFunctionFactory() {
return function comparator() {
return 0; // Don't sort the first visual column.
};
},
},
readOnly: true,
},
{},
{
type: 'numeric',
locale: 'en-US',
numericFormat: {
style: 'currency',
currency: 'USD',
minimumFractionDigits: 2,
},
},
{ type: 'checkbox' },
{ type: 'dropdown', source: ['yellow', 'red', 'orange'] },
{ type: 'password' },
]}
preventOverflow="horizontal"
colHeaders={[
'value underneath',
'type:text',
'type:numeric',
'type:checkbox',
'type:dropdown',
'type:password',
]}
height="auto"
/>
);
};
export default ExampleComponent;

Empty cells may be treated differently in different contexts, for example, the ColumnSorting plugin has sortEmptyCells option which is responsible for establishing whether empty cells should be sorted like non-empty cells.

Set different cell types in one column

Use the cells option to assign a different cell type to each row in a column. The following example creates a project settings form with dropdown, numeric, intl-date, checkbox, text, handsontable, and password cell types.

JavaScript
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
registerAllModules();
const projectMembers = [
['Ana García', 'Product Manager'],
['James Okafor', 'Senior Engineer'],
['Li Wei', 'UX Designer'],
];
const valueCellMeta = [
{ type: 'dropdown', source: ['Planning', 'In progress', 'Blocked'] },
{
type: 'numeric',
locale: 'en-US',
numericFormat: { style: 'currency', currency: 'USD', maximumFractionDigits: 0 },
},
{ type: 'intl-date', locale: 'en-US', dateFormat: { year: 'numeric', month: 'short', day: 'numeric' } },
{ type: 'checkbox' },
{ type: 'text' },
{
type: 'handsontable',
handsontable: {
colHeaders: ['Name', 'Role'],
autoColumnSize: true,
data: projectMembers,
getValue() {
const selection = this.getSelectedLast();
return this.getSourceDataAtCell(Math.max(selection?.[0] ?? 0, 0), 0);
},
},
},
{ type: 'password' },
];
const data = [
['Status', 'In progress'],
['Budget', 250000],
['Due date', '2026-09-30'],
['Approved', true],
['Project name', 'Website redesign'],
['Owner', 'Ana García'],
['Access code', 'release-2026'],
];
const ExampleComponent = () => (
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
data={data}
colHeaders={['Setting', 'Value']}
columns={[{ readOnly: true }, {}]}
cells={(row, col) => (col === 1 ? (valueCellMeta[row] ?? {}) : {})}
height="auto"
autoWrapRow={true}
autoWrapCol={true}
/>
);
export default ExampleComponent;
TypeScript
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
import type { CellMeta } from 'handsontable/settings';
registerAllModules();
const projectMembers = [
['Ana García', 'Product Manager'],
['James Okafor', 'Senior Engineer'],
['Li Wei', 'UX Designer'],
];
const valueCellMeta: CellMeta[] = [
{ type: 'dropdown', source: ['Planning', 'In progress', 'Blocked'] },
{
type: 'numeric',
locale: 'en-US',
numericFormat: { style: 'currency', currency: 'USD', maximumFractionDigits: 0 },
},
{ type: 'intl-date', locale: 'en-US', dateFormat: { year: 'numeric', month: 'short', day: 'numeric' } },
{ type: 'checkbox' },
{ type: 'text' },
{
type: 'handsontable',
handsontable: {
colHeaders: ['Name', 'Role'],
autoColumnSize: true,
data: projectMembers,
getValue() {
const selection = this.getSelectedLast();
return this.getSourceDataAtCell(Math.max(selection?.[0] ?? 0, 0), 0);
},
},
},
{ type: 'password' },
];
const data = [
['Status', 'In progress'],
['Budget', 250000],
['Due date', '2026-09-30'],
['Approved', true],
['Project name', 'Website redesign'],
['Owner', 'Ana García'],
['Access code', 'release-2026'],
];
const ExampleComponent = () => (
<HotTable
// licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
data={data}
colHeaders={['Setting', 'Value']}
columns={[{ readOnly: true }, {}]}
cells={(row, col) => (col === 1 ? (valueCellMeta[row] ?? {}) : {})}
height="auto"
autoWrapRow={true}
autoWrapCol={true}
/>
);
export default ExampleComponent;

Related guides

Configuration options

Core methods

Hooks