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.

Re-applying the same configuration

Re-applying a mergeCells value through updateSettings() clears only the cells that still hold a value. A range whose cells are already empty changes no data, so it fires no beforeChange or afterChange event.

This depends on the clearing write reaching the data. If you cancel it — by returning false from beforeChange, or with a validator that rejects null while allowInvalid is false — the covered cells keep their values, and every re-apply tries to clear them again.

This matters when a framework wrapper resends every option on each render. React and Angular do. Without it, an app that writes those events back into a store keeps receiving changes for values that never changed, and the two can keep triggering each other.

Nothing else about the clearing changes. A range still clears its covered cells the first time you apply it, even where those cells are already empty. And if new values arrive in a covered range — because you passed new data, or because sorting, filtering, or a row move brought other rows under the range — the next re-apply clears them, then stays quiet:

1
hot.updateSettings({
2
  data: [['SKU-4821', 'Stainless Steel Water Bottle'], ['SKU-0093', 'Wireless Mouse']],
3
  mergeCells: [{ row: 0, col: 0, rowspan: 2, colspan: 2 }], // unchanged
4
});
5

6
hot.getDataAtCell(0, 1); // -> null, cleared as usual

Copying and pasting over merged cells

Pasting a block of more than one cell over a merged range unmerges that range, and every pasted value becomes visible. Excel and Google Sheets behave the same way: a block with its own rows and columns cannot fit inside a single merged cell, so the merge gives way.

Every merged range the pasted block reaches is unmerged, not only the one you selected. A paste fills the larger of the copied block and the selected range, so it can reach past your selection and clip a neighboring merge.

Pasting a single value leaves the merge in place. A single value carries no structure of its own, so it lands in the merged range’s top-left cell and the covered cells stay empty.

The merge geometry travels with the paste’s own undo entry, so undo() restores the pasted values and the merged ranges together rather than in two steps. A validator that corrects a pasted value adds an undo entry of its own for each cell it corrects, as it does for any other write; those entries revert only their value and leave the merged ranges alone.

One thing this does not do: copying does not carry the merge. A merged range copies as its top-left value plus empty cells, so pasting it elsewhere creates no merge. Pasted HTML rowspan and colspan attributes are flattened the same way: the value lands in the top-left cell of the span and the covered cells are set to null.

To keep a merged range intact, cancel the paste from beforePaste. Returning false there stops the whole paste, so nothing is written and no merge is dropped:

1
new Handsontable(container, {
2
  mergeCells: [{ row: 0, col: 0, rowspan: 2, colspan: 2 }],
3
  beforePaste(data, coords) {
4
    const isSingleValue = data.length === 1 && data[0].length === 1;
5

6
    if (isSingleValue) {
7
      return; // a single value never breaks a merge, so let it through
8
    }
9

10
    const clipboardRows = data.length;
11
    const clipboardColumns = Math.max(...data.map(row => row.length));
12

13
    // Measure the area the paste writes, not the selected area: a paste fills the larger of the
14
    // copied block and the selection on each axis, so it can reach past the selection. Scan every
15
    // cell of that area, because `rowspan` and `colspan` are set only on a merged range's
16
    // top-left cell.
17
    const touchesMergedRange = coords.some(({ startRow, startCol, endRow, endCol }) => {
18
      const lastRow = startRow + Math.max(clipboardRows, endRow - startRow + 1) - 1;
19
      const lastColumn = startCol + Math.max(clipboardColumns, endCol - startCol + 1) - 1;
20

21
      for (let row = startRow; row <= lastRow; row += 1) {
22
        for (let col = startCol; col <= lastColumn; col += 1) {
23
          const { rowspan, colspan } = this.getCellMetaTransient(row, col);
24

25
          if (rowspan > 1 || colspan > 1) {
26
            return true;
27
          }
28
        }
29
      }
30

31
      return false;
32
    });
33

34
    if (touchesMergedRange) {
35
      return false;
36
    }
37
  },
38
});

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.
Rows removed from view count as spanned: a fragment that shows a single cell only because the rest of its rows are removed from view is kept, and it spans them again when they come back. This holds for manualRowMove, manualColumnMove, and manualColumnFreeze alike. The one exception is a row move of a merged cell whose rows a sort has separated (see the next section).

undo and redo restore the row and column order the reorder changed. They do not restore merged cells: an undo replays the opposite move, so a merged cell the reorder split stays split, and one it dropped stays dropped. Merge the cells again if you need the original merged cell back.

Behavior when rows inside a merge are removed from view

Some features remove rows from the grid entirely: filters, trimRows, and collapsing a parent row of nestedRows. A removed row has no position in the grid at all, so a merged cell that covers one spans fewer rows than it did:

The merged cell moves to the first of its rows that is still shown, and spans only the rows of its own that remain. It never grows over the rows below it.
When none of its rows is shown, the merged cell is not displayed.
When the rows come back, the merged cell spans them again. Nothing about the merge is lost while its rows are away. A merged cell you create while rows are already removed from view covers only the rows you could see, and does not grow when the rest come back.
When a row move splits a merged cell while some of its rows are removed from view, each removed row stays with the fragment holding the merged cell’s own rows next to it in the grid’s row order, which is the order the rows take when they come back. A removed row never crosses a row the merged cell does not cover: when the move places such a row between the merged cell’s own rows, the removed rows on each side of it stay on that side, and a removed row with no fragment reachable that way is lost.
A merged cell whose rows a sort has separated is the exception. It still spans one block, so that block reaches over rows the merged cell does not cover, and a row move that breaks the block cannot tell which fragment owns which row. Each fragment then covers only the rows it shows, and the rows removed from view are not restored. A single-column merged cell disappears altogether in this case, because every fragment it leaves behind is a single cell. Sort the column back, or clear the filter, before you move the rows.

hiddenRows works differently. A hidden row keeps its position, so a merged cell spanning one keeps its configured rowspan and simply draws over less space.

One limitation applies to undo. Unmerging a merged cell whose rows are all hidden but one records only the single cell you can see, which is not a merged cell, so undoing that unmerge restores nothing. Expand or unfilter the rows first if you want the unmerge to be reversible.

A merged cell behaves as a single cell at its top-left corner. When you move the selection onto a merged cell — with the arrow keys or a mouse click — the whole merged cell is highlighted. When you then leave it to the left or right with a non-Tab horizontal move — an arrow key, the editor’s arrow-key exit, or Enter when enterMoves is configured to step horizontally — the selection lands on the top row of the merged cell, whichever row you entered it from. Entering a merged cell from below and leaving it sideways lands on the same row as entering it from above, so horizontal navigation stays consistent. When the top row is hidden, the selection lands on the merged cell’s topmost visible row.

Vertical navigation keeps the column you were moving along, and the Tab and Shift+Tab keys keep the row they cycle along, so neither is affected.