Cell functions

Render, edit, and validate cell contents using Handsontable’s three independent cell functions.

Overview

Every Handsontable cell has three associated functions that handle distinct concerns:

Function	Role	Implemented as
`renderer`	Controls how a cell looks: DOM structure, CSS classes, HTML content	A plain function
`editor`	Controls how a cell is edited: input element, keyboard handling, open/close lifecycle	A class extending `BaseEditor`
`validator`	Decides whether a cell value is acceptable	A function or `RegExp`

The three functions are independent. You can mix and match any combination: use the built-in numeric editor with a custom renderer, override just the validator while keeping a built-in type, or write all three from scratch.

Function signatures

1
// renderer — called for every visible cell on every render
2
renderer(hotInstance, td, row, col, prop, value, cellProperties)
3
// hotInstance  – Handsontable instance
4
// td           – HTMLTableCellElement to modify
5
// row, col     – visual row and column indexes
6
// prop         – data property name (string) or column index (number)
7
// value        – current cell value
8
// cellProperties – merged cell configuration object
9

10
// validator — may be synchronous or asynchronous
11
validator(value, callback)
12
// value    – value to validate
13
// callback – call with true (valid) or false (invalid)
14
// RegExp alternative: /pattern/.test(value) must return true
15

16
// editor — a class; see the Cell editor guide for the full lifecycle API
17
class MyEditor extends BaseEditor { ... }

validator is optional. If no validator is defined for a cell, the cell is skipped entirely during validation — afterValidate will not fire for it, and it will not contribute to the validation cycle.

`allowInvalid`

By default, allowInvalid: true — invalid cells are accepted into the data source but marked with the htInvalid CSS class. Set allowInvalid: false to reject invalid values and keep the editor open until a valid value is entered.

Cell types bundle all three

A cell type is a preset that assigns a matching renderer, editor, and validator together under a single type alias. Using type: 'numeric' is shorthand for:

1
{
2
  renderer:  Handsontable.renderers.NumericRenderer,
3
  editor:    Handsontable.editors.NumericEditor,
4
  validator: Handsontable.validators.NumericValidator,
5
}

Built-in types: text, numeric, checkbox, date, time, dropdown, autocomplete, password, handsontable.

When you set an explicit renderer, editor, or validator alongside a type, the explicit function always takes precedence over the type for that function only:

1
columns: [{
2
  type: 'numeric',      // sets NumericEditor + NumericValidator
3
  renderer: myRenderer, // overrides only NumericRenderer; editor and validator stay numeric
4
}]

When to use a type vs individual functions:

Use type when you want the standard, bundled behavior for a data kind (numbers, dates, checkboxes).
Override a single function from a type when one aspect needs customizing but the rest is fine as-is.
Set individual renderer/editor/validator directly when no built-in type fits or you need full control.

Configuration priority

Cell functions resolve using the cascading configuration model. The most specific level wins:

1
cell[row][col]  >  column  >  global (root settings)

1
new Handsontable(container, {
2
  type: 'text',               // global fallback for all cells
3
  columns: [
4
    { type: 'numeric' },      // overrides global for all cells in column 0
5
    { type: 'text' },         // same as global for column 1
6
  ],
7
  cell: [
8
    { row: 0, col: 0, type: 'checkbox' }, // overrides column setting for cell [0, 0] only
9
  ],
10
});

Mixing renderer, editor, and validator

The example below shows a product inventory table. Each column uses a different function configuration:

Product — type: 'text' bundles text renderer, text editor, and no validator.
Price — type: 'numeric' bundles numeric renderer (formatted as currency), numeric editor, and numeric validator.
Stock — custom renderer (progress bar), built-in 'numeric' editor, and a custom range validator. All three come from different sources.

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3

4
registerAllModules();
5

6
// Custom renderer: visualizes stock level as a progress bar with a numeric label.
7
// Demonstrates using a renderer independently from the editor and validator.
8
function stockRenderer(hotInstance, td, row, col, prop, value) {
9
  const num = parseInt(value, 10);
10
  const valid = !isNaN(num) && num >= 0;
11
  const pct = valid ? Math.min(100, (num / 1000) * 100) : 0;
12
  const color = pct > 60 ? '#22c55e' : pct > 20 ? '#f59e0b' : '#ef4444';
13

14
  td.innerText = '';
15

16
  const wrapper = hotInstance.rootDocument.createElement('div');
17

18
  wrapper.className = 'htStockBar';
19

20
  const track = hotInstance.rootDocument.createElement('div');
21

22
  track.className = 'htStockBarTrack';
23

24
  const fill = hotInstance.rootDocument.createElement('div');
25

26
  fill.className = 'htStockBarFill';
27
  fill.style.width = `${pct}%`;
28
  fill.style.background = color;
29

30
  const label = hotInstance.rootDocument.createElement('span');
31

32
  label.className = 'htStockBarLabel';
33
  label.innerText = valid ? `${num}` : '—';
34
  track.appendChild(fill);
35
  wrapper.appendChild(track);
36
  wrapper.appendChild(label);
37
  td.appendChild(wrapper);
38

39
  return td;
40
}
41

42
// Custom validator: accepts integers in the range 0–1000.
43
// Demonstrates using a validator independently from the renderer and editor.
44
function stockValidator(value, callback) {
45
  const num = Number(value);
46

47
  callback(Number.isInteger(num) && num >= 0 && num <= 1000);
48
}
49

50
const container = document.querySelector('#example1');
51

52
new Handsontable(container, {
53
  data: [
54
    ['Apple', 1.2, 820],
55
    ['Banana', 0.5, 280],
56
    ['Cherry', 3.0, 45],
57
    ['Mango', 2.5, 960],
58
    ['Pear', 0.8, 170],
59
    ['Blueberry', 4.5, 15],
60
  ],
61
  colHeaders: ['Product', 'Price', 'Stock'],
62
  columns: [
63
    // Built-in type bundles renderer + editor + no validator
64
    { type: 'text' },
65
    // Built-in type bundles renderer + editor + validator with custom format
66
    {
67
      type: 'numeric',
68
      locale: 'en-US',
69
      numericFormat: { style: 'currency', currency: 'USD', minimumFractionDigits: 2 },
70
    },
71
    // Mixed: custom renderer, built-in numeric editor, custom validator
72
    {
73
      renderer: stockRenderer,
74
      editor: 'numeric',
75
      validator: stockValidator,
76
      allowInvalid: false,
77
    },
78
  ],
79
  colWidths: [120, 90, 200],
80
  rowHeaders: true,
81
  height: 'auto',
82
  autoWrapRow: true,
83
  autoWrapCol: true,
84
  licenseKey: 'non-commercial-and-evaluation',
85
});

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3

4
registerAllModules();
5

6
// Custom renderer: visualizes stock level as a progress bar with a numeric label.
7
// Demonstrates using a renderer independently from the editor and validator.
8
function stockRenderer(
9
  hotInstance: Handsontable.Core,
10
  td: HTMLTableCellElement,
11
  row: number,
12
  col: number,
13
  prop: string | number,
14
  value: any
15
): HTMLTableCellElement {
16
  const num = parseInt(value as string, 10);
17
  const valid = !isNaN(num) && num >= 0;
18
  const pct = valid ? Math.min(100, (num / 1000) * 100) : 0;
19
  const color = pct > 60 ? '#22c55e' : pct > 20 ? '#f59e0b' : '#ef4444';
20

21
  td.innerText = '';
22

23
  const wrapper = hotInstance.rootDocument.createElement('div');
24

25
  wrapper.className = 'htStockBar';
26

27
  const track = hotInstance.rootDocument.createElement('div');
28

29
  track.className = 'htStockBarTrack';
30

31
  const fill = hotInstance.rootDocument.createElement('div');
32

33
  fill.className = 'htStockBarFill';
34
  fill.style.width = `${pct}%`;
35
  fill.style.background = color;
36

37
  const label = hotInstance.rootDocument.createElement('span');
38

39
  label.className = 'htStockBarLabel';
40
  label.innerText = valid ? `${num}` : '—';
41
  track.appendChild(fill);
42
  wrapper.appendChild(track);
43
  wrapper.appendChild(label);
44
  td.appendChild(wrapper);
45

46
  return td;
47
}
48

49
// Custom validator: accepts integers in the range 0–1000.
50
// Demonstrates using a validator independently from the renderer and editor.
51
function stockValidator(value: any, callback: (valid: boolean) => void): void {
52
  const num = Number(value);
53

54
  callback(Number.isInteger(num) && num >= 0 && num <= 1000);
55
}
56

57
const container = document.querySelector('#example1') as HTMLElement;
58

59
new Handsontable(container, {
60
  data: [
61
    ['Apple', 1.2, 820],
62
    ['Banana', 0.5, 280],
63
    ['Cherry', 3.0, 45],
64
    ['Mango', 2.5, 960],
65
    ['Pear', 0.8, 170],
66
    ['Blueberry', 4.5, 15],
67
  ],
68
  colHeaders: ['Product', 'Price', 'Stock'],
69
  columns: [
70
    // Built-in type bundles renderer + editor + no validator
71
    { type: 'text' },
72
    // Built-in type bundles renderer + editor + validator with custom format
73
    { type: 'numeric', locale: 'en-US', numericFormat: { style: 'currency', currency: 'USD', minimumFractionDigits: 2 } },
74
    // Mixed: custom renderer, built-in numeric editor, custom validator
75
    {
76
      renderer: stockRenderer,
77
      editor: 'numeric',
78
      validator: stockValidator,
79
      allowInvalid: false,
80
    } as any,
81
  ],
82
  colWidths: [120, 90, 200],
83
  rowHeaders: true,
84
  height: 'auto',
85
  autoWrapRow: true,
86
  autoWrapCol: true,
87
  licenseKey: 'non-commercial-and-evaluation',
88
});

1
.htStockBar {
2
  display: flex;
3
  align-items: center;
4
  gap: 6px;
5
  padding: 0 4px;
6
  height: 100%;
7
  box-sizing: border-box;
8
}
9

10
.htStockBarTrack {
11
  flex: 1;
12
  height: 8px;
13
  background: #e5e7eb;
14
  border-radius: 4px;
15
  overflow: hidden;
16
}
17

18
.htStockBarFill {
19
  height: 100%;
20
  border-radius: 4px;
21
  min-width: 2px;
22
}
23

24
.htStockBarLabel {
25
  font-size: 11px;
26
  font-variant-numeric: tabular-nums;
27
  min-width: 28px;
28
  text-align: right;
29
  white-space: nowrap;
30
}

Double-click any Stock cell to edit it with the numeric editor. The bar renderer updates on save. Enter a value outside 0–1000 to see the validator reject it (cell turns red when allowInvalid: false).

Performance

Renderers are called separately for every displayed cell on every table render. A table can render many times during its lifetime — after scrolling, sorting, editing, and more. Keep renderer functions as simple and fast as possible to avoid performance drops, especially with large datasets.

Getting cell functions programmatically

Use getCellMeta(row, col) to read all properties of a cell at once, or the dedicated getters for individual functions:

1
const cellProperties = hot.getCellMeta(0, 0);
2

3
cellProperties.renderer;   // renderer function
4
cellProperties.editor;     // editor class
5
cellProperties.validator;  // validator function or RegExp
6
cellProperties.type;       // cell type string

Dedicated getters:

Method	Returns
`getCellRenderer(row, col)`	The resolved renderer function for the cell
`getCellEditor(row, col)`	The resolved editor class for the cell
`getCellValidator(row, col)`	The resolved validator function or `RegExp` for the cell

If a cell’s functions are defined through a cell type, the getters return the resolved functions, not the type string:

1
const hot = new Handsontable(container, {
2
  columns: [{ type: 'numeric' }],
3
});
4

5
const cellProperties = hot.getCellMeta(0, 0);
6

7
cellProperties.renderer;   // numericRenderer function
8
cellProperties.editor;     // NumericEditor class
9
cellProperties.validator;  // numericValidator function
10
cellProperties.type;       // 'numeric'