AG Grid Merge Cells: Row and Column Spanning Explained

Yes—AG Grid can make a cell span adjacent rows or columns, but it does not provide a general-purpose spreadsheet-style “merge any selected cells” command. In current releases, row spanning uses enableCellSpan with a column’s spanRows setting, while horizontal spanning uses the column definition’s colSpan callback.

What “merge cells” means in AG Grid

In a spreadsheet, merging usually means selecting a rectangular block of cells and combining it into one larger cell. AG Grid takes a more data-oriented approach: a cell can visually span neighboring cells when the grid’s configuration and row data meet specified conditions. The underlying records and column values remain separate; spanning changes how the grid renders them, not the structure of the data.

This distinction matters when choosing a solution. A grid typically displays a live collection of records that users may sort, filter, edit, or select. Arbitrarily combining cells could make it unclear which record a displayed value belongs to. AG Grid’s spanning features are therefore controlled by column definitions and grid behavior rather than by manually selecting a block and merging it.

Spanning is useful for patterns such as showing a department name once beside several related employees, or creating a section label that occupies several columns. It is not necessary for every repeated value: grouping, custom cell rendering, or a master-detail layout may express the underlying relationship more clearly.

How row spanning works

Row spanning makes a cell cover multiple consecutive rows in one column. In current AG Grid APIs, enable the feature on the grid and opt a particular column into spanning. With spanRows: true, adjacent cells in that column can be combined when their values match. For example, if three neighboring records all have the region value “North,” the region cell can display once across those rows.

const gridOptions = {
  enableCellSpan: true,
  columnDefs: [
    { field: 'region', spanRows: true },
    { field: 'employee' },
    { field: 'sales' }
  ]
};

The repeated values still belong to separate records. AG Grid displays the spanning cell across the matching run, while the employee and sales columns continue to show their row-level information. Row spans are based on neighboring rows: matching values separated by a different value do not form one continuous span.

For more selective behavior, the row-spanning API also supports a callback in versions that provide it. A callback lets an application decide whether neighboring cells should span, rather than relying only on matching values. Check the documentation for the AG Grid version and framework in use before adopting a callback, since API details can vary between releases.

How column spanning works

Column spanning makes one cell occupy space that would otherwise be used by adjacent columns in the same row. This is commonly used for a section or notice row. The relevant column definition uses colSpan, which can return the number of columns to span. For example, a description cell might cover three columns when the record is a section heading, but remain one column wide for ordinary records.

{
  field: 'description',
  colSpan: params => params.data?.kind === 'section' ? 3 : 1
}

That example assumes the description column is followed by at least two columns that can be covered for section rows. Plan the visible column order accordingly: a span cannot be treated like a free-floating rectangle that crosses arbitrary positions in the grid. Also decide what should happen to the neighboring fields in a section record. Their cells are covered visually, but their data is not automatically deleted or combined.

Column spanning is a good fit for a deliberately designed row, such as a “Quarterly totals” label spanning several descriptive columns. If the row needs a completely different layout, a full-width detail row or a custom renderer may be easier to understand and maintain.

Basic setup and a practical example

For a report with repeated region names and occasional section rows, define spanning only for the columns that need it. Keep ordinary columns unspanned. A simplified configuration might look like this:

const gridOptions = {
  enableCellSpan: true,
  columnDefs: [
    { field: 'region', spanRows: true },
    {
      field: 'description',
      colSpan: params => params.data?.kind === 'section' ? 3 : 1
    },
    { field: 'employee' },
    { field: 'sales' }
  ]
};

This illustrates the two separate mechanisms: spanRows handles vertical spans and colSpan handles horizontal spans. They solve different presentation problems, so a grid does not need to use both. The exact placement of columns and the records used for section rows must match the span rule.

In a framework wrapper, the grid options and column definitions are passed through that framework’s normal AG Grid integration; the spanning concepts are the same. Ensure the AG Grid packages are on compatible versions and consult the matching version’s docs if a property is not recognized. AG Grid has evolved its APIs and module setup over time, so copying configuration from an old example can lead to a property being ignored or a required module not being registered.

Sorting, filtering, and changing data

Spans depend on the order and values of the displayed rows. Sorting can change which records are adjacent, and filtering can remove records from between others. As a result, a span that appears in one view may break into separate spans—or become a longer run—in another view. That is expected: the visible result follows the current displayed data, not a permanent merge stored in the records.

Before enabling spans on a sortable or filterable report, test realistic user actions. For instance, sort employee sales from highest to lowest and check whether the region labels remain meaningful next to the reordered records. If a label is intended to apply to a group regardless of sort order, AG Grid row grouping or a grouped data model may be a better representation than relying on adjacent equal values.

Editing also deserves attention. A user may edit one of several records that previously shared a value, changing the boundaries of a row span. Ensure edits refresh or update the relevant row data so the displayed spans reflect the new values. Do not assume that a visual span means only one underlying record can be changed.

Limitations and common problems

It is not arbitrary selection-based merging. Spans are configured through grid behavior and column definitions; users do not simply select any range and merge it like in Excel.
Row spans depend on adjacency. Equal values in nonconsecutive displayed rows do not become one continuous cell.
Horizontal spans need a deliberate column layout. Check what neighboring columns contain and how the result looks when columns are moved, hidden, or resized.
Display and data remain different things. Covered cells are not necessarily removed from the row objects, exports, or application logic. Verify the behavior needed for each output.
Virtualized grids can behave differently from a static table. AG Grid renders rows and columns dynamically for performance. Test spans while scrolling and with the actual row model, data size, and pinned or grouped rows used by the application.

If a span does not appear, first confirm that the grid-level option is enabled for row spanning and that the relevant column has the correct property. Then check whether the values really match, whether the records are adjacent in the displayed order, and whether the installed AG Grid version supports the configuration shown. For a horizontal span, verify that the callback returns the intended number and that the required neighboring columns are present.

When to use grouping or another layout

Spanning is best when the grid remains fundamentally a flat table and a repeated label or section row is the only visual exception. It can reduce clutter in a report, but it may also make row-by-row scanning less obvious. A blank-looking covered cell should not make users wonder whether data is missing.

Consider alternatives when the information has a stronger structure:

Row grouping: use this when records genuinely belong to categories that users should expand, collapse, or summarize. Grouping communicates a hierarchy instead of merely hiding repeated labels.
Cell rendering: use a renderer or formatter when the goal is visual emphasis, an icon, or a label inside one cell—not a larger cell area.
Master-detail: use a detail view when each record needs a separate multi-column panel that does not fit naturally into the main table.
A separate summary row or table: use this when totals or explanatory notes should not be confused with ordinary records.

Choose based on the meaning of the data and the actions users need to take, not just on whether a merged appearance is possible. A visually compact grid is not necessarily easier to sort, edit, navigate by keyboard, or interpret with assistive technology.

Frequently Asked Questions

Can AG Grid merge cells like Excel?

Not as an unrestricted, user-selected merge of any rectangular range. AG Grid offers configured cell spanning for rows and columns, while retaining the underlying row data as separate records.

How do I merge identical values vertically?

In a current release that supports cell spanning, enable enableCellSpan on the grid and set spanRows: true on the relevant column. The values must occur in consecutive displayed rows to form a continuous span.

How do I make one cell cover several columns?

Use the column definition’s colSpan property. It can return a number or use a callback to vary the span for different rows. Make sure the neighboring columns and row data are arranged for the intended result.

Do spans change or combine the row data?

No. Spanning changes the grid’s presentation; it does not automatically combine records or erase values in covered cells. Keep application logic, editing, and export behavior based on the actual data model.

Why did a row span disappear after sorting?

Row spans rely on neighboring displayed rows. Sorting or filtering can change which matching values are adjacent, so the rendered span can change too. If the relationship should persist as a group, consider using AG Grid’s grouping features instead.

Choosing the right approach

For straightforward repeated labels, AG Grid’s row spanning can provide the merged-cell appearance readers expect. For a heading that needs to stretch across a row, use column spanning with a clear rule for when it applies. In both cases, treat the span as a presentation choice—not as a change to the data—and test sorting, filtering, editing, scrolling, export, and keyboard use in the configuration your users will actually see. If the layout represents real parent-child relationships, grouping or detail views are often more robust than simulated spreadsheet merges.

Try it: the Date Difference Calculator: days, months, years and weekdays between two dates, with the DATEDIF formulas.

More in How-to basics

Sources: Function behaviour and menu paths: Microsoft Support documentation for Excel. Method & sources

Spotted an error in this guide? Let us know.