ng-diagram: an Angular library for node-based editors

What the library is, and what it claims to be better at

The readme describes ng-diagram as a capable Angular library for building interactive diagrams, node-based editors, and visual programming interfaces, designed with Angular and TypeScript, offering a complete toolkit for creating sophisticated, customizable, high-performance diagramming applications.

And then it makes the differentiation argument in one line: unlike generic diagramming libraries, it is Angular-first, built on Angular signals and templates for integration and performance.

That is a narrower claim than it looks, and it is the one that matters. A generic diagramming library for the web will draw a box and an arrow, and it will let you configure the box's label and colour. It will not let you put your own application component inside the box, because it has no idea what a component is in your framework. A library that is built on templates can, and that is the difference between a diagram tool and an editor framework.

The feature list shows the shape of that claim. Nodes are draggable, resizable, and rotatable. Edges can be routed orthogonally, as polylines, or as curves, with custom arrowheads, with labels, and there are floating edges that connect without needing ports. There are groups, which are container nodes that nest and that can be dragged as a unit. And there is a built-in palette for dragging new nodes onto the canvas, a minimap for navigation, a keyboard shortcut system, touch support including pinch zoom and long press selection, and a design system built on variables with light and dark themes.

So the library is not a drawing primitive. It is an editor with the drawing primitives included, and the custom template support is what turns it into a framework for a product.

The project is Apache 2 licensed, the last push was on 2026-10-14, and the release notes make the direction of travel unusually clear: the newest version is about edge relinking, dangling edges and hidden elements, the one before it about an awaitable API and gesture reliability, and the one before that about smoother trackpad gestures and pan fixes. Three releases in four months, each fixing a specific thing a user would notice.

The five templates, and what they tell you

The templates section is the most revealing part of the readme, because five production-ready applications built with the library say more about its range than any feature list.

The first is an organisational chart: tree-based, with drag-and-drop reordering, expanding and collapsing, layout from a separate engine, a minimap, and a dark and light theme. The second is an electronic circuit editor, with a searchable library of parts as vector graphics, smart wire junctions, and export to vector, raster, and data formats. The third is the most specialised: a single-line diagram editor for high-voltage substations, using the symbols from an international standard, with a properties panel driven by a schema. The fourth is an audio and video signal flow editor with typed connectors, meaning the connector type itself carries meaning, and export to formats a mechanical drafting tool reads. The fifth is a production-line monitor with two modes, a live data feed, key performance indicators coloured by their thresholds, and sparklines.

Read as a set, they cover three quite different uses. The organisational chart is a document viewer with editing. The substation diagram and the circuit editor are engineering tools, where the symbols and the connections have fixed meanings and the layout has to be precise. And the production line monitor is a live dashboard that happens to be drawn as a graph.

That last one is the most interesting for a library, because a live data feed changes what the editor has to be. A diagram that never changes is a picture. A diagram that updates from a feed is a rendering of application state, and the library is being used as a view layer over data rather than as a document format.

Each template has a live demo and a source repository, and the instruction is to fork and customise. So the library's commercial argument is not that you will not write this yourself, which is false, but that you will not write the pan and zoom and the selection and the group dragging and the minimap and the keyboard handling and the copy and paste, which is a great deal of work for the same result in every application.

The library also has a live demo of its own and a separate repository for it, and a video course that is being produced in episodes: project setup, a properties panel using signals, and custom node types in a workflow builder. That last one is the subject the library exists for, and it is free.

The quick start, and the stylesheet warning

The installation is the usual one line, and then there is a warning that is the kind of thing a library should print in bold.

npm install ng-diagram

The warning is that the required styles must be imported for the diagram to display correctly, and the reason is given: because the library uses variables, the stylesheet has to be imported in the global file, for example the main stylesheet of the application, and not inside a component.

That is a real trap, and the reason is worth understanding rather than memorising. A stylesheet imported into a component is scoped to that component, and the library's variables are the mechanism by which the theme works, so a component-scoped import means the variables are defined in a scope the diagram's own elements may not see. Global import, global scope, variables available everywhere.

/* src/styles.scss */
@import 'ng-diagram/styles.css';

And then the first diagram, which is the part worth reading in detail, because it shows the shape of the model.

import { Component } from '@angular/core';
import { NgDiagramComponent, initializeModel, provideNgDiagram } from 'ng-diagram';

@Component({
  imports: [NgDiagramComponent],
  providers: [provideNgDiagram()],
  template: ` <ng-diagram [model]="model" /> `,
  styles: `
    :host {
      display: flex;
      height: 300px;
    }
  `,
})
export class MyDiagramComponent {
  model = initializeModel({
    nodes: [
      { id: '1', position: { x: 100, y: 150 }, data: { label: 'Node 1' } },
      { id: '2', position: { x: 400, y: 150 }, data: { label: 'Node 2' } },
    ],

Three things in that are Angular conventions rather than library conventions, and that is the point. The component is standalone, so it imports the diagram component directly instead of declaring it. The library's provider is added to the component's own providers array, so the configuration is scoped to the component rather than to the application root. And the model is a plain field on the component, initialised by a function, and bound to the component with a property binding on a custom element.

So a diagram is a component with a model. There is no imperative API to call, no chart to configure, and no lifecycle to manage. The model is a value, and the value is bound.

And the model itself is plain data: nodes with an identifier, a position, and a data payload holding a label. The edges follow the same shape, with identifiers for the source and target and names for the ports they attach to. Nothing in that is library specific, and that is what makes it possible to build an editor around it.

Middleware, performance, and the AI-facing piece

Two features in the list are about the library's internals, and one is about something else entirely.

The performance entry lists three things: signal-based reactivity, spatial hashing, and viewport virtualisation for large diagrams. Each of those answers a specific failure mode. Reactivity through signals means a change to one node does not re-render the whole canvas. Spatial hashing means a hit test does not walk every node, which is what makes a large diagram feel immediate. And virtualisation means the nodes outside the viewport are not drawn at all, which is the difference between a diagram with a thousand nodes and one with a hundred thousand.

The extensible architecture entry is the middleware pipeline for custom behaviours and business logic. The idea is the same as middleware in a server framework: a request passes through a chain of handlers, and a library user can insert a handler that validates, logs, or transforms without modifying the library.

For an editor, that is where a surprising amount of application logic lives. A rule that a node cannot be deleted while it has children, or a rule that connecting two particular node types is not allowed, is domain logic, and putting it in a middleware keeps it out of the library and out of the components.

The last entry is the unusual one: an official server for the model context protocol, published as its own package, which lets an assistant search the documentation and the API from the editor. The package is a way of making the library's documentation queryable by a coding assistant rather than something to be pasted into a prompt.

And the repository layout backs the point up. There is a directory of skills at the top level, a configuration file for the protocol server, a directory of decision records, a directory of tools, an applications directory, a packages directory, and a workspace configuration. The decision log is the one to note: for a library that has been through three releases of edge handling and gesture fixes, a written record of why the design went the way it did is worth more than a changelog.

The rest of the tooling is a modern monorepo setup, with a task runner fanning commands out across the workspace, parallel type checking and parallel tests, coverage reporting, and separate commands for the end to end tests including an interactive mode and an install step for the test browsers. The end to end suite has its own package, and the commands filter down to it by name.

Editorial conclusion

ng-diagram fits an Angular team building a visual editor and who want the nodes to be their own components rather than a configuration object, and a team that has decided to make diagrams a first class part of their product. It does not fit a team that wants a diagram in a page, because the whole library is an editor. Verify first which of the five template applications resembles the domain you are in, since they differ enormously in how specialised they are, that you import the stylesheet globally rather than in a component, because the library uses variables and a component-scoped import will not reach them, and that the version of the library you take matches your Angular version, since the library is written against a specific framework generation.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. synergycodes/ng-diagram on GitHub