MergeCells

Options

mergeCells

Can be set at: grid

mergeCells.mergeCells : boolean | Array<object>

The mergeCells option configures the MergeCells plugin.

You can set the mergeCells option to one of the following:

Setting	Description
`true`	Enable the `MergeCells` plugin
`false`	Disable the `MergeCells` plugin
An array of objects	- Enable the `MergeCells` plugin - Merge specific cells at initialization
{ virtualized: true }	Enable the `MergeCells` plugin with enabled virtualization mode

To merge specific cells at Handsontable’s initialization, set the mergeCells option to an array of objects, with the following properties:

Property	Description
`row`	The visual row index of the merged section’s beginning
`col`	The visual column index of the merged section’s beginning
`rowspan`	The width (as a number of rows) of the merged section
`colspan`	The height (as a number of columns ) of the merged section

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

A merged range clears the cells it covers. Re-applying the same value through updateSettings() clears only the cells that still hold a value, so a range that is already empty fires no beforeChange or afterChange event. Values that come back into a covered range — through new data, a sort, a filter, or a row move — are cleared on the next re-apply, as before. This assumes the clearing write reaches the data: cancel it (a beforeChange returning false, or a validator rejecting null) and every re-apply tries again.

Merge cells

Default: false
Example

1
// enable the `MergeCells` plugin
2
mergeCells: true,
3

4
// enable the `MergeCells` plugin
5
// and merge specific cells at initialization
6
mergeCells: [
7
  // merge cells from cell (1,1) to cell (3,3)
8
  {row: 1, col: 1, rowspan: 3, colspan: 3},
9
  // merge cells from cell (3,4) to cell (2,2)
10
  {row: 3, col: 4, rowspan: 2, colspan: 2},
11
  // merge cells from cell (5,6) to cell (3,3)
12
  {row: 5, col: 6, rowspan: 3, colspan: 3}
13
],
14

15
// enable the `MergeCells` plugin with enabled virtualization mode
16
// and merge specific cells at initialization
17
mergeCells: {
18
  virtualized: true,
19
  cells: [
20
    // merge cells from cell (1,1) to cell (3,3)
21
    {row: 1, col: 1, rowspan: 3, colspan: 3},
22
    // merge cells from cell (3,4) to cell (2,2)
23
    {row: 3, col: 4, rowspan: 2, colspan: 2},
24
    // merge cells from cell (5,6) to cell (3,3)
25
    {row: 5, col: 6, rowspan: 3, colspan: 3}
26
  ],
27
},

Members

DEFAULT_SETTINGS

Source code

MergeCells.DEFAULT_SETTINGS

Returns the default settings applied when the plugin is enabled without explicit configuration.

PLUGIN_KEY

Source code

MergeCells.PLUGIN_KEY

Returns the plugin key used to identify this plugin in Handsontable settings.

PLUGIN_PRIORITY

Source code

MergeCells.PLUGIN_PRIORITY

Returns the priority order used to determine the order in which plugins are initialized.

Methods

clearCollections

Source code

mergeCells.clearCollections()

Clears the merged cells from the merged cell container.

destroy

Source code

mergeCells.destroy()

Destroys the plugin instance. Removes the row index mapper local hook explicitly, because BasePlugin#destroy only clears addHook-managed hooks, not raw addLocalHook registrations, and releases the per-paste state, which BasePlugin#destroy cannot reach either - its objectEach sweep only sees enumerable own properties, never # fields.

disablePlugin

Source code

mergeCells.disablePlugin()

Disables the plugin functionality for this Handsontable instance.

enablePlugin

Source code

mergeCells.enablePlugin()

Enables the plugin functionality for this Handsontable instance.

isEnabled

Source code

mergeCells.isEnabled() ⇒ boolean

Checks if the plugin is enabled in the handsontable settings. This method is executed in Hooks#beforeInit hook and if it returns true then the MergeCells#enablePlugin method is called.

merge

Source code

mergeCells.merge(startRow, startColumn, endRow, endColumn)

Merges the specified range.

Emits: Hooks#event:beforeMergeCells, Hooks#event:afterMergeCells

Param	Type	Description
startRow	`number`	Visual start row of the merged cell.
startColumn	`number`	Visual start column of the merged cell.
endRow	`number`	Visual end row of the merged cell.
endColumn	`number`	Visual end column of the merged cell.

mergeSelection

Source code

mergeCells.mergeSelection([cellRange])

Merges the selection provided as a cell range.

Param	Type	Description
[cellRange]	`CellRange`	`optional` Selection cell range.

unmerge

Source code

mergeCells.unmerge(startRow, startColumn, endRow, endColumn)

Unmerges the merged cell in the provided range.

Emits: Hooks#event:beforeUnmergeCells, Hooks#event:afterUnmergeCells

Param	Type	Description
startRow	`number`	Visual start row of the merged cell.
startColumn	`number`	Visual start column of the merged cell.
endRow	`number`	Visual end row of the merged cell.
endColumn	`number`	Visual end column of the merged cell.

unmergeSelection

Source code

mergeCells.unmergeSelection([cellRange])

Unmerges the selection provided as a cell range.

Param	Type	Description
[cellRange]	`CellRange`	`optional` Selection cell range.

updatePlugin

Source code

mergeCells.updatePlugin()

Updates the plugin’s state.

This method is executed when updateSettings() is invoked with any of the following configuration options:

mergeCells