Programmatic row operations

In this tutorial, you will add, delete, and reorder rows in Handsontable using external toolbar buttons. You will learn how to wire buttons to the alter() API and the ManualRowMove plugin to give users full programmatic control over row order.

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

4
registerAllModules();
5

6
/* start:skip-in-preview */
7
const data = [
8
  ['Migrate auth service to OAuth 2.0', 'Alice Johnson', 'High', 'In Progress'],
9
  ['Write API documentation', 'Bob Smith', 'Normal', 'To Do'],
10
  ['Fix pagination bug on dashboard', 'Carol White', 'High', 'In Review'],
11
  ['Add CSV export feature', 'David Lee', 'Normal', 'To Do'],
12
  ['Upgrade React to v19', 'Eve Martinez', 'Low', 'Backlog'],
13
  ['Implement dark mode toggle', 'Frank Brown', 'Normal', 'In Progress'],
14
  ['Set up end-to-end test suite', 'Grace Kim', 'High', 'To Do'],
15
  ['Refactor database connection pool', 'Henry Wilson', 'Low', 'Backlog'],
16
];
17
/* end:skip-in-preview */
18

19
const container = document.querySelector('#example1');
20

21
const toolbar = document.createElement('div');
22

23
toolbar.classList.add('example-controls-container');
24
toolbar.innerHTML = `
25
  <div class="controls">
26
    <button id="btn-add-row" type="button">Add Row</button>
27
    <button id="btn-delete-row" type="button">Delete Row</button>
28
    <button id="btn-move-up" type="button">Move Up</button>
29
    <button id="btn-move-down" type="button">Move Down</button>
30
  </div>
31
`;
32
container.before(toolbar);
33

34
const hot = new Handsontable(container, {
35
  data,
36
  colHeaders: ['Task', 'Assignee', 'Priority', 'Status'],
37
  rowHeaders: true,
38
  height: 'auto',
39
  width: '100%',
40
  manualRowMove: true,
41
  // Keep the grid selected when clicking toolbar buttons. Without this,
42
  // Handsontable treats toolbar clicks as outside clicks and deselects,
43
  // which clears selectedRow before the button's click handler runs.
44
  outsideClickDeselects(target) {
45
    return !toolbar.contains(target);
46
  },
47
  licenseKey: 'non-commercial-and-evaluation',
48
});
49

50
const btnAddRow = toolbar.querySelector('#btn-add-row');
51
const btnDeleteRow = toolbar.querySelector('#btn-delete-row');
52
const btnMoveUp = toolbar.querySelector('#btn-move-up');
53
const btnMoveDown = toolbar.querySelector('#btn-move-down');
54

55
let selectedRow = null;
56

57
function updateButtonStates() {
58
  const hasSelection = selectedRow !== null;
59
  const isFirst = selectedRow === 0;
60
  const isLast = selectedRow === hot.countRows() - 1;
61

62
  btnDeleteRow.disabled = !hasSelection;
63
  btnMoveUp.disabled = !hasSelection || isFirst;
64
  btnMoveDown.disabled = !hasSelection || isLast;
65
}
66

67
hot.addHook('afterSelectionEnd', (row, col, row2) => {
68
  selectedRow = row === row2 ? Math.min(row, row2) : null;
69
  updateButtonStates();
70
});
71

72
hot.addHook('afterDeselect', () => {
73
  selectedRow = null;
74
  updateButtonStates();
75
});
76

77
btnAddRow.addEventListener('click', () => {
78
  hot.alter('insert_row_below', hot.countRows() - 1);
79
});
80

81
btnDeleteRow.addEventListener('click', () => {
82
  const selected = hot.getSelected();
83

84
  if (!selected) {
85
    return;
86
  }
87

88
  const rowSet = new Set();
89

90
  selected.forEach(([r1, , r2]) => {
91
    const from = Math.min(r1, r2);
92
    const to = Math.max(r1, r2);
93

94
    for (let r = from; r <= to; r++) {
95
      rowSet.add(r);
96
    }
97
  });
98

99
  const rows = [...rowSet].sort((a, b) => b - a);
100

101
  rows.forEach(row => hot.alter('remove_row', row, 1));
102
  updateButtonStates();
103
});
104

105
btnMoveUp.addEventListener('click', () => {
106
  if (selectedRow === null || selectedRow === 0) {
107
    return;
108
  }
109

110
  hot.getPlugin('manualRowMove').moveRow(selectedRow, selectedRow - 1);
111
  hot.render();
112
  selectedRow -= 1;
113
  hot.selectRows(selectedRow);
114
});
115

116
// ManualRowMove inserts BEFORE the target index, so moving row N down
117
// requires a target of N + 2 (the slot after the next row).
118
btnMoveDown.addEventListener('click', () => {
119
  if (selectedRow === null || selectedRow === hot.countRows() - 1) {
120
    return;
121
  }
122

123
  hot.getPlugin('manualRowMove').moveRow(selectedRow, selectedRow + 2);
124
  hot.render();
125
  selectedRow += 1;
126
  hot.selectRows(selectedRow);
127
});
128

129
updateButtonStates();

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

4
registerAllModules();
5

6
/* start:skip-in-preview */
7
const data = [
8
  ['Migrate auth service to OAuth 2.0', 'Alice Johnson', 'High', 'In Progress'],
9
  ['Write API documentation', 'Bob Smith', 'Normal', 'To Do'],
10
  ['Fix pagination bug on dashboard', 'Carol White', 'High', 'In Review'],
11
  ['Add CSV export feature', 'David Lee', 'Normal', 'To Do'],
12
  ['Upgrade React to v19', 'Eve Martinez', 'Low', 'Backlog'],
13
  ['Implement dark mode toggle', 'Frank Brown', 'Normal', 'In Progress'],
14
  ['Set up end-to-end test suite', 'Grace Kim', 'High', 'To Do'],
15
  ['Refactor database connection pool', 'Henry Wilson', 'Low', 'Backlog'],
16
];
17
/* end:skip-in-preview */
18

19
const container = document.querySelector('#example1')!;
20

21
const toolbar = document.createElement('div');
22

23
toolbar.classList.add('example-controls-container');
24
toolbar.innerHTML = `
25
  <div class="controls">
26
    <button id="btn-add-row" type="button">Add Row</button>
27
    <button id="btn-delete-row" type="button">Delete Row</button>
28
    <button id="btn-move-up" type="button">Move Up</button>
29
    <button id="btn-move-down" type="button">Move Down</button>
30
  </div>
31
`;
32
container.before(toolbar);
33

34
const hot = new Handsontable(container, {
35
  data,
36
  colHeaders: ['Task', 'Assignee', 'Priority', 'Status'],
37
  rowHeaders: true,
38
  height: 'auto',
39
  width: '100%',
40
  manualRowMove: true,
41
  outsideClickDeselects(target: HTMLElement) {
42
    return !toolbar.contains(target);
43
  },
44
  licenseKey: 'non-commercial-and-evaluation',
45
});
46

47
const btnAddRow = toolbar.querySelector('#btn-add-row') as HTMLButtonElement;
48
const btnDeleteRow = toolbar.querySelector('#btn-delete-row') as HTMLButtonElement;
49
const btnMoveUp = toolbar.querySelector('#btn-move-up') as HTMLButtonElement;
50
const btnMoveDown = toolbar.querySelector('#btn-move-down') as HTMLButtonElement;
51

52
let selectedRow: number | null = null;
53

54
function updateButtonStates(): void {
55
  const hasSelection = selectedRow !== null;
56
  const isFirst = selectedRow === 0;
57
  const isLast = selectedRow === hot.countRows() - 1;
58

59
  btnDeleteRow.disabled = !hasSelection;
60
  btnMoveUp.disabled = !hasSelection || isFirst;
61
  btnMoveDown.disabled = !hasSelection || isLast;
62
}
63

64
hot.addHook('afterSelectionEnd', (row: number, _col: number, row2: number) => {
65
  selectedRow = row === row2 ? Math.min(row, row2) : null;
66
  updateButtonStates();
67
});
68

69
hot.addHook('afterDeselect', () => {
70
  selectedRow = null;
71
  updateButtonStates();
72
});
73

74
btnAddRow.addEventListener('click', () => {
75
  hot.alter('insert_row_below', hot.countRows() - 1);
76
});
77

78
btnDeleteRow.addEventListener('click', () => {
79
  const selected = hot.getSelected();
80

81
  if (!selected) {
82
    return;
83
  }
84

85
  const rowSet = new Set<number>();
86

87
  selected.forEach(([r1, , r2]) => {
88
    const from = Math.min(r1, r2);
89
    const to = Math.max(r1, r2);
90

91
    for (let r = from; r <= to; r++) {
92
      rowSet.add(r);
93
    }
94
  });
95

96
  const rows = [...rowSet].sort((a, b) => b - a);
97

98
  rows.forEach(row => hot.alter('remove_row', row, 1));
99
  updateButtonStates();
100
});
101

102
btnMoveUp.addEventListener('click', () => {
103
  if (selectedRow === null || selectedRow === 0) {
104
    return;
105
  }
106

107
  hot.getPlugin('manualRowMove').moveRow(selectedRow, selectedRow - 1);
108
  hot.render();
109
  selectedRow -= 1;
110
  hot.selectRows(selectedRow);
111
});
112

113
// ManualRowMove inserts BEFORE the target index, so moving row N down
114
// requires a target of N + 2 (the slot after the next row).
115
btnMoveDown.addEventListener('click', () => {
116
  if (selectedRow === null || selectedRow === hot.countRows() - 1) {
117
    return;
118
  }
119

120
  hot.getPlugin('manualRowMove').moveRow(selectedRow, selectedRow + 2);
121
  hot.render();
122
  selectedRow += 1;
123
  hot.selectRows(selectedRow);
124
});
125

126
updateButtonStates();

Overview

This recipe shows how to wire four external toolbar buttons — Add Row, Delete Row, Move Up, and Move Down — to Handsontable’s alter() API and the ManualRowMove plugin. This pattern is common in form-like grids where users manage an ordered list of items.

Difficulty: Beginner Time: ~15 minutes

What You’ll Build

A Handsontable grid with a toolbar that lets you:

Append a blank row at the bottom
Delete all rows covered by the current selection
Move the selected row one position up or down
Disable Move Up when the first row is selected, and Move Down when the last row is selected

Before you begin

You need a Handsontable instance. If you haven’t set one up yet, follow the Getting started guide first.

Make sure you have a container element with four buttons in your HTML:

1
<div class="row-toolbar">
2
  <button id="btn-add-row">Add Row</button>
3
  <button id="btn-delete-row">Delete Row</button>
4
  <button id="btn-move-up">Move Up</button>
5
  <button id="btn-move-down">Move Down</button>
6
</div>
7
<div id="example1"></div>

Enable ManualRowMove and initialize Handsontable

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

4
registerAllModules();
5

6
const hot = new Handsontable(document.querySelector('#example1'), {
7
  data: myData,
8
  colHeaders: ['Task', 'Assignee', 'Priority', 'Status'],
9
  rowHeaders: true,
10
  height: 'auto',
11
  width: '100%',
12
  manualRowMove: true,
13
  licenseKey: 'non-commercial-and-evaluation',
14
});

What’s happening:

manualRowMove: true activates the ManualRowMove plugin. Without it, hot.getPlugin('manualRowMove').moveRow() does nothing.
registerAllModules() registers all built-in plugins so they are available by name.

Track the selected row

The Move Up and Move Down buttons act on a single row. Use a module-level variable to track which row is currently selected, and keep it in sync via two hooks:
```
1
let selectedRow = null;
2

3
hot.addHook('afterSelectionEnd', (row, col, row2) => {
4
  // Only track a single-row selection for move operations
5
  selectedRow = row === row2 ? Math.min(row, row2) : null;
6
  updateButtonStates();
7
});
8

9
hot.addHook('afterDeselect', () => {
10
  selectedRow = null;
11
  updateButtonStates();
12
});
```
What’s happening:
- afterSelectionEnd fires after the user finishes selecting cells. The arguments row and row2 are the start and end rows of the selection rectangle.
- When row === row2, a single row is selected — store it in selectedRow. When multiple rows are selected, set selectedRow to null to disable the move buttons (you can only move one row at a time).
- afterDeselect fires when the grid loses focus or the selection is programmatically cleared. Reset selectedRow to null.
Sync button disabled states

Disable buttons that don’t apply to the current selection:
```
1
function updateButtonStates() {
2
  const hasSelection = selectedRow !== null;
3
  const isFirst = selectedRow === 0;
4
  const isLast = selectedRow === hot.countRows() - 1;
5

6
  btnDeleteRow.disabled = !hasSelection;
7
  btnMoveUp.disabled = !hasSelection || isFirst;
8
  btnMoveDown.disabled = !hasSelection || isLast;
9
}
```
What’s happening:
- Delete Row is disabled when nothing is selected.
- Move Up is disabled on the first row — there is nowhere to go.
- Move Down is disabled on the last row — there is nowhere to go.
- Call updateButtonStates() after every hook callback and after every button action.
Add Row button

Append a blank row at the bottom:
```
1
btnAddRow.addEventListener('click', () => {
2
  hot.alter('insert_row_below', hot.countRows() - 1);
3
});
```
What’s happening:
- hot.alter('insert_row_below', index) inserts a row below index.
- Passing hot.countRows() - 1 means “below the last row”, which appends to the end.
- The new row is filled with null values — the grid treats missing values as empty cells.

Delete Row button

Remove every row touched by the current selection:

1
btnDeleteRow.addEventListener('click', () => {
2
  const selected = hot.getSelected();
3

4
  if (!selected) {
5
    return;
6
  }
7

8
  // Collect all row indices covered by the selection
9
  const rowSet = new Set();
10

11
  selected.forEach(([r1, , r2]) => {
12
    const from = Math.min(r1, r2);
13
    const to = Math.max(r1, r2);
14

15
    for (let r = from; r <= to; r++) {
16
      rowSet.add(r);
17
    }
18
  });
19

20
  // Delete from bottom to top to keep earlier indices valid
21
  const rows = [...rowSet].sort((a, b) => b - a);
22

23
  rows.forEach(row => hot.alter('remove_row', row, 1));
24
  selectedRow = null;
25
  updateButtonStates();
26
});

What’s happening:

hot.getSelected() returns an array of [r1, c1, r2, c2] tuples — one per selection range (Handsontable supports non-contiguous multi-selection via Ctrl+Click).
For each tuple, collect every row index between r1 and r2 into a Set. The Set deduplicates rows that appear in overlapping ranges.
Sort the collected rows in descending order, then delete from bottom to top. If you delete row 2 first, the former row 3 becomes row 2, and all higher indices shift down — your loop would then delete the wrong rows. Deleting from the bottom up avoids this shift problem entirely.
Reset selectedRow and update button states after deleting.

Move Up button

Move the selected row one position earlier:
```
1
btnMoveUp.addEventListener('click', () => {
2
  if (selectedRow === null || selectedRow === 0) {
3
    return;
4
  }
5

6
  hot.getPlugin('manualRowMove').moveRow(selectedRow, selectedRow - 1);
7
  hot.render();
8
  selectedRow -= 1;
9
  hot.selectRows(selectedRow);
10
});
```
What’s happening:
- hot.getPlugin('manualRowMove').moveRow(from, to) moves the row at visual index from to visual index to. After the move, the row occupies position to.
- hot.render() is required after moveRow() — the plugin modifies internal index mappings but does not repaint the grid automatically.
- Update selectedRow to the new position and call hot.selectRows() to keep the row highlighted.
Move Down button

Move the selected row one position later:
```
1
btnMoveDown.addEventListener('click', () => {
2
  if (selectedRow === null || selectedRow === hot.countRows() - 1) {
3
    return;
4
  }
5

6
  hot.getPlugin('manualRowMove').moveRow(selectedRow, selectedRow + 2);
7
  hot.render();
8
  selectedRow += 1;
9
  hot.selectRows(selectedRow);
10
});
```
What’s happening:
- Moving a row down requires a target index of selectedRow + 2, not selectedRow + 1. The ManualRowMove target is the slot before which the row is inserted. To place row 3 after row 4, you must insert it before slot 5 — so the target is 3 + 2 = 5.
- As with Move Up, call hot.render() and update selectedRow.

How It Works - Complete Flow

Initial state - The grid renders with manualRowMove: true. All four buttons are disabled (no selection yet).
User clicks a row - afterSelectionEnd fires, selectedRow is updated, and updateButtonStates() enables Delete Row and the appropriate Move Up / Move Down buttons.
Add Row clicked - hot.alter('insert_row_below', lastIndex) appends a blank row. No selection change occurs.
Delete Row clicked - All selected rows are collected into a Set, sorted descending, and removed one by one. The selection is cleared and buttons are reset.
Move Up or Move Down clicked - moveRow() updates the internal row order, hot.render() repaints, and hot.selectRows() keeps the visual focus on the moved row.

What you learned

How to append rows with hot.alter('insert_row_below', index)
How to delete multiple selected rows safely by sorting indices descending before removing
How to reorder rows with hot.getPlugin('manualRowMove').moveRow(from, to) and why you must call hot.render() afterward
Why moving a row down requires target row + 2 (ManualRowMove inserts before the target slot)
How to sync external button states with afterSelectionEnd and afterDeselect hooks

Next steps

To restrict row reordering at runtime, listen to the beforeRowMove hook and return false to cancel specific moves.
To persist row order after a page reload, serialize the current row order with hot.getPlugin('manualRowMove').getOrderedIndexes() and restore it on init.
To trigger the same operations from a context menu instead of toolbar buttons, see Context menu.

Programmatic row operations

Overview

What You’ll Build

Before you begin

Enable ManualRowMove and initialize Handsontable

Track the selected row

Sync button disabled states

Add Row button

Delete Row button

Move Up button

Move Down button

How It Works - Complete Flow

What you learned

Next steps