Skip to content
DzGrid

spans

Draws merged cells, cells spanning rows or columns, full-width rows and grouped headers.

Importimport { spans } from '@dzgrid/dom/spans';
Signaturespans(o?: { readonly acrossLevels?: boolean; } | undefined): GridFeature
Textsno bundle of its own
Own CSSSPANS_CSS — to add yourself with injectStyles: false
Declared inpackages/dom/src/spans/index.ts
OptionsType
acrossLevelsboolean

What it does

Section titled “What it does”

spans() draws what the columns and settings ask for: equal neighbours merged into one tall cell (merge), spans decided by the data (rowSpan, colSpan), rows one cell wide (fullWidth), and the header rows of column groups (a column with children). Span rules given without it are ignored, and the grid tells one missing-feature warning per kind of rule.

Spans are computed on the rows as shown: after a sort or a filter, the rows now side by side merge again. A merge never crosses a page, a pinned edge, a group of rows or a gap. The label of a long merged cell moves with the scroll, so it stays in view. The keys treat a spanned cell as one stop, and moving back returns to the row you came from; a click on a tall cell acts on the row under the pointer. A CSV file writes the value on every row the cell covers.

In a tree, a merge joins siblings only, unless acrossLevels is on; full-width rows stay refused beside a tree (unsupported-combination). Master/detail refuses spans(). A span over another is dropped (span-overlap); one cut by a pinned edge or by the end of the rows tells span-clipped; a bad span (merge with rowSpan or colSpan on one column, a rule that throws) invalid-span; a bad column group invalid-column-group.

Options

Section titled “Options”
  • acrossLevels: in a tree, outside a row’s tree column, a merge goes on across a node and its children shown, under one top-level row. Off by default: a merge stops where the level changes.

Read when the grid is made.

Example

Section titled “Example”
import { createGrid } from '@dzgrid/dom';
import type { ColumnOrGroup } from '@dzgrid/core';
import { spans } from '@dzgrid/dom/spans';
import { EN } from '@dzgrid/dom/locales/en';


type Hike = { id: string; valley: string; trail: string; km: number };


const columns: ColumnOrGroup<Hike>[] = [
  { id: 'valley', header: 'Valley', merge: true },
  { id: 'walk', header: 'Walk', children: [
    { id: 'trail', header: 'Trail' },
    { id: 'km', header: 'Distance (km)', type: 'number' },
  ] },
];


createGrid<Hike>(document.getElementById('walks')!, {
  rows: [
    { id: 'w1', valley: 'Green valley', trail: 'Fern path', km: 4.5 },
    { id: 'w2', valley: 'Green valley', trail: 'Waterfall loop', km: 7 },
    { id: 'w3', valley: 'Stone valley', trail: 'Ridge walk', km: 11 },
  ],
  columns,
  getRowId: (w) => w.id,
  messages: EN,
  features: [spans()],
});

Live demo

Section titled “Live demo”

Sort by Distance: the valleys split, then merge again when sorted back by Valley.

See also

Section titled “See also”