Skip to content
ZenGrid

Grouping Toolbar

Enterprise

Introduction

Section titled “Introduction”

The earlier pages set the grouping up in code. The Grouping Toolbar hands that control to the user: a toolbar of chips — one per grouped column — that sits above the grid. Remove a chip to ungroup, drag chips to re-order the nesting, or pick a new column from the add menu. It’s a thin, presentational view over the same rowGrouping() manager, so every change it makes flows through setGroupBy/addGroup/removeGroup — and, conversely, any programmatic re-grouping re-renders the chips to match.

Build the panel with rowGroupPanel(): give it the manager it should drive and the columns it may group by (each a source index + label), then mount it above the grid.

const grouping = rowGrouping({ groupBy: [2] });   // start grouped by Region


const grid = new Zengrid(mount, {
  fullWidthProvider: grouping.provider,
  columns: dataColumns,
});
grouping.attach(grid);
grouping.setData(rows);


const panel = rowGroupPanel({
  grouping,                                        // the manager to drive + mirror
  columns: [
    { col: 1, label: 'Role' },
    { col: 2, label: 'Region' },
    { col: 5, label: 'Status' },
  ],
});
mount.before(panel.element);                       // toolbar above the grid

Customising the panel

Section titled “Customising the panel”

Everything the panel shows is tunable on rowGroupPanel():

  • columns — the groupable columns ({ col, label }). The add menu lists the ones not already grouped; chips read their label here.
  • allowRemove (default true) — show the × remove control on each chip.
  • allowReorder (default true) — let chips be dragged to change the nesting order (outermost is leftmost).
  • allowAdd (default true) — show the add menu of ungrouped columns.
  • addLabel — the add-menu button text (default Group by +).
  • placeholder — the text shown when nothing is grouped.
  • chipLabel({ col, label, index }) — return the text drawn on a chip (e.g. prefix it, or number the nesting level).
  • onChange(groupBy) — called with the new grouping (source column indices) after any panel-driven change.

The panel also exposes refresh() (rebuild the chips) and destroy() (unsubscribe and detach). It subscribes to the manager, so you rarely need refresh() yourself.

Try it live

Section titled “Try it live”

Grouped by Region. Open "Group by +" to nest Role or Status, drag a chip to re-order, or click a chip × to ungroup. Every change re-groups the grid live.

Notes

Section titled “Notes”
  • The panel drives the manager — it owns no grouping state. Chips are always rendered from grouping.getGroupBy(), so the panel and the grid can never disagree. A programmatic setGroupBy/addGroup/removeGroup re-renders the chips automatically.
  • Order is nesting. The leftmost chip is the outermost group. Dragging a chip calls setGroupBy with the re-ordered levels, preserving any per-level comparator/keyGetter you configured on the manager.
  • The add menu self-filters. It only lists columns that aren’t already grouped; once every column is grouped, the button disappears.
  • Mount it where you like. panel.element is a plain element — put it above the grid (mount.before(...)), in a card header, or anywhere in your layout. Call panel.destroy() when you tear the grid down.

Next

Section titled “Next”
  • Expanding Groups — control which groups start open and drive expand/collapse in code.
  • Grouping Data — the setGroupBy / addGroup / removeGroup API the panel is built on.