grafloria

Learn / Groups

Groups

A group is not a rectangle drawn behind some nodes — it is a container the engine understands: members move together, collapse is reversible by construction, and nesting reflows parents around children.

Creating and membership

import { GroupModel } from '@grafloria/engine';

diagram.addGroup(new GroupModel({
  id: 'ingest-stage',
  position: { x: 0, y: 0 }, size: { width: 320, height: 180 },
}));

await engine.addToGroup('ingest-stage', 'a');    // (groupId, entityId) — group first
await engine.addToGroup('ingest-stage', 'b');
await engine.removeFromGroup('ingest-stage', 'b');

Members drag with the group, and interactive membership works too — drag a node into a group's frame and it joins; groups can contain groups. Query structure with diagram.getGroups(), diagram.getGroup(id), diagram.getAncestors(id) / getDescendants(id).

Collapse is a reversible snapshot

await engine.collapseGroup('ingest-stage');   // members hide, links re-route to the header
await engine.expandGroup('ingest-stage');     // everything returns exactly where it was

Collapse stores a snapshot on the group — member world-positions and the links removed at collapse time — so a collapsed diagram serializes, round-trips, and expands correctly later, even in a different session. Links from outside to a hidden member re-anchor to the collapsed header, and parallel edges merge into one until expand.

Nesting and fit

Containers reflow: a group can fit itself around its already-fitted children, and a resize cascades down into nested containers' own reflows. That is what makes swimlanes, BPMN pools and stage-based pipelines behave — moving a lane moves its contents; growing content grows the lane.

Frameless groups — layout without chrome

const g = diagram.getGroup('kpi-row');
g.setMetadata('frameChrome', 'none');    // no border, no header — pure layout container

A frameless group is the primitive under the dashboard kit's grid: cells that pack and drag without looking like "a group". Use it whenever you want container behavior without container pixels.

Groups participate in everything else on this site: group operations are commands (undoable), groups serialize in the document, ELK lays out nested structures natively, and a collapsed group exports exactly as it looks on screen.

Live: group demos — drag in, collapse, nest →

Where next

  • The model — where groups sit among nodes and links.
  • Kits — the dashboard grid built on frameless groups.