MergedCellsCollection

Description

Defines a container object for the merged cells.

Description

Initializes the cells collection with references to the MergeCells plugin and the Handsontable instance.

Members

mergedCells

Source code

mergedCellsCollection.mergedCells : Array<MergedCellCoords>

Array of merged cells.

mergedCellsMatrix

Source code

mergedCellsCollection.mergedCellsMatrix : Array

Matrix of cells (row, col) that points to the instances of the MergedCellCoords objects.

Methods

add

Source code

mergedCellsCollection.add(mergedCellInfo, [auto]) ⇒ MergedCellCoords | boolean

Add a merged cell to the container.

Param	Type	Default	Description
mergedCellInfo	`object`		The merged cell information object. Has to contain `row`, `col`, `colspan` and `rowspan` properties.
[auto]	`boolean`	`false`	`optional` `true` if called internally by the plugin (usually in batch).

Returns: MergedCellCoords | boolean - Returns the new merged cell on success and false on failure.

capturePhysicalSpans

Source code

mergedCellsCollection.capturePhysicalSpans(axis) ⇒ Map<MergedCellCoords, Array<number>>

Capture the physical indexes covered by every merged cell along an axis.

Used by the manual row/column move and column freeze integrations to translate merges through a reorder: the captured spans pin each merge to the underlying data so the merge can be repositioned (and split, if a non-contiguous run results) after the visual sequence changes.

Param	Type	Description
axis	`'column'` `'row'`	Which axis the upcoming reorder targets.

Returns: Map<[MergedCellCoords](/docs/vue-data-grid/api/merged-cell-coords/), Array<number>> - Map of merge -> physical indexes along the axis.

clear

Source code

mergedCellsCollection.clear()

Clear all the merged cells.

detectContiguousRuns

Source code

MergedCellsCollection.detectContiguousRuns(sortedAscending) ⇒ Array<{start: number, length: number}>

Group an ascending list of integers into contiguous runs.

Param	Type	Description
sortedAscending	`Array<number>`	Already-sorted ascending visual indexes.

filterOverlappingMergeCells

Source code

mergedCellsCollection.filterOverlappingMergeCells(mergedCellsInfo) ⇒ Array<{row: number, col: number, rowspan: number, colspan: number}>

Filters merge cells objects provided by users from overlapping cells.

Param	Type	Description
mergedCellsInfo	`Object`	The merged cell information object. Has to contain `row`, `col`, `colspan` and `rowspan` properties.

get

Source code

mergedCellsCollection.get(row, column) ⇒ MergedCellCoords | boolean

Get a merged cell from the container, based on the provided arguments. You can provide either the “starting coordinates” of a merged cell, or any coordinates from the body of the merged cell.

Param	Type	Description
row	`number`	Row index.
column	`number`	Column index.

Returns: MergedCellCoords | boolean - Returns a wanted merged cell on success and false on failure.

getBottomMostRowIndex

Source code

mergedCellsCollection.getBottomMostRowIndex(range, visualRowIndex) ⇒ number

Gets the bottom-most visual row index that do not intersect with other merged cells within the provided range.

Param	Type	Description
range	`CellRange`	The range to search within.
visualRowIndex	`number`	The visual row index to start the search from.

getByRange

Source code

mergedCellsCollection.getByRange(range) ⇒ MergedCellCoords | false

Get the first-found merged cell containing the provided range.

Param	Type	Description
range	`CellRange`	The range to search merged cells for.

getByVisualColumn

Source code

mergedCellsCollection.getByVisualColumn(column) ⇒ Array<MergedCellCoords>

Get the merged cells that cover any cell of the provided visual column. The cost scales with the total number of merged cells, not with the number of table rows. Merges purged from the lookup matrix (fully hidden) are not returned.

Param	Type	Description
column	`number`	Visual column index.

Returns: Array<MergedCellCoords> - Array of merged cells covering the column.

getByVisualRow

Source code

mergedCellsCollection.getByVisualRow(row) ⇒ Array<MergedCellCoords>

Get the merged cells that cover any cell of the provided visual row. The cost scales with the number of merged cells covering the row, not with the number of table columns. Merges purged from the lookup matrix (fully hidden) are not returned.

Param	Type	Description
row	`number`	Visual row index.

Returns: Array<MergedCellCoords> - Array of merged cells covering the row.

getEndMostColumnIndex

Source code

mergedCellsCollection.getEndMostColumnIndex(range, visualColumnIndex) ⇒ number

Gets the end-most visual column index that do not intersect with other merged cells within the provided range.

Param	Type	Description
range	`CellRange`	The range to search within.
visualColumnIndex	`number`	The visual column index to start the search from.

getFirstRenderableCoords

Source code

mergedCellsCollection.getFirstRenderableCoords(row, column) ⇒ CellCoords

Get the first renderable coords of the merged cell at the provided coordinates.

Param	Type	Description
row	`number`	Visual row index.
column	`number`	Visual column index.

Returns: CellCoords - A CellCoords object with the coordinates to the first renderable cell within the merged cell.

getStartMostColumnIndex

Source code

mergedCellsCollection.getStartMostColumnIndex(range, visualColumnIndex) ⇒ number

Gets the start-most visual column index that do not intersect with other merged cells within the provided range.

Param	Type	Description
range	`CellRange`	The range to search within.
visualColumnIndex	`number`	The visual column index to start the search from.

getTopMostRowIndex

Source code

mergedCellsCollection.getTopMostRowIndex(range, visualRowIndex) ⇒ number

Gets the top-most visual row index that do not intersect with other merged cells within the provided range.

Param	Type	Description
range	`CellRange`	The range to search within.
visualRowIndex	`number`	The visual row index to start the search from.

getWithinRange

Source code

mergedCellsCollection.getWithinRange(range, [countPartials]) ⇒ Array<MergedCellCoords>

Get the merged cells contained in the provided range. Each merged cell is returned once, even when it spans multiple cells of the range. The cost scales with the number of merged cells in the collection, not with the area of the range.

Param	Type	Default	Description
range	`CellRange`		The range to search merged cells in.
[countPartials]	`boolean`	`false`	`optional` If set to `true`, all the merged cells overlapping the range will be taken into calculation.

Returns: Array<MergedCellCoords> - Array of found merged cells, ordered by their first covered cell in row-major order.

IS_OVERLAPPING_WARNING

Source code

MergedCellsCollection.IS_OVERLAPPING_WARNING(mergedCell) ⇒ string

Get a warning message for when the declared merged cell data overlaps already existing merged cells.

Param	Type	Description
mergedCell	`Object`	Object containing information about the merged cells that was about to be added.

isFirstRenderableMergedCell

Source code

mergedCellsCollection.isFirstRenderableMergedCell(row, column) ⇒ boolean

Check whether the provided row/col coordinates direct to a first not hidden cell within merge area.

Param	Type	Description
row	`number`	Visual row index.
column	`number`	Visual column index.

isOverlapping

Source code

mergedCellsCollection.isOverlapping(mergedCell) ⇒ boolean

Check if the provided merged cell overlaps with the others already added.

Param	Type	Description
mergedCell	`MergedCellCoords`	The merged cell to check against all others in the container.

Returns: boolean - true if the provided merged cell overlaps with the others, false otherwise.

relocateInMatrix

Source code

mergedCellsCollection.relocateInMatrix(relocations)

Relocates a batch of merges in the coords->merge lookup matrix, applying each merge’s new visual top-left. Used after re-anchoring to the visible rows on a trimming/sort change. Incremental alternative to a full rebuild — only the cells of the affected merges are touched. Runs in two phases (remove all, then re-add all) so merges that swap visual positions don’t clobber each other’s freshly written entries.

Param	Type	Description
relocations	`Array<{mergedCell: MergedCellCoords, row: number, col: number}>`	The merges to move together with their new top-left visual `row`/`col`.

remove

Source code

mergedCellsCollection.remove(row, column) ⇒ MergedCellCoords | boolean

Remove a merged cell from the container. You can provide either the “starting coordinates” of a merged cell, or any coordinates from the body of the merged cell.

Param	Type	Description
row	`number`	Row index.
column	`number`	Column index.

Returns: MergedCellCoords | boolean - Returns the removed merged cell on success and false on failure.

removeFromMatrix

Source code

mergedCellsCollection.removeFromMatrix(merges)

Removes a batch of merges from the coords->merge lookup matrix without touching the mergedCells list. Used to purge merges whose whole visible span has been trimmed away, so their stale entries cannot resolve to a phantom merge once a different row surfaces at the same visual slot. The merges themselves are kept (their physical anchor lets them be re-added when visible).

Param	Type	Description
merges	`Array<MergedCellCoords>`	The merges to remove from the matrix.

shiftCollections

Source code

mergedCellsCollection.shiftCollections(direction, index, count)

Shift the merged cell in the direction and by an offset defined in the arguments.

Param	Type	Description
direction	`string`	`right`, `left`, `up` or `down`.
index	`number`	Index where the change, which caused the shifting took place.
count	`number`	Number of rows/columns added/removed in the preceding action.

translateAfterAxisMove

Source code

mergedCellsCollection.translateAfterAxisMove(axis, snapshot)

Translate the merged cells collection after a manual row/column reorder, splitting merges whose physical indexes are no longer contiguous in the new visual order.

Note: single-cell fragments (colspan === 1 && rowspan === 1) are dropped because they no longer represent a merge. The user-facing behavior (auto-split + silent drop of singletons) is documented in docs/content/guides/cell-features/merge-cells/merge-cells.md under “Behavior during row/column reorder and column freeze”.

Param	Type	Description
axis	`'column'` `'row'`	Axis that was reordered.
snapshot	`Map<MergedCellCoords, Array<number>>`	Snapshot taken before the reorder.