Skip to content
ZenGrid

Expanding Groups

Enterprise

Introduction

Section titled “Introduction”

Every group header ZenGrid renders is collapsible — clicking the chevron (or anywhere on the banner) toggles it, and the rows beneath appear or disappear. This page is about controlling that expansion: which groups start open, how deep to open a hierarchy by default, and how to drive it all from code — including saving and restoring the exact set of open/closed groups.

All of it lives on the rowGrouping() manager returned when you set the feature up (see Overview); there’s nothing extra to wire.

Which groups start open

Section titled “Which groups start open”

By default every group starts expanded. Two options change that:

  • expandedByDefault: false — every group starts collapsed (just the top banners show).
  • groupDefaultExpanded: N — open the first N nesting levels and collapse anything deeper. This is the precise control for deep hierarchies and it overrides expandedByDefault:
    • groupDefaultExpanded: -1 — open every level (fully expanded).
    • groupDefaultExpanded: 0 — collapse all (same as expandedByDefault: false).
    • groupDefaultExpanded: 1 — open only the outermost groups; their children start collapsed.
    • groupDefaultExpanded: 2 — open the first two levels, and so on.
rowGrouping({
  groupBy: [2, 1, 5],          // Region -> Role -> Status (three levels)
  groupDefaultExpanded: 1,     // only the Region banners open on load
});

A group at 0-based level shows its children when level < groupDefaultExpanded, so the value reads as “how many levels of rows are visible under the top banners.”

Driving expansion from the API

Section titled “Driving expansion from the API”

The manager exposes the full expand/collapse surface:

  • expandAll() / collapseAll() — open or close every group.
  • expandToLevel(n) — open the first n levels and collapse the rest, exactly like groupDefaultExpanded but applied live (-1 = all, 0 = none).
  • setExpanded(path, open) / toggle(path) — open or close one group by its path (a group’s path is its key, joined by a space through the nesting chain — e.g. 'EU-West', or 'EU-West Analyst').
  • isExpanded(path) — query a single group’s state.
  • onExpandedChanged({ path, expanded }) — a callback fired on every user-driven or programmatic toggle (great for logging or syncing UI).

Saving & restoring state

Section titled “Saving & restoring state”

A user’s open/closed choices are worth persisting across a reload or a data refresh. Two methods snapshot and restore the exact expansion state:

  • getCollapsedPaths(): string[] — a serialisable list of every currently collapsed group. Stash it (local storage, your app state, a URL).
  • setCollapsedPaths(paths) — restore that snapshot; every listed group closes, everything else opens.
const saved = grouping.getCollapsedPaths();   // persist this
// ...later...
grouping.setCollapsedPaths(saved);            // restore the exact state

Try it live

Section titled “Try it live”

groupDefaultExpanded:1 opens only the Region banners. The controls call expandToLevel(n) — open the first n levels live — or collapse all. Level 3 reveals the leaf rows under Region -> Role -> Status.

Notes

Section titled “Notes”
  • groupDefaultExpanded wins over expandedByDefault. Set the numeric one when you care about depth; the boolean is a shorthand for all-open/all-closed.
  • Paths are stable keys, not indices. A group’s path is built from its key chain ('EU-West', 'EU-West Analyst'), so setExpanded/getCollapsedPaths survive re-sorting siblings — but change if the underlying key changes.
  • State resets on re-group. Changing the grouping columns (setGroupBy, addGroup, removeGroup) rebuilds the tree and re-applies the default expansion policy, so snapshot first if you need to carry state across a re-group.
  • expandToLevel mirrors the config. expandToLevel(n) at runtime is exactly what groupDefaultExpanded: n does on load — -1 all, 0 none.

Next

Section titled “Next”