Merge cells

Merge adjacent cells, using the Ctrl+M shortcut or the context menu. Control merged cells, using Handsontable’s API.

Overview

By merging, you can combine two or more adjacent cells into a single cell that spans several rows or columns.

Handsontable merges cells in the same way as Microsoft Excel: keeps only the upper-left value of the selected range and clears other values. This clearing happens in the underlying data, not just on screen — see Effect on the underlying data.

How to merge cells

To enable the merge cells feature, set the mergeCells option to true or to an array.

To initialize Handsontable with predefined merged cells, provide merged cells details in form of an array:

The row and col properties use visual indexes. They refer to positions as displayed in the grid, in the same coordinate space as selectCell() and getCellMeta().

1
const hotSettings = {
2
  mergeCells: [
3
    { row: 1, col: 1, rowspan: 3, colspan: 3 },
4
    { row: 3, col: 4, rowspan: 2, colspan: 2 },
5
    { row: 5, col: 6, rowspan: 3, colspan: 3 },
6
  ],
7
};

1
<script setup lang="ts">
2
import { ref } from 'vue';
3
import { HotTable } from '@handsontable/vue3';
4
import { registerAllModules } from 'handsontable/registry';
5
import type { GridSettings } from 'handsontable/settings';
6

7
registerAllModules();
8

9
const data = new Array(100)
10
  .fill(null)
11
  .map((_, row) =>
12
    new Array(50)
13
      .fill(null)
14
      .map((_, column) => `${row}, ${column}`)
15
  );
16

17
const hotSettings = ref<GridSettings>({
18
  data,
19
  height: 320,
20
  autoColumnSize: {
21
    allowSampleDuplicates: true,
22
    samplingRatio: 100,
23
  },
24
  rowHeaders: true,
25
  colHeaders: true,
26
  contextMenu: true,
27
  mergeCells: [
28
    { row: 1, col: 1, rowspan: 3, colspan: 3 },
29
    { row: 3, col: 4, rowspan: 2, colspan: 2 },
30
    { row: 5, col: 6, rowspan: 3, colspan: 3 },
31
  ],
32
  autoWrapRow: true,
33
  autoWrapCol: true,
34
  licenseKey: 'non-commercial-and-evaluation',
35
});
36
</script>
37

38
<template>
39
  <div id="example1">
40
    <HotTable :settings="hotSettings" />
41
  </div>
42
</template>

Optimizing rendering of the wide/tall merged cells

When cells span thousands of rows or columns, scrolling may feel slower compared to unmerged cells. To improve performance, consider enabling the dedicated virtualization feature for merged cells, which is disabled by default.

To enable the merged cells virtualization mode, enable the virtualized option:

1
const hotSettings = {
2
  mergeCells: {
3
    virtualized: true,
4
    cells: [{ row: 1, col: 1, rowspan: 200, colspan: 2 }],
5
  },
6
};

The example below uses virtualized merged cells. It’s also recommended to increase the buffer of rendered rows/columns to minimize the flickering effects.

1
<script setup lang="ts">
2
import { ref } from 'vue';
3
import { HotTable } from '@handsontable/vue3';
4
import { registerAllModules } from 'handsontable/registry';
5
import type { GridSettings } from 'handsontable/settings';
6

7
registerAllModules();
8

9
const data = new Array(50)
10
  .fill(null)
11
  .map((_, row) =>
12
    new Array(500)
13
      .fill(null)
14
      .map((_, column) => `${row}, ${column}`)
15
  );
16

17
const hotSettings = ref<GridSettings>({
18
  data,
19
  height: 320,
20
  colWidths: 100,
21
  rowHeaders: true,
22
  colHeaders: true,
23
  contextMenu: true,
24
  mergeCells: {
25
    virtualized: true,
26
    cells: [{ row: 1, col: 1, rowspan: 3, colspan: 498 }],
27
  },
28
  viewportColumnRenderingOffset: 15,
29
  viewportColumnRenderingThreshold: 5,
30
  autoWrapRow: true,
31
  autoWrapCol: true,
32
  licenseKey: 'non-commercial-and-evaluation',
33
});
34
</script>
35

36
<template>
37
  <div id="example2">
38
    <HotTable :settings="hotSettings" />
39
  </div>
40
</template>

React to merge and unmerge events

To run your own logic when cells merge or unmerge, use the beforeMergeCells, afterMergeCells, beforeUnmergeCells, and afterUnmergeCells hooks. Each hook receives the affected cellRange, and afterMergeCells also receives the resulting mergeParent object (row, col, rowspan, colspan).

The example below logs a message every time you merge or unmerge cells, using the context menu or the Ctrl+M shortcut.

1
<script setup lang="ts">
2
import { ref } from 'vue';
3
import { HotTable } from '@handsontable/vue3';
4
import { registerAllModules } from 'handsontable/registry';
5
import type { GridSettings } from 'handsontable/settings';
6

7
registerAllModules();
8

9
const output = ref('');
10

11
const logEvent = (message: string) => {
12
  output.value = `${message}\n${output.value}`;
13
};
14

15
const hotSettings: GridSettings = {
16
  data: [
17
    ['North America', 420000, 465000, 501000],
18
    ['Europe', 388000, 402000, 411000],
19
    ['APAC', 275000, 298000, 312000],
20
    ['Latin America', 142000, 151000, 158000],
21
    ['Middle East', 96000, 101000, 108000],
22
  ],
23
  colHeaders: ['Region', 'Jan 2025', 'Feb 2025', 'Mar 2025'],
24
  rowHeaders: true,
25
  height: 'auto',
26
  contextMenu: true,
27
  mergeCells: true,
28
  autoWrapRow: true,
29
  autoWrapCol: true,
30
  licenseKey: 'non-commercial-and-evaluation',
31
  beforeMergeCells: (cellRange) => {
32
    logEvent(`beforeMergeCells: rows ${cellRange.from.row}-${cellRange.to.row}, columns ${cellRange.from.col}-${cellRange.to.col}.`);
33
  },
34
  afterMergeCells: (cellRange, mergeParent) => {
35
    logEvent(`afterMergeCells: merged into ${mergeParent.rowspan} row(s) by ${mergeParent.colspan} column(s).`);
36
  },
37
  beforeUnmergeCells: (cellRange) => {
38
    logEvent(`beforeUnmergeCells: rows ${cellRange.from.row}-${cellRange.to.row}, columns ${cellRange.from.col}-${cellRange.to.col}.`);
39
  },
40
  afterUnmergeCells: (cellRange) => {
41
    logEvent(`afterUnmergeCells: rows ${cellRange.from.row}-${cellRange.to.row}, columns ${cellRange.from.col}-${cellRange.to.col}.`);
42
  },
43
};
44
</script>
45

46
<template>
47
  <div id="example3">
48
    <output class="console" id="example3-output">{{
49
      output ||
50
        'Select cells, then press Ctrl+M (or use the context menu) to merge or unmerge them. Hook activity appears here.'
51
    }}</output>
52
    <HotTable :settings="hotSettings" />
53
  </div>
54
</template>

Merge and unmerge cells programmatically

To merge or unmerge a range without a user action, call the MergeCells plugin’s merge() and unmerge() methods. Both methods take a visual startRow, startColumn, endRow, and endColumn, the same coordinate space as selectCell().

1
hot.getPlugin('mergeCells').merge(startRow, startColumn, endRow, endColumn);
2
hot.getPlugin('mergeCells').unmerge(startRow, startColumn, endRow, endColumn);

This clears the underlying data the same way as merging through the UI or the mergeCells configuration option. See Effect on the underlying data.

The example below merges and unmerges a footnote row that spans every column, using buttons instead of a manual selection.

1
<script setup lang="ts">
2
import { useTemplateRef } from 'vue';
3
import { HotTable } from '@handsontable/vue3';
4
import { registerAllModules } from 'handsontable/registry';
5
import type { GridSettings } from 'handsontable/settings';
6

7
registerAllModules();
8

9
const hotRef = useTemplateRef<InstanceType<typeof HotTable>>('hotRef');
10

11
const hotSettings: GridSettings = {
12
  data: [
13
    ['North America', 420000, 465000, 501000],
14
    ['Europe', 388000, 402000, 411000],
15
    ['APAC', 275000, 298000, 312000],
16
    ['Latin America', 142000, 151000, 158000],
17
    ['Middle East', 96000, 101000, 108000],
18
    ['Note: Q1 totals include a one-time currency adjustment.', null, null, null],
19
  ],
20
  colHeaders: ['Region', 'Jan 2025', 'Feb 2025', 'Mar 2025'],
21
  rowHeaders: true,
22
  height: 'auto',
23
  contextMenu: true,
24
  mergeCells: true,
25
  autoWrapRow: true,
26
  autoWrapCol: true,
27
  licenseKey: 'non-commercial-and-evaluation',
28
};
29

30
function mergeNoteRow() {
31
  hotRef.value?.hotInstance?.getPlugin('mergeCells').merge(5, 0, 5, 3);
32
}
33

34
function unmergeNoteRow() {
35
  hotRef.value?.hotInstance?.getPlugin('mergeCells').unmerge(5, 0, 5, 3);
36
}
37
</script>
38

39
<template>
40
  <div id="example4">
41
    <div class="example-controls-container">
42
      <div class="controls">
43
        <button id="example4-merge" class="button button--primary" @click="mergeNoteRow">
44
          Merge the note row
45
        </button>
46
        <button id="example4-unmerge" class="button button--primary" @click="unmergeNoteRow">
47
          Unmerge the note row
48
        </button>
49
      </div>
50
    </div>
51
    <HotTable ref="hotRef" :settings="hotSettings" />
52
  </div>
53
</template>

Effect on the underlying data

Merging doesn’t only hide the covered cells visually — it clears their values in the underlying data too, whether you merge through the UI, the mergeCells configuration option, or the merge() method. Only the top-left cell of the range keeps its value; every other cell covered by the merge is set to null.

For a range merged at (0, 0) with rowspan: 2 and colspan: 2:

1
hot.getData();
2
// -> [['Top-left value', null], [null, null]]
3

4
hot.getSourceData();
5
// -> [['Top-left value', null], [null, null]] (the same)

Both getData() and getSourceData() return null for the covered cells, because the clearing runs through the normal change pipeline: it fires beforeChange and afterChange with source === 'MergeCells' (see Events and hooks: Definition for source argument).

Unmerging does not restore the cleared values. If you need the original values back, keep a copy before merging, or restore them yourself in a beforeUnmergeCells or afterUnmergeCells handler.

Effect on viewport getter methods

With merged cells, the rendered range extends to fit any merged cell that crosses the viewport edge. This is the same expansion that the virtualized option turns off. As a result, the rendered-range getters can return indexes beyond what you see on the screen:

getFirstRenderedVisibleRow(), getLastRenderedVisibleRow(), getFirstRenderedVisibleColumn(), and getLastRenderedVisibleColumn().
AutoRowSize.getFirstVisibleRow() and AutoRowSize.getLastVisibleRow(), which delegate to the rendered-row getters.
AutoColumnSize.getFirstVisibleColumn() and AutoColumnSize.getLastVisibleColumn(), which delegate to the rendered-column getters.

For example, a merged cell that spans columns 0 to 100 makes getLastVisibleColumn() return an index near 100, even when the viewport shows far fewer columns.

To read the actual visible viewport, use the fully-visible or partially-visible getters, which ignore the merge-cell expansion:

Setting virtualized to true also removes the range expansion, but it is a performance option — the rendered-range getters still include buffered rows and columns outside the viewport.

Behavior during row/column reorder and column freeze

When a merged cell’s underlying rows or columns are reordered (through manualColumnMove, manualRowMove, or manualColumnFreeze), Handsontable follows the merge to the new visual position. Two side effects can occur:

Auto-split: if the move bisects a merge so the underlying cells are no longer contiguous in the new visual order, the merge is split into separate merges, one per contiguous run. The cross-axis span (rowspan for column moves, colspan for row moves) is preserved on every fragment.
Silent drop of single-cell fragments: any resulting fragment that ends up as a single cell (rowspan === 1 && colspan === 1) is removed, because a single cell is no longer a merge. The afterMergeCells hook is not fired for the dropped fragment.

undo and redo restore the pre-move state, including any merges that were split or dropped by the reorder.