React Grid Cell Merging

    The Ignite UI for React Grid provides a Cell Merging feature that combines two or more adjacent cells with the same value into a single, larger cell. Merging is applied vertically within a column and helps improve readability by reducing duplicate values. The feature can be configured to merge cells either by default matching data values or by applying a custom condition.

    React Grid Cell Merging Example

    Enabling and Using Cell Merging

    Cell merging in the grid is controlled at two levels:

    • Grid-level merge mode – determines when merging is applied.
    • Column-level merge toggle – determines which columns can merge cells.

    Grid Merge Mode

    The grid exposes a cellMergeMode property that accepts values from the GridCellMergeMode enum:

    • always - Merges any adjacent cells that meet the merging condition, regardless of sort state.
    • onSort - Merges adjacent cells only when the column is sorted (default value).
    <IgrGrid data={data} cellMergeMode={cellMergeMode} >
    ...
</IgrGrid>

    const cellMergeMode: GridCellMergeMode = 'always';

    Column Merge Toggle

    At the column level, merging can be enabled or disabled with the merge property.

    <IgrColumn field="OrderID" merge={true}></IgrColumn>
<IgrColumn field="ShipperName" merge={false}></IgrColumn>

    In the above example:

    • The OrderID column will merge adjacent duplicate values.
    • The ShipperName column will render normally without merging.

    Combined Example

    <IgrGrid data={data} cellMergeMode={cellMergeMode} autoGenerate={false}>
    <IgrColumn field="OrderID" header="Order ID" merge={true}></IgrColumn>
    <IgrColumn field="ShipperName" header="Shipper Name" merge={true}></IgrColumn>
    <IgrColumn field="Salesperson" header="Salesperson"></IgrColumn>
</IgrGrid>

    const cellMergeMode: GridCellMergeMode = 'onSort';

    Here, the grid is set to merge only when columns are sorted, and both Category and Product columns are configured for merging.

    Custom Merge Conditions

    In addition to the built-in always and onSort modes, the grid allows you to define a custom condition for merging cells through the mergeStrategy property. This strategy controls both how cells are compared and how merged ranges are calculated.

    Merge Strategy Class

    A custom merge strategy must implement the IgrGridMergeStrategy class:

    export declare class IgrGridMergeStrategy {
    merge: (
        data: any[],
        field: string,
        comparer: (prevRecord: any, currentRecord: any, field: string) => boolean,
        result: any[],
        activeRowIndex?: number,
        grid?: GridType
    ) => any[];

    comparer: (prevRecord: any, record: any, field: string) => boolean;
}
    • merge - defines how merged cells are produced.
    • comparer - defines the condition to decide if two adjacent records should be merged.

    Extending the Default Strategy

    If you only want to customize part of the behavior (for example, the comparer logic), you can extend the built-in IgrDefaultMergeStrategy and override the relevant methods.

    export class MyCustomStrategy extends IgrDefaultMergeStrategy {
    /* Merge only cells within their respective projects */
    public override comparer(prevRecord: any, record: any, field: string): boolean {
        const a = prevRecord[field];
        const b = record[field];
        const projA = prevRecord['ProjectName'];
        const projB = record['ProjectName'];
        return a === b && projA === projB;
    }
}

    Applying a Custom Strategy

    Once defined, assign the strategy to the grid through the mergeStrategy property:

    <IgrGrid data={data} mergeStrategy={customStrategy}>
  <IgrColumn field="ActionID" merge={true}></IgrColumn>
  <IgrColumn field="ProjectName" merge={true}></IgrColumn>
</IgrGrid>

    const customStrategy = new MyCustomStrategy() as IgrGridMergeStrategy;

    Feature Integration

    Due to the specific behavior of merged cells it has to be noted how exactly it ties together with some of the other features of the grid:

    • Expand/Collapse: if a feature (such as master-detail, grouping, etc.) generates a non-data row, then the cell merging is interrupted and the group will be split.
    • Excel export: merged cells remain merged when exported to Excel.
    • Column pinning: cells remain merged when a column is pinned and are displayed in the pinned area.
    • Row pinning: cells merge only withing their containing area, i.e. cells of pinned rows merge only with cells of other pinned rows, while cells of unpinned rows merge only with cells of unpinned rows.
    • Updating/Editing: since activation breaks the merge sequence, only a single cell will be in edit mode.
    • Row selection: if selected rows intersect merged cells, all related merged cells should be marked as part of the selection.
    • Navigation/Activation: when a cell is active, all merged cells in the same row become single cells, i.e. their merge sequence is broken. This also includes activation via keyboard navigation.

    [!NOTE] If a merged cell is clicked, the closest cell from the merge sequence will become active.

    Limitations

    Known Limitations Description
    Cell merging is not supported in combination with Multi-row Layout. Both span complex layouts that don't make sense when combined. A warning will be thrown if such invalid configuration is detected.

    API References

    Additional Resources

    Our community is active and always welcoming to new ideas.