merge

Merges a column’s equal neighbours into one cell, as in a spreadsheet.

Type	true | ((a: SpanCtx<T>, b: SpanCtx<T>) => boolean) | { readonly same?: (a: SpanCtx<T>, b: SpanCtx<T>) => boolean; readonly within?: readonly string[] }
Default	not set
Live update (update())	Yes — give the columns again (update({ columns }))
Declared in	packages/core/src/columns/defs.ts

What it does

It needs the spans() feature from @dzgrid/dom/spans; without it the grid tells a missing-feature warning and draws plain cells.

• true merges rows whose values have the same stable text (e and é stay apart); blank cells never merge.
• A function (a, b) => boolean decides whether two neighbours merge.
• { same, within }: same as the function, within a list of columns whose change cuts a run (a town merges only inside its region).

Merges follow the rows on screen: after a sort or a filter, the rows now side by side merge again. A merge never crosses a page, a pinned edge or a group of rows. A column cannot have merge together with rowSpan or colSpan (invalid-span). In a CSV file the value is written on every row it covers.

Example

import { createGrid } from '@dzgrid/dom';
import { spans } from '@dzgrid/dom/spans';
import { EN } from '@dzgrid/dom/locales/en';

type Visit = { id: string; region: string; town: string; day: string };

createGrid<Visit>(document.getElementById('visits')!, {
  rows: [{ id: 'v1', region: 'North', town: 'Ashby', day: '2026-04-01' }],
  columns: [
    { id: 'region', header: 'Region', merge: true },
    { id: 'town', header: 'Town', merge: { within: ['region'] } },
    { id: 'day', header: 'Day', type: 'day' },
  ],
  getRowId: (r) => r.id,
  messages: EN,
  features: [spans()],
});

Live demo

Region and Town merge; Town only inside its region.

See also

• rowSpan, colSpan.
• Columns.