synergycodes/ng-diagram/ng-diagram-performance

Performance and virtualization

How to keep large ng-diagram editors fast: virtualization, batching, cheap templates, minimap settings, measuring. Viewport fitting is in ng-diagram-viewport, transactions in detail in ng-diagram-transactions, hiding elements in ng-diagram-visibility, the minimap in ng-diagram-minimap.

Without virtualization the library is built for hundreds of nodes: the docs performance test renders 500 default nodes in a 25 × 20 grid with 499 edges. For more, turn on virtualization.

Rules

• Batch changes. Every service call is one full update pass: all middlewares (yours too), edge routing, z-index and events. Send one updateNodes([...]) for many nodes, and wrap different operations in one transaction.
• Keep one model. A new model object (for example computed(() => initializeModel(data(), injector)) fed by changing data) re-initializes the whole diagram: every element is measured again and diagramInit fires again. Update the existing model with the services; use initializeModel to load a different diagram.
• Virtualization (since 1.0.0) is chosen when the model initializes. Put it in [config] before init. To switch it, change [config] and initialize the model again ([config] alone is read only at model init). Do not switch virtualization.enabled with updateConfig: it only flips the flag, so the render strategy and the pan handler chosen at init stay, while code that checks the flag later (zoomToFit, [ngDiagramHidden], port cleanup) switches. The diagram ends up half in each mode.
• Hide many elements with one updateNodes call that sets the model hidden flag (since 1.4.0). Under virtualization the [ngDiagramHidden] template binding (since 1.4.0) is ignored.
• Keep node templates cheap: ChangeDetectionStrategy.OnPush, derived values in computed, no heavy work in template expressions. Only a node whose properties really change gets a new object, so the templates of the other nodes keep the same input (with OnPush, Angular skips them).
• Do not put heavy computeds on modelService.nodes()/edges() in always-visible UI: these signals change on every node change, for example on every frame of a drag.

Enable virtualization

readonly config = signal<NgDiagramConfig>({
  virtualization: {
    enabled: true, // default false
    padding: 0.5, // default 0.5 - extra render area around the visible viewport
    idleDelay: 100, // default 100 ms - wait after panning stops before rendering newly visible elements
  },
});
readonly model = signal(initializeModel(bigData));
// `enabled` is read when the model initializes: change the config AND re-initialize from plain data
setVirtualization(enabled: boolean): void {
  const data: Partial<Model> = JSON.parse(this.modelService.toJSON()); // keeps size, points, metadata.viewport
  this.config.update((config) => ({ ...config, virtualization: { ...config.virtualization, enabled } }));
  this.model.set(initializeModel(data, this.injector)); // outside an injection context: pass the injector
}

Template: <ng-diagram [model]="model()" [config]="config()" />. Re-initializing passes plain data: initializeModel(modelService.getModel()) does not compile (the adapter is not Partial<Model>).

• padding: the render area grows on each side by max(viewport width, height) × padding screen px. When zoomed out (scale < 1) this extra area shrinks in proportion to the scale.
• idleDelay: while the user pans, the rendered set stays the same; idleDelay ms after panning stops, newly visible elements are added. During zoom the set is refreshed 300 ms after the last scale change. Fast pans can show empty areas for a moment: raise padding (more DOM) or lower idleDelay (more renders).
• padding and idleDelay are read on every use, so updateConfig({ virtualization: { padding: 1 } }) works at runtime. enabled does not.

What changes with virtualization

Give nodes a size in your data (or keep the one toJSON() saves): never-rendered nodes then have real bounds for the render-area test (without a size a node counts as 1 × 1 px at its position), the minimap outline, layouts and custom fits.

Batch updates

// Slow: one full update pass (middlewares, routing, events) per node
async moveOneByOne(positions: Map<string, Point>): Promise<void> {
  for (const [id, position] of positions) {
    await this.modelService.updateNode(id, { position });
  }
}
// Fast: one pass for all nodes
async moveAll(positions: Map<string, Point>): Promise<void> {
  await this.modelService.updateNodes([...positions].map(([id, position]) => ({ id, position })));
}
// Different operations: one transaction = one commit
async importChunk(newNodes: Node[], newEdges: Edge[], obsoleteEdgeIds: string[]): Promise<void> {
  await this.diagram.transaction(() => {
    this.modelService.deleteEdges(obsoleteEdgeIds); // do not reuse these ids below: adds run before removes
    this.modelService.addNodes(newNodes);
    this.modelService.addEdges(newEdges);
  });
}

A property set to the value it already has is not a change (positions and sizes are compared by value, other properties by reference), so a node whose data gets a new object always counts as changed.

Cheap node templates

@Component({
  selector: 'app-task-node',
  imports: [NgDiagramPortComponent],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <div class="task">
      <span>{{ node().data.title }}</span>
      <span>{{ percent() }}</span>
    </div>
    <ng-diagram-port id="in" type="target" side="left" />
    <ng-diagram-port id="out" type="source" side="right" />
  `,
})
export class TaskNodeComponent implements NgDiagramNodeTemplate<TaskData> {
  node = input.required<Node<TaskData>>();
  // Derived values as computed signals: recalculated only when this node changes
  readonly percent = computed(() => `${Math.round(this.node().data.progress * 100)}%`);
}

• Level of detail: when zoomed out, render a lighter variant, e.g. computed(() => viewport.scale() < 0.75) switching the template content (the Org Chart template does this). If the variant has another size, the node is measured again.
• Minimap on large diagrams: <ng-diagram-minimap [deferNodeUpdates]="true" /> (since 1.2.0) freezes minimap nodes during drag, resize and rotate. Prefer nodeStyle or CSS over minimapNodeTemplateMap, which renders Angular components in foreignObject per node.
• Box selection on very large diagrams: boxSelection: { realtime: false } selects once on release instead of running one update pass per pointer move.

Measure

• debugMode: true (in [config] or updateConfig) logs [ngDiagram] Render: +<added> -<removed> nodes (total: <n>): <ms>ms whenever the set of rendered nodes changes (time from the render call until two animation frames later), and logs every update with its full before/after state. The state logs are heavy on big diagrams: use them to see what runs, turn them off when you time things, and never ship them.
• For real numbers, record a drag or pan in the browser's performance profiler and look for long scripting tasks in your own templates and middlewares.

Edge cases

• Switching virtualization re-initializes the diagram: node selection is cleared (toJSON() drops node selected but keeps edge selected), diagramInit fires again, and zoom.zoomToFit.onInit runs again (with virtualization on, it only logs the warning).
• Your middlewares run on every update pass, including each drag frame. Return early (next()) when the update does not concern them; never await service calls inside a middleware (see ng-diagram-middleware).
• While the user pans, viewport updates skip the middleware chain, so middlewares cost nothing during pans.
• Many template [ngDiagramHidden] bindings changing in one change detection cycle are processed together, but the model flag is still cheaper.

Symptom → fix

Verify before you answer

• Check the installed version in node_modules/ng-diagram/package.json (or the lockfile). This skill describes ng-diagram 1.4.0; anything marked "since vX.Y" does not exist in older versions.
• Confirm exact names and signatures in node_modules/ng-diagram/ng-diagram.d.ts (its TSDoc has @since tags) instead of guessing.
• For more detail, use the ng-diagram docs MCP tools (search_docs, get_doc, search_symbols, get_symbol) when available, or https://www.ngdiagram.dev/docs.