Cell editor

Create custom cell editors to fully control how values are entered in your data grid.

Each cell can have one editor — a class that manages the editor’s DOM element, its value, and the lifecycle from opening to saving. Handsontable’s EditorManager selects and drives the editor automatically. You create editors by extending BaseEditor or any of the built-in editor classes.

Component-based editors

Use React components as editors with the useHotEditor hook. The hook returns value, setValue, and finishEditing, plus callbacks for the editor lifecycle (onOpen, onClose, onPrepare, onFocus).

To prevent the editor from closing when clicked (due to outsideClickDeselects), call event.stopPropagation() on the mousedown event of the editor’s root element.

1
import { useRef } from 'react';
2
import { HotTable, HotColumn, useHotEditor } from '@handsontable/react-wrapper';
3

4
const EditorComponent = () => {
5
  const mainElementRef = useRef(null);
6
  const { value, setValue, finishEditing } = useHotEditor({
7
    onOpen: () => {
8
      if (!mainElementRef.current) return;
9
      mainElementRef.current.style.display = 'block';
10
    },
11
    onClose: () => {
12
      if (!mainElementRef.current) return;
13
      mainElementRef.current.style.display = 'none';
14
    },
15
    onPrepare: (_row, _column, _prop, TD, _originalValue, _cellProperties) => {
16
      const tdPosition = TD.getBoundingClientRect();
17

18
      // As the `prepare` method is triggered after selecting
19
      // any cell, we're updating the styles for the editor element,
20
      // so it shows up in the correct position.
21
      if (!mainElementRef.current) return;
22
      mainElementRef.current.style.left = `${tdPosition.left + window.pageXOffset}px`;
23
      mainElementRef.current.style.top = `${tdPosition.top + window.pageYOffset}px`;
24
    },
25
    onFocus: () => {},
26
  });
27

28
  const setLowerCase = () => {
29
    setValue(value.toString().toLowerCase());
30
    finishEditing();
31
  };
32

33
  const setUpperCase = () => {
34
    setValue(value.toString().toUpperCase());
35
    finishEditing();
36
  };
37

38
  const stopMousedownPropagation = (e) => {
39
    e.stopPropagation();
40
  };
41

42
  const buttonValue = value || '';
43

44
  return (
45
    <div
46
      id="editorElement"
47
      ref={mainElementRef}
48
      style={{
49
        display: 'none',
50
        position: 'absolute',
51
        left: 0,
52
        top: 0,
53
        background: '#fff',
54
        border: '1px solid #000',
55
        padding: '15px',
56
        zIndex: 999,
57
      }}
58
      onMouseDown={stopMousedownPropagation}
59
    >
60
      <button onClick={setLowerCase.bind(this)}>{buttonValue.toLowerCase()}</button>
61
      <button onClick={setUpperCase.bind(this)}>{buttonValue.toUpperCase()}</button>
62
    </div>
63
  );
64
};
65

66
const data = [
67
  ['Obrien Fischer'],
68
  ['Alexandria Gordon'],
69
  ['John Stafford'],
70
  ['Regina Waters'],
71
  ['Kay Bentley'],
72
  ['Emerson Drake'],
73
  ['Dean Stapleton'],
74
];
75

76
const ExampleComponent = () => {
77
  return (
78
    <HotTable
79
      data={data}
80
      rowHeaders={true}
81
      autoWrapRow={true}
82
      autoWrapCol={true}
83
      height="auto"
84
      licenseKey="non-commercial-and-evaluation"
85
    >
86
      <HotColumn width={250} editor={EditorComponent} />
87
    </HotTable>
88
  );
89
};
90

91
export default ExampleComponent;

1
import { MouseEvent, useRef } from 'react';
2
import { HotTable, HotColumn, useHotEditor } from '@handsontable/react-wrapper';
3

4
const EditorComponent = () => {
5
  const mainElementRef = useRef<HTMLDivElement>(null);
6

7
  const { value, setValue, finishEditing } = useHotEditor({
8
    onOpen: () => {
9
      if (!mainElementRef.current) return;
10

11
      mainElementRef.current.style.display = 'block';
12
    },
13
    onClose: () => {
14
      if (!mainElementRef.current) return;
15

16
      mainElementRef.current.style.display = 'none';
17
    },
18
    onPrepare: (_row, _column, _prop, TD, _originalValue, _cellProperties) => {
19
      const tdPosition = TD.getBoundingClientRect();
20

21
      // As the `prepare` method is triggered after selecting
22
      // any cell, we're updating the styles for the editor element,
23
      // so it shows up in the correct position.
24
      if (!mainElementRef.current) return;
25
      mainElementRef.current.style.left = `${tdPosition.left + window.pageXOffset}px`;
26
      mainElementRef.current.style.top = `${tdPosition.top + window.pageYOffset}px`;
27
    },
28
    onFocus: () => {},
29
  });
30

31
  const setLowerCase = () => {
32
    setValue(value.toString().toLowerCase());
33
    finishEditing();
34
  };
35

36
  const setUpperCase = () => {
37
    setValue(value.toString().toUpperCase());
38
    finishEditing();
39
  };
40

41
  const stopMousedownPropagation = (e: MouseEvent) => {
42
    e.stopPropagation();
43
  };
44

45
  const buttonValue = value || '';
46

47
  return (
48
    <div
49
      id="editorElement"
50
      ref={mainElementRef}
51
      style={{
52
        display: 'none',
53
        position: 'absolute',
54
        left: 0,
55
        top: 0,
56
        background: '#fff',
57
        border: '1px solid #000',
58
        padding: '15px',
59
        zIndex: 999,
60
      }}
61
      onMouseDown={stopMousedownPropagation}
62
    >
63
      <button onClick={setLowerCase.bind(this)}>{buttonValue.toLowerCase()}</button>
64
      <button onClick={setUpperCase.bind(this)}>{buttonValue.toUpperCase()}</button>
65
    </div>
66
  );
67
};
68

69
const data = [
70
  ['Obrien Fischer'],
71
  ['Alexandria Gordon'],
72
  ['John Stafford'],
73
  ['Regina Waters'],
74
  ['Kay Bentley'],
75
  ['Emerson Drake'],
76
  ['Dean Stapleton'],
77
];
78

79
const ExampleComponent = () => {
80
  return (
81
    <HotTable
82
      data={data}
83
      rowHeaders={true}
84
      autoWrapRow={true}
85
      autoWrapCol={true}
86
      height="auto"
87
      licenseKey="non-commercial-and-evaluation"
88
    >
89
      <HotColumn width={250} editor={EditorComponent} />
90
    </HotTable>
91
  );
92
};
93

94
export default ExampleComponent;

Class-based editors

Declare the editor as a class that extends a built-in editor (e.g., TextEditor) and pass it to the editor option in column configuration.

1
import { HotTable } from '@handsontable/react-wrapper';
2
import { TextEditor } from 'handsontable/editors/textEditor';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
class CustomEditor extends TextEditor {
9
  createElements() {
10
    super.createElements();
11
    this.TEXTAREA = document.createElement('input');
12
    this.TEXTAREA.setAttribute('placeholder', 'Custom placeholder');
13
    this.TEXTAREA.setAttribute('data-hot-input', 'true');
14
    this.textareaStyle = this.TEXTAREA.style;
15
    this.TEXTAREA_PARENT.innerText = '';
16
    this.TEXTAREA_PARENT.appendChild(this.TEXTAREA);
17
  }
18
}
19

20
const ExampleComponent = () => {
21
  return (
22
    <HotTable
23
      id="hot"
24
      startRows={5}
25
      columns={[
26
        {
27
          editor: CustomEditor,
28
        },
29
      ]}
30
      colHeaders={true}
31
      colWidths={200}
32
      autoWrapRow={true}
33
      autoWrapCol={true}
34
      height="auto"
35
      licenseKey="non-commercial-and-evaluation"
36
    />
37
  );
38
};
39

40
export default ExampleComponent;

1
import { HotTable } from '@handsontable/react-wrapper';
2
import { TextEditor } from 'handsontable/editors/textEditor';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
class CustomEditor extends TextEditor {
9
  createElements() {
10
    super.createElements();
11

12
    this.TEXTAREA = document.createElement('input');
13
    this.TEXTAREA.setAttribute('placeholder', 'Custom placeholder');
14
    this.TEXTAREA.setAttribute('data-hot-input', 'true');
15
    this.textareaStyle = this.TEXTAREA.style;
16
    this.TEXTAREA_PARENT.innerText = '';
17
    this.TEXTAREA_PARENT.appendChild(this.TEXTAREA);
18
  }
19
}
20

21
const ExampleComponent = () => {
22
  return (
23
    <HotTable
24
      id="hot"
25
      startRows={5}
26
      columns={[
27
        {
28
          editor: CustomEditor,
29
        },
30
      ]}
31
      colHeaders={true}
32
      colWidths={200}
33
      autoWrapRow={true}
34
      autoWrapCol={true}
35
      height="auto"
36
      licenseKey="non-commercial-and-evaluation"
37
    />
38
  );
39
};
40

41
export default ExampleComponent;

How editing works

Handsontable separates rendering (displaying cell values) from editing (changing them). Renderers are stateless functions; editors are stateful classes that own a DOM element and manage the full editing flow.

EditorManager lifecycle

EditorManager orchestrates all editors. For each cell interaction it runs four steps in order:

Step	When it runs	What it does
Select editor	Cell is selected	Looks up the editor class from the `editor` config option
Prepare	Cell is selected	Calls `prepare()` to configure the editor for the selected cell
Open	User triggers editing	Fires `beforeBeginEditing` (return `false` to cancel), then calls `beginEditing()` → `open()`
Close	User confirms or cancels	Calls `finishEditing()` → `close()` or `focus()`

Editing opens on: Enter, Shift+Enter, F2, double-click.

Preventing the editor from opening: Use the beforeBeginEditing hook to conditionally cancel editor opening. Return false from the hook callback to prevent the editor from opening. Returning undefined (or any non-boolean value) applies the default behavior, which disallows opening for non-contiguous selections (Ctrl/Cmd+click) and multi-cell selections (Shift+click). Returning true removes those restrictions.

Editing closes on:

Key / action	Result
Click another cell	Saves changes
`Enter` / `Shift`+`Enter`	Saves and moves selection down / up
`Tab` / `Shift`+`Tab`	Saves and moves selection right / left
`Ctrl`/`Cmd`+`Enter` or `Alt`/`Option`+`Enter`	Inserts a line break
`Page Up` / `Page Down`	Saves and scrolls one screen
`Escape`	Cancels without saving

Overriding keyboard behavior: Register a beforeKeyDown hook listener and call event.stopImmediatePropagation() to prevent EditorManager from processing a specific key. Register the listener in open() and remove it in close() so it only intercepts events while your editor is active.

Editor singleton: Each editor class has exactly one instance per table. The constructor and init() run once per table; prepare() runs every time the user selects a cell that uses that editor.

BaseEditor API

All custom editors extend Handsontable.editors.BaseEditor. In an ESM project, import it from handsontable/editors/baseEditor. In a script-tag (UMD) project, access it as Handsontable.editors.BaseEditor.

Common methods

These methods are already implemented in BaseEditor. Override them only when necessary — always call super.method() first when you do.

Method	Description
`prepare()`	Configures the editor for the selected cell. Sets `this.row`, `this.col`, `this.prop`, `this.TD`, and `this.cellProperties`. Parameters: `(row, col, prop, td, originalValue, cellProperties)`.
`beginEditing()`	Sets the initial editor value and calls `open()`. Uses the original cell value when `newInitialValue` is `undefined`. Parameters: `(newInitialValue, event)`.
`finishEditing()`	Validates and saves the value, or restores the original when `restoreOriginalValue` is `true`. When `ctrlDown` is `true`, applies the value to all selected cells. Calls `close()` on success or `focus()` when validation fails. Parameters: `(restoreOriginalValue?, ctrlDown?, callback?)`.
`discardEditor()`	Called after validation. If valid, calls `close()`; if invalid, calls `focus()` to keep the editor open. Parameter: `(result)`.
`saveValue()`	Validates and saves `value`. Applies to all selected cells when `ctrlDown` is `true`. Parameters: `(value, ctrlDown)`.
`isOpened()`	Returns `true` if the editor is currently open.
`extend()`	Returns a new subclass of the current editor. Overriding methods on the returned class does not affect the original. Useful for ES5 environments; in ES6+ prefer `class MyEditor extends BaseEditor {}`.

Abstract methods

You must implement all of these in your custom editor class.

Method	Description
`init()`	Called once when the editor object is created. Build the editor’s DOM here.
`getValue()`	Returns the current editor value to be saved as the new cell value.
`setValue()`	Updates the editor to display the new value. Parameter: `(newValue)`.
`open()`	Shows the editor.
`close()`	Hides the editor after editing ends.
`focus()`	Focuses the editor input. Called when validation fails and the editor must stay open.

Editor instance properties

Available as this.property inside any editor method.

Property	Type	Description
`hot`	`Handsontable.Core`	The Handsontable instance this editor belongs to. Set once in the constructor; never changes.
`row`	`number`	Visual row index of the active cell. Updated by `prepare()`.
`col`	`number`	Visual column index of the active cell. Updated by `prepare()`.
`prop`	`string`	Data property name for the active cell (for object data sources). Updated by `prepare()`.
`TD`	`HTMLTableCellElement`	DOM node of the active cell. Updated by `prepare()`.
`cellProperties`	`object`	Configuration of the active cell. Updated by `prepare()`. Includes all standard cell options and any custom properties (e.g., `selectOptions`).

Built-in editors

Alias	Editor class
`autocomplete`	`Handsontable.editors.AutocompleteEditor`
`checkbox`	`Handsontable.editors.CheckboxEditor`
`date`	`Handsontable.editors.DateEditor`
`dropdown`	`Handsontable.editors.DropdownEditor`
`handsontable`	`Handsontable.editors.HandsontableEditor`
`numeric`	`Handsontable.editors.NumericEditor`
`password`	`Handsontable.editors.PasswordEditor`
`select`	`Handsontable.editors.SelectEditor`
`text`	`Handsontable.editors.TextEditor`
`time`	`Handsontable.editors.TimeEditor`

Creating a custom editor

Two approaches are available:

Extend an existing editor when you want most of its behavior and only need to change a few details (e.g., swap the input element type).
Extend BaseEditor directly when you need an entirely different UI (e.g., a dropdown list, a date picker, a color picker).

Extending an existing editor

Override only the methods you need. The PasswordEditor below extends TextEditor and replaces the <textarea> with <input type="password">. Since both elements share the same DOM API, only createElements() needs to change.

1
import { HotTable } from '@handsontable/react-wrapper';
2
import { TextEditor } from 'handsontable/editors/textEditor';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
class CustomEditor extends TextEditor {
9
  createElements() {
10
    super.createElements();
11
    this.TEXTAREA = document.createElement('input');
12
    this.TEXTAREA.setAttribute('placeholder', 'Custom placeholder');
13
    this.TEXTAREA.setAttribute('data-hot-input', 'true');
14
    this.textareaStyle = this.TEXTAREA.style;
15
    this.TEXTAREA_PARENT.innerText = '';
16
    this.TEXTAREA_PARENT.appendChild(this.TEXTAREA);
17
  }
18
}
19

20
const ExampleComponent = () => {
21
  return (
22
    <HotTable
23
      id="hot"
24
      startRows={5}
25
      columns={[
26
        {
27
          editor: CustomEditor,
28
        },
29
      ]}
30
      colHeaders={true}
31
      colWidths={200}
32
      autoWrapRow={true}
33
      autoWrapCol={true}
34
      height="auto"
35
      licenseKey="non-commercial-and-evaluation"
36
    />
37
  );
38
};
39

40
export default ExampleComponent;

1
import { HotTable } from '@handsontable/react-wrapper';
2
import { TextEditor } from 'handsontable/editors/textEditor';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
class CustomEditor extends TextEditor {
9
  createElements() {
10
    super.createElements();
11

12
    this.TEXTAREA = document.createElement('input');
13
    this.TEXTAREA.setAttribute('placeholder', 'Custom placeholder');
14
    this.TEXTAREA.setAttribute('data-hot-input', 'true');
15
    this.textareaStyle = this.TEXTAREA.style;
16
    this.TEXTAREA_PARENT.innerText = '';
17
    this.TEXTAREA_PARENT.appendChild(this.TEXTAREA);
18
  }
19
}
20

21
const ExampleComponent = () => {
22
  return (
23
    <HotTable
24
      id="hot"
25
      startRows={5}
26
      columns={[
27
        {
28
          editor: CustomEditor,
29
        },
30
      ]}
31
      colHeaders={true}
32
      colWidths={200}
33
      autoWrapRow={true}
34
      autoWrapCol={true}
35
      height="auto"
36
      licenseKey="non-commercial-and-evaluation"
37
    />
38
  );
39
};
40

41
export default ExampleComponent;

Building an editor from scratch

Extend BaseEditor directly for full control. The SelectEditor below renders a <select> dropdown. It also overrides keyboard behavior so Arrow Up / Arrow Down cycle through options rather than closing the editor.

Key implementation decisions:

init() - DOM is created here (runs once), not in prepare() or open().
data-hot-input="true" - Required on the editor element. Without it, Handsontable treats clicks on the editor as clicks outside it and closes the editor immediately.
prepare() - Options are populated here so each cell can have its own list via selectOptions.
open() / close() - The beforeKeyDown hook is registered when opening and cleared when closing, scoping key interception to this editor only.

To use a class-based editor from scratch in React, pass the editor class as the editor prop in a column configuration object. See the class-based editors section for an example.

Registering an editor

Register your editor under a string alias so it can be referenced by name in configuration instead of passing the class directly:

1
Handsontable.editors.registerEditor('myEditor', MyEditor);

After registration, use the alias in column configuration:

1
<HotTable columns={[{ editor: 'myEditor' }]} />

To reuse the same editor component across multiple columns, import and pass it wherever it is needed:

1
import { MySelectEditor } from './MySelectEditor';
2

3
<HotTable>
4
  <HotColumn editor={MySelectEditor} />
5
  <HotColumn editor={MySelectEditor} />
6
</HotTable>

Handsontable defines these aliases by default: autocomplete, base, checkbox, date, dropdown, handsontable, numeric, password, select, text, time.

Choose a unique alias (e.g., 'myorg.select') to avoid overwriting built-in editors. Registering under an existing alias silently overwrites the previous mapping.

Publishing a custom editor

If you intend to distribute your editor as a library, two extra steps make it easy for others to discover and extend it.

Step 1: Register the alias (covered above) so users can reference the editor by name:

1
Handsontable.editors.registerEditor('myorg.select', MySelectEditor);

Step 2: Expose the class on Handsontable.editors so users can retrieve and extend it without importing from your source module:

1
Handsontable.editors.MySelectEditor = MySelectEditor;

To extend a published editor, retrieve it with getEditor():

1
const MySelectEditor = Handsontable.editors.getEditor('myorg.select');
2

3
class ExtendedSelectEditor extends MySelectEditor {
4
  // override methods as needed
5
}

Windows	macOS	Action	Excel	Sheets
Arrow keys	Arrow keys	Move the cursor through the text	✓	✓
Alphanumeric keys	Alphanumeric keys	Enter the pressed key’s value into the cell	✓	✓
`Enter`	`Enter`	Complete the cell entry and move to the cell below	✓	✓
`Shift`+`Enter`	`Shift`+`Enter`	Complete the cell entry and move to the cell above	✓	✓
`Tab`	`Tab`	Complete the cell entry and move to the next cell^*	✓	✓
`Shift`+`Tab`	`Shift`+`Tab`	Complete the cell entry and move to the previous cell^*	✓	✓
`Delete`	`Delete`	Delete one character after the cursor^*	✓	✓
`Backspace`	`Backspace`	Delete one character before the cursor^*	✓	✓
`Home`	`Home`	Move the cursor to the beginning of the text^*	✓	✓
`End`	`End`	Move the cursor to the end of the text^*	✓	✓
`Ctrl` + Arrow keys	`Cmd` + Arrow keys	Move the cursor to the beginning or to the end of the text	✓	✓
`Ctrl`+`Shift` + Arrow keys	`Cmd`+`Shift` + Arrow keys	Extend the selection to the beginning or to the end of the text	✓	✓
`Page Up`	`Page Up`	Complete the cell entry and move one screen up	✓	✓
`Page Down`	`Page Down`	Complete the cell entry and move one screen down	✓	✓
`Alt`+`Enter`	`Option`+`Enter`	Insert a line break	✗	✓
`Ctrl`+`Enter`	`Ctrl`/`Cmd`+`Enter`	Insert a line break	✗	✓
`Escape`	`Escape`	Cancel the cell entry and exit the editing mode	✓	✓

^* This action depends on your layout direction.

APIs

BasePlugin

Configuration options

Core methods

Hooks

Cell editor

Cell editor

Component-based editors

Class-based editors

How editing works

EditorManager lifecycle

BaseEditor API

Common methods

Abstract methods

Editor instance properties

Built-in editors

Creating a custom editor

Extending an existing editor

Building an editor from scratch

Registering an editor

Publishing a custom editor

Related keyboard shortcuts

Related API reference