React Data GridMerge cells

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

Overview
How to merge cells
Optimizing rendering of the wide/tall merged cells
Related keyboard shortcuts
Related API reference

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.

Cell merging happens on Handsontable's visual layer and doesn't affect your source data structure.

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:

mergeCells={[{ row: 1, col: 1, rowspan: 2, colspan: 2 }]}

{
  "name": "handsontable",
  "version": "1.0.0",
  "description": "",
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "hyperformula": "^2.4.0",
    "handsontable": "15.0",
    "@handsontable/react-wrapper": "15.0"
  },
  
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Handsontable</title>
  </head>

  <body>
    <noscript> You need to enable JavaScript to run this app. </noscript>
    <div id="root"></div>
  </body>
</html>

import React, { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./styles.css";
import ExampleComponent from "./ExampleComponent";

const rootElement = document.getElementById("root");
const root = createRoot(rootElement);

root.render(
  <StrictMode>
    <ExampleComponent />
  </StrictMode>
);

import React from "react";
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
import 'handsontable/styles/handsontable.css';
import 'handsontable/styles/ht-theme-main.css';

// register Handsontable's modules
registerAllModules();

// generate an array of arrays with dummy data
const data = new Array(100) // number of rows
  .fill(null)
  .map((_, row) =>
    new Array(50) // number of columns
      .fill(null)
      .map((_, column) => `${row}, ${column}`)
  );

const ExampleComponent = () => {
  return (
    <HotTable
      data={data}
      height={320}
      colWidths={50}
      rowHeaders={true}
      colHeaders={true}
      contextMenu={true}
      mergeCells={[
        { row: 1, col: 1, rowspan: 3, colspan: 3 },
        { row: 3, col: 4, rowspan: 2, colspan: 2 },
        { row: 5, col: 6, rowspan: 3, colspan: 3 },
      ]}
      autoWrapRow={true}
      autoWrapCol={true}
      licenseKey="non-commercial-and-evaluation"
    />
  );
};

export default ExampleComponent;

import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
import 'handsontable/styles/handsontable.css';
import 'handsontable/styles/ht-theme-main.css';

// register Handsontable's modules
registerAllModules();

// generate an array of arrays with dummy data
const data = new Array(100) // number of rows
  .fill(null)
  .map((_, row) =>
    new Array(50) // number of columns
      .fill(null)
      .map((_, column) => `${row}, ${column}`)
  );

const ExampleComponent = () => {
  return (
    <HotTable
      data={data}
      height={320}
      colWidths={50}
      rowHeaders={true}
      colHeaders={true}
      contextMenu={true}
      mergeCells={[
        { row: 1, col: 1, rowspan: 3, colspan: 3 },
        { row: 3, col: 4, rowspan: 2, colspan: 2 },
        { row: 5, col: 6, rowspan: 3, colspan: 3 },
      ]}
      autoWrapRow={true}
      autoWrapCol={true}
      licenseKey="non-commercial-and-evaluation"
    />
  );
};



ReactDOM.render(<ExampleComponent />, document.getElementById("example1"));

<script src="https://cdn.jsdelivr.net/npm/handsontable@15.0/dist/handsontable.full.min.js"></script>
<link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable@15.0/styles/handsontable.min.css" /> 
<link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable@15.0/styles/ht-theme-main.css" /> 
<link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable@15.0/styles/ht-theme-horizon.css" /> 
<script src="https://cdn.jsdelivr.net/npm/react@18/umd/react.production.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/react-dom@18/umd/react-dom.production.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@handsontable/react-wrapper@15.0/dist/react-handsontable.min.js"></script>
<script src="https://handsontable.com/docs/scripts/fixer.js"></script>

<div id="example1" class="hot ht-theme-main-dark-auto "></div>

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:

mergeCells={{
  virtualized: true,
  cells: [{ row: 1, col: 1, rowspan: 200, colspan: 2 }]
}}

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

{
  "name": "handsontable",
  "version": "1.0.0",
  "description": "",
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "hyperformula": "^2.4.0",
    "handsontable": "15.0",
    "@handsontable/react-wrapper": "15.0"
  },
  
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Handsontable</title>
  </head>

  <body>
    <noscript> You need to enable JavaScript to run this app. </noscript>
    <div id="root"></div>
  </body>
</html>

import React, { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./styles.css";
import ExampleComponent from "./ExampleComponent";

const rootElement = document.getElementById("root");
const root = createRoot(rootElement);

root.render(
  <StrictMode>
    <ExampleComponent />
  </StrictMode>
);

import React from "react";
import { HotTable } from '@handsontable/react';
import { registerAllModules } from 'handsontable/registry';
import 'handsontable/styles/handsontable.css';
import 'handsontable/styles/ht-theme-main.css';

// register Handsontable's modules
registerAllModules();

// generate an array of arrays with dummy data
const data = new Array(50) // number of rows
  .fill(null)
  .map((_, row) =>
    new Array(500) // number of columns
      .fill(null)
      .map((_, column) => `${row}, ${column}`)
  );

const ExampleComponent = () => {
  return (
    <HotTable
      data={data}
      height={320}
      colWidths={100}
      rowHeaders={true}
      colHeaders={true}
      contextMenu={true}
      mergeCells={{
        virtualized: true,
        cells: [{ row: 1, col: 1, rowspan: 3, colspan: 498 }],
      }}
      viewportColumnRenderingOffset={15}
      viewportColumnRenderingThreshold={5}
      autoWrapRow={true}
      autoWrapCol={true}
      licenseKey="non-commercial-and-evaluation"
    />
  );
};

export default ExampleComponent;

import { HotTable } from '@handsontable/react';
import { registerAllModules } from 'handsontable/registry';
import 'handsontable/styles/handsontable.css';
import 'handsontable/styles/ht-theme-main.css';

// register Handsontable's modules
registerAllModules();

// generate an array of arrays with dummy data
const data = new Array(50) // number of rows
  .fill(null)
  .map((_, row) =>
    new Array(500) // number of columns
      .fill(null)
      .map((_, column) => `${row}, ${column}`)
  );

const ExampleComponent = () => {
  return (
    <HotTable
      data={data}
      height={320}
      colWidths={100}
      rowHeaders={true}
      colHeaders={true}
      contextMenu={true}
      mergeCells={{
        virtualized: true,
        cells: [{ row: 1, col: 1, rowspan: 3, colspan: 498 }],
      }}
      viewportColumnRenderingOffset={15}
      viewportColumnRenderingThreshold={5}
      autoWrapRow={true}
      autoWrapCol={true}
      licenseKey="non-commercial-and-evaluation"
    />
  );
};



ReactDOM.render(<ExampleComponent />, document.getElementById("example2"));

<script src="https://cdn.jsdelivr.net/npm/handsontable@15.0/dist/handsontable.full.min.js"></script>
<link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable@15.0/styles/handsontable.min.css" /> 
<link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable@15.0/styles/ht-theme-main.css" /> 
<link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable@15.0/styles/ht-theme-horizon.css" /> 
<script src="https://cdn.jsdelivr.net/npm/react@18/umd/react.production.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/react-dom@18/umd/react-dom.production.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@handsontable/react-wrapper@15.0/dist/react-handsontable.min.js"></script>
<script src="https://handsontable.com/docs/scripts/fixer.js"></script>

<div id="example2" class="hot ht-theme-main-dark-auto "></div>

Windows	macOS	Action	Excel	Sheets
`Ctrl`+`M`	`Ctrl`+`M`	Merge or unmerge the selected cells	✗	✗

React Data GridMerge cells

Overview

How to merge cells

Optimizing rendering of the wide/tall merged cells

Related keyboard shortcuts

Related API reference