DEV Community: Wojciech Krzesaj

React Flow alternative for Angular: meet ngDiagram

Wojciech Krzesaj — Wed, 05 Aug 2026 12:05:10 +0000

React Flow has grown into the default for node-based UIs in React since its 2019 origins. Its maker, xyflow, also ships a Svelte version, Svelte Flow, but no Angular one. If you work in Angular and reach for React Flow, that gap is the wall you hit. Angular has a signals-native answer: ngDiagram, a React Flow alternative built for Angular.

Disclosure: I work at Synergy Codes, the team behind ngDiagram. I've built with both ngDiagram and React Flow, so this comparison comes from using each.

In short

React Flow is React-only. Using it inside Angular means bridging 2 runtimes. ngDiagram is a native Angular diagram library built on signals, dependency injection, and OnPush: one runtime, no bridge. The library is open source under Apache 2.0, first published to npm in August 2025, out of beta that November, with a stable 1.0 in February 2026.

Why not just wrap React Flow?

Angular teams building workflow builders, org charts, pipeline editors, or data-flow canvases need a library to build the canvas on. Framework-agnostic options like GoJS and JointJS mean driving the diagram imperatively from outside Angular. GoJS is commercially licensed, while JointJS keeps its advanced tooling in the paid JointJS+ tier. React Flow is the most popular node-based UI library in React, so it keeps coming up.

React Flow's limit in Angular is that it ships no Angular build. Its only way into an Angular app is a React island: an isolated React root inside your page, shipping react, react-dom, and React Flow alongside Angular, reached through a hand-built bridge or a third-party wrapper.

The framework boundary, drawn out: ngDiagram sits inside Angular, while React Flow lives in a separate React box you bridge to.

Wrapping works, and the diagram itself is fine. The cost sits at the boundary, in 3 places:

A second runtime. Rendering React Flow means shipping react and react-dom, code an Angular app would never load otherwise.
State stuck on the React side. React Flow keeps state inside React, where Angular's change detection can't see it. Every selection, drag, and connection you need in Angular you carry across by hand (more still on Zone.js, with runOutsideAngular() and ngZone.run()).
Maturity that stays on the React side. React Flow is proven in React apps. The bridge that holds it inside Angular is yours to write and keep working.

All three are the same problem: React Flow is not Angular. Remove the boundary and the costs go with it.

React Flow's mental model, native in Angular

If you know React Flow, ngDiagram will feel familiar. The mental model carries over: nodes, edges, a map of custom node types, and connection points on each node. ngDiagram needs Angular 18+, and its only runtime dependency is tslib. The foundation is pure Angular and a single runtime.

The difference is what those pieces are in Angular: a custom node is an ordinary Angular component that renders through Angular directly, with nothing to sync. The model is a swappable ModelAdapter, so your own store can be the single source of truth.

The same diagram, both ways

Before any custom code, here is the smallest thing each library does: a diagram with 2 nodes and an edge. A direct comparison of the minimal setups shows where the runtime difference lives.

React Flow uses hooks and (typically) controlled state:

// React Flow
import { useState, useCallback } from "react";
import {
  ReactFlow,
  applyNodeChanges,
  applyEdgeChanges,
  addEdge,
  Position,
  type Node,
  type Edge,
  type OnNodesChange,
  type OnEdgesChange,
  type OnConnect,
} from "@xyflow/react";
import "@xyflow/react/dist/style.css";

const initialNodes: Node[] = [
  {
    id: "1",
    position: { x: 100, y: 150 },
    data: { label: "Node 1" },
    // side handles, so the edge runs horizontally
    sourcePosition: Position.Right,
    targetPosition: Position.Left,
  },
  {
    id: "2",
    position: { x: 400, y: 150 },
    data: { label: "Node 2" },
    sourcePosition: Position.Right,
    targetPosition: Position.Left,
  },
];
const initialEdges: Edge[] = [{ id: "e1", source: "1", target: "2" }];

export default function DiagramComponent() {
  const [nodes, setNodes] = useState<Node[]>(initialNodes);
  const [edges, setEdges] = useState<Edge[]>(initialEdges);
  const onNodesChange: OnNodesChange = useCallback(
    (changes) => setNodes((nds) => applyNodeChanges(changes, nds)),
    [],
  );
  const onEdgesChange: OnEdgesChange = useCallback(
    (changes) => setEdges((eds) => applyEdgeChanges(changes, eds)),
    [],
  );
  const onConnect: OnConnect = useCallback(
    (params) => setEdges((eds) => addEdge(params, eds)),
    [],
  );

  return (
    <div style={{ width: "100%", height: 300 }}>
      <ReactFlow
        nodes={nodes}
        edges={edges}
        onNodesChange={onNodesChange}
        onEdgesChange={onEdgesChange}
        onConnect={onConnect}
      />
    </div>
  );
}

ngDiagram is a standalone component and a provider. State is a model you initialize:

// ngDiagram
// styles.scss: @import "ng-diagram/styles.css";
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 DiagramComponent {
  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" } },
    ],
    edges: [
      {
        id: "e1",
        source: "1",
        // port ids shipped by the default node template
        sourcePort: "port-right",
        target: "2",
        targetPort: "port-left",
        data: {},
      },
    ],
  });
}

The two setups look almost the same: declare your nodes and edges, then hand them to a component. The difference shows up in Angular, where the ngDiagram version runs as written and the React Flow version needs a bridge first. You wrap the React root in a Web Component and push state in through a setter per prop. Events wire back out by hand, and you own the teardown.

The whole example is 2 nodes and an edge. Custom nodes are the next step.

A custom node, both ways

The setup is the same in both libraries: build a component, map it to a type name, then bind the map to the canvas. Each does it the way native to its own framework.

In React Flow, the node's props are typed as NodeProps, and its connection points are <Handle> elements:

// React Flow
import { Handle, Position, type Node, type NodeProps } from "@xyflow/react";

export function CustomNode({ data }: NodeProps<Node<{ label: string }>>) {
  return (
    <div className="custom-node">
      <Handle type="target" position={Position.Left} />
      <span>{data.label}</span>
      <Handle type="source" position={Position.Right} />
    </div>
  );
}

You register the component in a nodeTypes map, then pass that map to the canvas. A node renders with it when its type matches the registered key:

function DiagramComponent() {
  const nodeTypes = useMemo(() => ({ customNode: CustomNode }), []);

  return <ReactFlow nodeTypes={nodeTypes} nodes={nodes} edges={edges} />;
}

In ngDiagram, the node arrives as a typed input, and its connection points are <ng-diagram-port> elements:

// ngDiagram
import { Component, input } from "@angular/core";
import {
  NgDiagramPortComponent,
  type NgDiagramNodeTemplate,
  type Node,
} from "ng-diagram";

@Component({
  imports: [NgDiagramPortComponent],
  template: `
    <div class="custom-node">{{ node().data.label }}</div>
    <ng-diagram-port id="port-left" type="target" side="left" />
    <ng-diagram-port id="port-right" type="source" side="right" />
  `,
})
export class CustomNodeComponent implements NgDiagramNodeTemplate<{
  label: string;
}> {
  node = input.required<Node<{ label: string }>>();
}

You register the component in an NgDiagramNodeTemplateMap, then bind that map to the diagram. The node's type selects its template, just as nodeTypes does in React Flow:

@Component({
  template: `<ng-diagram
    [model]="model"
    [nodeTemplateMap]="nodeTemplateMap"
  />`,
})
export class DiagramComponent {
  nodeTemplateMap = new NgDiagramNodeTemplateMap([
    ["customNode", CustomNodeComponent],
  ]);
}

The node can reach the rest of your app through dependency injection. Inject a service and use it. The example uses an OrderService, the same service your forms and tables already call:

@Component({
  template: `<div class="custom-node">{{ status() }}</div>`,
})
export class CustomNodeComponent implements NgDiagramNodeTemplate<{
  orderId: string;
}> {
  private orders = inject(OrderService);
  node = input.required<Node<{ orderId: string }>>();

  status = computed(() => this.orders.statusOf(this.node().data.orderId));
}

Because status is a signal, the node updates when the order changes.

When I built an app with ngDiagram, the reuse showed up right away. Generic components I already shipped elsewhere in the product (forms, cards, status widgets) dropped into nodes and just worked.

How ngDiagram and React Flow handle extensibility

Sooner or later every diagram app needs a behavior its library doesn't ship. What happens then (extend, or fork) depends on the library's extensibility model. The two libraries take different routes.

React Flow extends through its React surface. The <ReactFlow> component exposes a wide prop surface (interaction flags, connection rules, styling), and in controlled mode the change callbacks (onNodesChange, onEdgesChange) and connection events (onConnect) let you intercept and reshape changes before you apply them. Beyond that, it is hooks and component composition.

ngDiagram has 3 layers. Most needs are already in the global config: snapping, zoom, grouping, linking, edge routing, keyboard shortcuts, and validation callbacks, all adjustable at runtime. Events like nodeDragEnded and selectionChanged cover reacting to what users do. And when config and events aren't enough, every model change runs through a middleware pipeline. This is how you extend ngDiagram without forking it: I've used the pipeline to add behavior the library doesn't ship by default, like connecting edges to other edges.

Locking a node to horizontal movement shows the pipeline in a few lines: intercept the moved nodes, keep the new X, and restore the Y they started at.

// Horizontal movement lock in ngDiagram
import type { Middleware } from "ng-diagram";

export const horizontalLock: Middleware<"horizontal-lock"> = {
  name: "horizontal-lock",
  execute: (context, next) => {
    const movedIds = context.helpers.getAffectedNodeIds(["position"]);
    if (!movedIds.length) {
      next();
      return;
    }
    const nodesToUpdate = movedIds.map((id) => ({
      id,
      position: {
        x: context.nodesMap.get(id)!.position.x,
        y: context.initialNodesMap.get(id)!.position.y,
      },
    }));
    next({ nodesToUpdate });
  },
};

You register it alongside the defaults and pass it to the diagram:

@Component({
  template: ` <ng-diagram [model]="model" [middlewares]="middlewares" /> `,
})
export class MyDiagramComponent {
  middlewares = createMiddlewares((defaults) => [...defaults, horizontalLock]);
  // ...
}

The library stays untouched and your behavior sits on top of it.

A dragged node moves only horizontally. The middleware above keeps its new X and restores the Y it started at.

In React Flow the same rule goes in the controlled-mode onNodesChange callback: reset each position change's Y to the node's start value, captured in onNodeDragStart and held in a ref. A per-node extent can pin movement too, but the callback is the general mechanism for arbitrary rules.

// Horizontal movement lock in React Flow
// startYOf: start positions captured in onNodeDragStart, kept in a ref
const onNodesChange = useCallback((changes: NodeChange[]) => {
  const locked = changes.map((change) =>
    change.type === "position" && change.position
      ? {
          ...change,
          position: { x: change.position.x, y: startYOf(change.id) },
        }
      : change,
  );
  setNodes((nds) => applyNodeChanges(locked, nds));
}, []);

Both work. The difference is where the rule lives. In React Flow it sits in the component that renders the flow. In ngDiagram it registers once and applies to every change, whatever triggered it.

The middleware guide covers the full pipeline: intercepting, transforming, or canceling any change.

ngDiagram vs React Flow, feature by feature

ngDiagram covers the same core as React Flow, with a feature set shaped by its creators' decade of client diagramming work: the capabilities that kept proving necessary in real projects. I used those features in my own project, and they covered what I needed. For an Angular team, the deciding factor is how natively each feature fits.

Feature	ngDiagram	React Flow
Custom nodes	Angular component (`NgDiagramNodeTemplate`), registered in a node-type map; full Angular inside: DI and services	React component (`NodeProps`), registered in a node-type map (`nodeTypes`)
Custom edges	Angular component (`NgDiagramEdgeTemplate`), registered in an edge-type map; SVG path via `NgDiagramBaseEdgeComponent`	React component, registered in an edge-type map (`edgeTypes`); SVG path via path helpers (`getBezierPath` etc.) + `<BaseEdge>`
Ports / handles	Named connection points via `<ng-diagram-port>`	Named connection points via `<Handle>`
Edge routing	Built-in orthogonal, bezier, polyline; custom via `NgDiagramService.registerRouting()`	Built-in bezier, straight, step, smoothstep, simplebezier; custom via path helpers + `<BaseEdge>`
Auto-layout	No built-in layout; documented ELK.js integration	No built-in layout; documented dagre, elkjs, d3-hierarchy integrations
State & store	Built-in signal model (`initializeModel`). Swap in a `ModelAdapter` to make your own store the single source of truth	Built-in Zustand store; controlled mode lets your store drive nodes/edges, but the internal store stays (not replaceable)
Extensibility	Config, callbacks, and events for most cases Middleware pipeline for any model change	Extend through React composition, hooks, change/event callbacks, and helper components (`Panel`, `NodeToolbar`, `ViewportPortal`)
Undo / redo	Not built in yet; `Ctrl/Cmd+Z` / `Ctrl/Cmd+Y` are reserved and on the public roadmap (needs a custom model today)	Not built in; you implement it yourself (a paid Pro example exists)
Transactions	`transaction()` batches many changes into one atomic model update: fewer renders, consistent state, and groundwork for undo/redo	No transaction API; batch changes yourself in a single state update
Performance	Opt-in viewport virtualization via `virtualization.enabled`, default off	Opt-in viewport virtualization via `onlyRenderVisibleElements`, default off
Grouping	Group nodes that contain child nodes via `groupId`	Group nodes that contain child nodes via `parentId`
Palette	Built-in palette components for drag-and-drop node creation, with live drag preview	No built-in palette; build one following the drag-and-drop example
Resize	Built-in resize handles via `<ng-diagram-node-resize-adornment>`	Built-in resize handles via `<NodeResizer>`
Rotation	Built-in rotation handle via `<ng-diagram-node-rotate-adornment>`	No built-in rotation; build one following the rotatable-node example
Minimap	Minimap `<ng-diagram-minimap>`: node overview, viewport indicator, pan/zoom navigation	Minimap `<MiniMap>`: node overview, viewport indicator, pan/zoom navigation
Theming	CSS variables; light and dark out of the box; Tailwind supported	CSS variables; light and dark via `colorMode` (default light); Tailwind supported
Touch / mobile	Supported: pinch-zoom, 2-finger pan, long-press select, tap/drag/resize/rotate, drag-connect, tap-to-connect via linking mode (`startLinking()`)	Supported: pinch-zoom, pan, tap-to-connect, drag-connect, auto-pan, connection radius
Accessibility	Not built in yet; full support is on the public roadmap. Keyboard shortcuts cover editing (copy/paste, move, zoom), not navigation. Nodes are real DOM, so you can add ARIA to node content today	Documented built-in a11y: focusable nodes/edges, keyboard move, ARIA labels
AI-assisted dev	Official `@ng-diagram/mcp` server puts the docs and API into your AI assistant	No official MCP server (a deliberate docs-first choice); publishes `llms.txt` docs endpoints for AI assistants instead
Bundle	One library; only runtime dependency is `tslib`; no extra framework in the bundle	The library plus the React runtime (`react` + `react-dom`) an Angular app would not otherwise ship

Current bundle sizes: bundlephobia for ng-diagram and @xyflow/react.

How mature is ngDiagram?

ngDiagram hit a stable v1.0 in February 2026 and is at v1.2 as of mid-2026. It is open source under Apache 2.0, tracks the latest 3 Angular versions, and is built by Synergy Codes.

Development has not slowed since: each release brings DX improvements and features the community asked for.

Beyond examples, the team ships maintained starter-kit templates that you clone and customize for your own use case, with more to come. They come from the same place as the feature set: what client work kept proving necessary.

Developers are already building the first projects using it, collected in the growing showcases.

The library has been well received: it has passed 500 GitHub stars, the community has started writing its own tutorials on Medium, and the official Angular account shared ngDiagram in February 2026.

The official Angular account sharing ngDiagram, February 2026 (source).

When to choose which, and how to start

The rule tracks your framework, with one exception:

Your stack	Recommendation	Why
Your app is React	React Flow	Mature, MIT-licensed, proven in production
A new Angular build	ngDiagram	No React layer to ship or bridge
Angular already running a React Flow island	Keep it. Treat as tech debt, plan a migration	The island works. The second runtime, bridge, and state sync stay as ongoing cost

For a fresh Angular build, I don't see a reason to start with React Flow. The framework boundary alone is enough to prefer a native option. Wrapping is usually chosen for React Flow's maturity. The question is whether the boundary cost is worth it in your app.

The exception is if you already run React Flow inside Angular. A rewrite tomorrow is rarely worth the risk. Keep it, and revisit when the bridge starts to bite: a major framework upgrade, nodes that need deeper access to your Angular app, or the next big diagram feature.

Sticking with what you know is reasonable, but in Angular, React Flow adds one more thing to maintain: the bridge between the 2 frameworks. A native library drops it. Try ngDiagram and see how it feels. Adding it takes one install, one provider, and a styles import. Start with the interactive examples.

Building a custom diagram editor, or taking an existing one further, is the kind of work Synergy Codes does.

Why your accessibility tools can't see your diagram

Wojciech Krzesaj — Wed, 20 May 2026 08:30:04 +0000

TL;DR:

Lighthouse scored my Org Chart 98%. A keyboard user could not reach a single node.
I audited from three angles: automated tools, manual pass, LLM review.
Fixes: landmarks, headings, focus styles, role="tree" + custom keyboard shortcuts, skip-link as documentation.
Tools score documents, not diagrams. They check what they can check.
The biggest takeaway: try the app with the keyboard before the first commit.

Accessibility is getting harder to ignore, and that is mostly a good thing. The same markup that helps a screen reader user also lets web crawlers and LLM agents work from structure instead of screenshots. The catch is that the apps where the standard tools and articles say the least - diagrams, dashboards, data-heavy interfaces - are the ones where teams will increasingly need answers. The complexity is real, but it is not an excuse.

I built an Org Chart with ngDiagram a while back, and I want accessibility to be part of how I build rather than something I bolt on later. To audit it I picked the tools I had not used before on a real app: Lighthouse, WAVE, an accessibility linter, and an LLM-based review. What follows is a walkthrough of that audit rather than a guide.

The org chart after the audit - a node has keyboard focus, with a visible focus ring.

The audit

The plan was to look at the app from three angles: automated tools, a manual pass, and an LLM review of the code itself.

What the automated tools said

Lighthouse went first. 98 out of 100, with one fix (a missing main landmark) and a manual checklist worth running through.

WAVE was more useful. Zero errors, but the warnings were the interesting part: node descriptions rendered below comfortable reading size and no heading structure on the page at all. The order tab was the only thing nagging me - something about the labels on the diagram's tab stops did not quite line up with what I expected, and that was enough to push me into trying the app manually.

WAVE's order tab numbering the focusable elements. The canvas is buried far down the sequence.

The ESLint accessibility rules (angular-eslint's templateAccessibility ruleset) came in later as a habit rather than an audit. They do not catch the big things - those live in interactions, not markup. But they raise a hand when a label is missing or an aria attribute is wrong, every time you save. Next step is wiring them into CI so a missing label is a build failure rather than a reminder I might ignore.

What clicking and tabbing told me

I set the mouse aside and opened the browser's developer tools. The accessibility panel has an option to show the page as a full accessibility tree - a nice discovery on its own. The zoom level was rendered as a bare number, which a screen reader would read as "100" with no idea what it was 100 of. The minimap was technically hidden when collapsed, but the underlying image was still in the tree.

The accessibility tree as a screen reader sees it: "57" with no context.

The keyboard pass was where the audit stopped feeling routine. Tabbing worked fine until I reached the diagram, and at first I thought it worked there too. What I was actually reaching were the expand/collapse buttons on each node. The nodes themselves had no focus, and the plus-buttons for adding new ones only appeared on mouse hover - which meant they did not exist for anyone not using one, and they did not exist for the audit tools either, because there is nothing in the DOM until the pointer event fires. Drag-and-drop reordering was the same story. Two of the most important things in the app were entirely mouse-only, and the previous tools had not flagged any of it. They were not wrong. They were checking what they can check, and they cannot check interactions that only exist while you hover.

What the LLM caught

For the third pass I used Claude with a custom skill based on the accessibility-review skill on MCPMarket. It agreed with the static tools on the obvious things. What it added was findings you can only get by reading the code: the specific input that auto-focused when the properties sidebar opened, the exact pointerdown handler that locked add-buttons to a mouse, and the missing keyboard entry on the diagram as a top finding rather than a footnote. Running it twice gave overlapping but not identical lists. Not every point was worth fixing, and saying no to a few of them ended up being part of the audit too.

Making the diagram keyboard-reachable

The first decision was what kind of thing the diagram actually is. An org chart is a tree, so the canvas got role="tree" and each node got role="treeitem". That changes how a screen reader narrates the structure: instead of "graphic, region" it reads as a hierarchical tree, which matches what the user is actually looking at. Picking the role is the application's job, not the library's - ngDiagram does not know whether you are rendering an org chart, a state machine, or a dependency graph, and each of those wants a different role.

The canvas gets the tree role:

<main aria-describedby="diagram-instructions" ...>
  <div role="tree" aria-label="Organization tree">
    <ng-diagram ... />
  </div>
</main>

Each node component declares itself a treeitem through its host bindings, alongside the aria state it needs to expose:

@Component({
  host: {
    '[attr.role]': '"treeitem"',
    '[attr.tabindex]': 'isFocusable() ? 0 : -1',
    '[attr.aria-selected]': 'node().selected',
    '[attr.aria-expanded]': 'ariaExpanded()',
    '[attr.aria-label]': 'ariaLabel()',
  },
})
export class NodeComponent { ... }

isFocusable() is a roving tabindex: only one node is in the tab order at a time, so Tab moves in and out of the canvas in one step rather than walking every node.

The interaction model:

Keys	Action
Shift + arrows	Move focus between nodes
Arrows (when focused)	Move the node on the canvas
Space	Expand / collapse children
Enter / Esc	Open / close properties panel
Alt + arrows	Add a new node next to the focused one (child or sibling depending on layout direction)
Delete	Remove the focused node

Keyboard navigation across the tree: focus moves with Shift+arrows, Space expands, Alt+arrow adds a new node.

Adding all of this raised a question I had not been thinking about: how does the user know any of it exists? Implementing keyboard support is one job. Making sure people can find out it is there is another - a shortcut nobody is told about is a secret.

The skip-link as documentation

The answer ended up sitting next to the skip-link. The skip-link itself jumps focus to the diagram; right after it, a short paragraph lists every shortcut. The diagram's <main> references that paragraph via aria-describedby, so the instructions get announced when focus enters the canvas. The paragraph stays visible on the page too - sighted keyboard users need to know the shortcuts as much as screen reader users do, and the audit tools cannot tell them.

The skip-link with the shortcut list immediately next to it - visible to sighted users, announced to screen readers.

The side effect was the thing I did not see coming. Once there was a place to tell the user about a shortcut, the answer to "the plus-buttons only show on hover" stopped being "show them on focus too" and became "a custom shortcut, written down right next to the skip-link." Having somewhere to document a shortcut is what made them worth building at all.

The smaller fixes

The static-tool findings mostly translated to small fixes:

The page got a <main> landmark and a visually-hidden <h1>.
Styled spans pretending to be headings became real heading tags.
Icon-only buttons (add, toggle, caret, sidebar, theme, zoom) picked up aria-labels; the toggle-expand button got aria-expanded.
"100" in the zoom widget became "Zoom level 100" - the kind of fix where a lot of accessibility work hides: rewriting a number to say what the number is of.
Blanket outline: none came out of the form styles; :focus-visible rings went in.
The minimap, which duplicates content the keyboard user already navigates on the main canvas, got aria-hidden="true" - along with the button that toggles it, since a control that opens a panel the user cannot perceive is no use to them either.

What I left alone (on purpose)

Drag-and-drop hierarchy changes are still mouse-only. A real gap; a keyboard equivalent (cut/paste-style reparenting) was bigger than this round could absorb.
No help dialog or shortcut overlay yet. The description next to the skip-link is enough to make the keyboard support discoverable for this pass.
The properties sidebar is deliberately non-modal. No focus trap, no focus return on close, because a user editing a node's properties should still be able to move around the diagram underneath. That one is a feature, not a deferred fix.

Where this leaves me

The audit changed the app. What I did not expect was that it would also change how I look at apps. If I had spent any real time using my own work with the keyboard only, before I started building it, I would have built it differently from day one. That is the thing I am taking forward: not a list of fixes, but the habit of trying the app the way the user will, before the first commit.

Tools like Lighthouse, WAVE, and the LLM pass are useful starting points. They tell you where to look. They cannot tell you whether the app is actually usable. That part still needs a person, a keyboard, and a willingness to be honest with yourself about what you find.

Diagrams and other visual tools have a lot going on - many features, many interactions, many edge cases - and making them work for every user is harder than making a form work for every user. Most of the existing material does not help with the difference. If you are curious about how those problems play out in practice (and where some of them are still unsolved), come talk to us.

Where to look next

Building Accessible Whiteboards and Diagrams - the GAAD 2026 webinar we are hosting
ngDiagram Org Chart - the app the audit was on
ngDiagram - the library the app is built on
angular-eslint - the ESLint plugin with the templateAccessibility ruleset
accessibility-review skill - the basis for the LLM audit skill I used

GAAD 2026 webinar - Thursday, 21 May, 14:00 CET
Anna Dulny-Leszczyńska and I are hosting Building Accessible Whiteboards and Diagrams: a free, 45-minute talk with real examples instead of theory.

Save your seat

I've Used GoJS for Years. Here's What Happened When I Built an Org Chart with ngDiagram

Wojciech Krzesaj — Tue, 14 Apr 2026 07:59:11 +0000

TL;DR: I've spent 5+ years building diagram-heavy apps with GoJS. Recently I built an org chart starter kit with ngDiagram - an Angular-native, open-source diagramming library. The big difference: nodes are just Angular components, styling is just CSS, and the MCP server makes AI assistance actually useful during development. The trade-off is real though - you build more yourself (layouts or expand/collapse), but you get full control and zero context-switching between "diagram code" and "Angular code." If you're an Angular dev evaluating diagramming options, this is an honest breakdown of both.

Disclaimer: I work at Synergy Codes, the company behind ngDiagram. This is my honest experience - including the rough edges.

Picking a diagramming library for your project is a bigger decision than it looks. It's not just "can it render nodes and edges" - it's how it fits into your stack, how it scales with your requirements, and how productive you are day to day while working with it. The right choice helps you develop and introduce new features faster.

I've Used GoJS for Five Years. Three Weeks with ngDiagram Changed My Perspective

I work as a Software Developer at Synergy Codes (the company behind ngDiagram), where I've been building diagram-heavy applications for over 5 years. Most of my experience is with GoJS, but I've worked with other diagramming libraries too. The projects spanned industries from automotive manufacturing and AI-powered tools to engineering platforms and enterprise analytics.

GoJS is powerful, no question. But it always felt like bolting a separate application onto your project. Recently, I built an org chart starter kit with ngDiagram, an Angular-native library that rethinks the whole approach. With all that background, I had a lot of context for what usually goes wrong and what usually works.

Here's what I found after about 3 weeks of building.

Bird's-eye view of the org chart starter kit built with ngDiagram

The Brief: What This Org Chart Had to Do

The goal: build an interactive org chart to showcase ngDiagram's capabilities. Not a static tree, but a fully interactive product.

It needed to:

Display employees in a hierarchy with editable properties.
Support drag & drop to restructure reporting lines.
Render in both horizontal and vertical tree layouts.
Show different node variants depending on zoom level - full details when zoomed in, compact view when zoomed out.
Switch nodes between occupied and vacant dynamically. Clear someone's name in the sidebar, and the node becomes a placeholder.

The sidebar form was wired to the diagram in real-time, including a dropdown that actually re-parented nodes in the graph. The whole tree supported expand/collapse of child nodes.

I've built similar projects in GoJS before. This time I was genuinely curious how the whole experience would turn out with ngDiagram.

Getting Started: Less to Learn Than I Expected

The first thing that struck me was how little I had to relearn. If you know Angular, you already know most of what you need to get started with ngDiagram. Node templates are just Angular components. Styling is just CSS. The diagram integrates into your project like any other piece of your UI.

That's a real contrast to GoJS, where the diagram code tends to live in its own world. You build UI using GraphObject.make calls, nesting panels inside panels to construct your nodes. It's a completely different way of building UI than what you're used to in Angular. You have to switch into that mindset every time you touch the diagram. With ngDiagram, I was moving between diagram components and the rest of the app without any context switching. It's all just Angular.

Within the first few hours, I had a basic diagram rendering with custom, complex nodes. I couldn't say the same about my first encounter with GoJS years ago.

The MCP Advantage: AI That Actually Understands the Library

Here's something I didn't expect to write about in a diagramming library review: AI made a huge difference.

ngDiagram ships with an MCP server, which means AI assistants understand the library's API and patterns. I used AI throughout the entire project. I was designing architecture, making technical decisions, and guiding the AI on how things should work. What I didn't do was dive deep into ngDiagram-specific API details - I relied on the AI's knowledge of the library for that, and the results were solid.

I'd describe the behavior I wanted, explain the technical approach, sometimes show mockups - and get working code back in a few iterations. Node templates in particular were written almost entirely by AI. I reviewed them, fixed minor bugs, and moved on.

This works so well because ngDiagram's building blocks are standard Angular. The AI isn't wrestling with some custom API - it's generating components and CSS. Things it already excels at.

Building the Org Chart with ngDiagram

The org chart touched several areas of ngDiagram's API - from node templates and layout integration to drag & drop, expand/collapse, and edge connections. Here's how each one played out - and where it felt different from what I was used to in GoJS.

Node Templates: Three States, One Component

The org chart needed three visual states for each node. A full view of all employee details. A compact view at lower zoom levels. A vacant state for unassigned positions. Some elements were independent of the visual state - the expand/collapse button shows when a node has children, and the add-node buttons appear on hover. Their logic lives outside the variant switching entirely.

Full, compact, and vacant - the three visual states of an org chart node built with ngDiagram

In ngDiagram, this was one Angular component with a @switch:

@switch (variant()) {
  @case ('vacant') {
    <app-vacant-node [role]="node().data.role" />
  }
  @case ('compact') {
    @let data = occupiedData();
    <app-compact-node
      [fullName]="data?.fullName"
      [role]="data?.role"
      [color]="color()"
    />
  }
  @case ('full') {
    @let data = occupiedData();
    <app-full-node
      [fullName]="data?.fullName"
      [role]="data?.role"
      [color]="color()"
      [reports]="data?.reports"
      [span]="data?.span"
      [shiftCapacity]="data?.shiftCapacity"
    />
  }
}

The zoom level comes from a diagram service as a signal. One computed() drives the whole switch:

variant = computed<NodeVariant>(() => {
  if (isVacantNode(this.node())) return 'vacant';
  return this.viewportService.scale() < 1 ? 'compact' : 'full';
});

The shared elements - expand/collapse, add buttons - just live outside the @switch. Their own conditions determine when they show, completely independent of which variant is active.

Nodes can also switch between occupied and vacant dynamically. Clear an employee's name in the sidebar form and the node converts to vacant live. Same node, different identity - no re-creation needed.

In GoJS, you'd typically handle this with category switching. That means managing separate templates for each visual state - the behavior spreads across multiple definitions instead of being visible in one place. Or you could use visibility bindings on nested panels, which gets cumbersome when you have many dependent elements. Those shared elements? You can reuse them, but you still have to include them in every template.

Layout: Plugging In ELK.js

For the tree layout, I used ELK.js with its mrtree algorithm. The integration was straightforward - compute positions with ELK, assign them back to ngDiagram nodes. Both horizontal and vertical orientations worked. Coordinating ngDiagram transactions with ELK's async layout took some effort - but it was a solvable problem.

Switching between horizontal and vertical tree layouts - powered by ELK.js mrtree algorithm

Drag & Drop: Custom Implementation, Solid Building Blocks

Drag & drop was more interesting. Beyond simple repositioning, I needed drops near existing nodes to trigger hierarchy changes - reassigning an employee's reporting line. This required a fully custom implementation, but ngDiagram provided useful building blocks - API methods and events - that helped put it together. The building blocks were there - I just had to put them together.

Restructuring the hierarchy with drag & drop - a node moved to a new position

Expand / Collapse: Not Built In - But Not Hard Either

Expand/collapse was where the difference in library maturity showed most clearly. In GoJS, tree expand/collapse is built in - you get it essentially for free. In ngDiagram, you manage node visibility yourself by setting isHidden on individual nodes, which means writing your own tree traversal logic to hide or show entire subtrees. It's not hard, but it's work that GoJS handles out of the box.

Expanding and collapsing child nodes in the ngDiagram org chart

Ports: Explicit by Design

In GoJS, any object on a node can be a port. In ngDiagram, ports are explicit components - you place <ng-diagram-port> elements in your template and configure their position and type. In this project, I used two: top for incoming edges, bottom for outgoing.

It's a more structured approach. Different from what I knew, but it made the connection points very clear in the template.

Theming: Light, Dark, and Zero Extra Wiring

I used CSS custom properties as design tokens throughout the entire application - colors, spacing, borders, shadows, everything. One token file with definitions for light and dark themes. A toggle switches data-theme on the document root, and the whole app - diagram nodes, sidebar, buttons, backgrounds - updates instantly.

Because ngDiagram nodes are just Angular components with regular CSS, they pick up the tokens automatically. No special integration, no theme service wiring into the diagram. The same tokens that style a sidebar button also style a node's header. Once the token system was in place, adding the dark theme was trivial - just a new set of values.

Switching between light and dark mode in the ngDiagram org chart

GoJS vs. ngDiagram: An Honest Comparison

After three weeks of building with ngDiagram and years of building with GoJS, here's where I think each one stands.

Where GoJS Excels

Feature Set and Maturity

GoJS has years of development behind it. The feature set is massive - built-in tools for most common diagramming needs and countless edge cases already handled. Documentation is extensive, and there's an answer to almost every question. If you need a complex, battle-tested solution for a large enterprise project, GoJS delivers.

Considerations

That said, GoJS can feel like an oversized tool for some projects. You carry a lot of weight you may never use. If you're new to the library, the learning curve is steep - it takes time before you can use it to its full potential. Licensing is worth mentioning too: GoJS requires a paid commercial license. It's justified for large projects, but it's a real consideration.

Where ngDiagram Excels

Feature Set and Core

ngDiagram gives you a solid foundation - node and edge rendering with full Angular templates, edge drawing between ports, selection, a minimap with zoom controls, viewport management, and a signals-based reactive model wrapped in transactions. That's the core, and it works well out of the box.

Developer Experience

On the developer experience side, ngDiagram has a lot going for it. If you're an Angular developer, the onboarding is remarkably smooth. You're writing components, using HTML, working with signals or connecting to your state management.

The styling story is strong too - achieving polished visual results feels natural with CSS. Theming is a perfect example: I built a full light/dark theme using CSS design tokens, and the same tokens style both the diagram nodes and the rest of the app. One toggle, everything updates. In GoJS, theming was recently introduced, but it uses a separate object-based system rather than CSS - which makes it harder to keep the diagram visually consistent with the rest of your Angular application.

AI assistance via the MCP server also deserves special mention - it works exceptionally well, and the MCP integration makes AI genuinely useful throughout development.

Extensibility and Integration

ngDiagram is also genuinely extensible. The API provides building blocks - methods, events, services - that let you build custom functionality on top without fighting the library. It's not just for small projects. It handles large numbers of nodes with strong performance and can power complex applications even without the years of maturity that GoJS has.

There's also the integration story. In GoJS projects, the diagram always felt like a separate part of the application. The way you use it is so different from the rest of your code that it's natural to think of it as its own thing. ngDiagram dissolves that boundary. It's Angular all the way down. And it's open source.

The Trade-off: What ngDiagram Asks of You

ngDiagram's philosophy isn't to ship every feature built in. It gives you building blocks and a clean API to extend them. The tree layout, for example, isn't part of ngDiagram itself - you bring your own layout engine. I used ELK.js with the mrtree algorithm, and ngDiagram provides a documented example of this integration, so I wasn't starting from scratch.

Things you build on top of what the library gives you:

Expand/collapse (you manage node visibility via isHidden)
Zoom-responsive node variants
Hierarchy validation
Re-parenting logic

That approach means more upfront work compared to something like GoJS, where tree layouts and expand/collapse come ready-made. But it also means you're never fighting someone else's assumptions about how your feature should work. The custom drag & drop with drop indicators, the anti-cycle validation, the way nodes switch between occupied and vacant - all of these fit naturally because I built them with standard Angular patterns on top of ngDiagram's API, not around a pre-built behavior.

There were a couple of rough edges along the way

Expand/collapse positioning: When expanding a collapsed subtree, the child nodes would reappear at their last known positions - scattered across the canvas - instead of emerging from the parent. The fix was to set all children's positions to the parent's coordinates before triggering the re-layout. That way they animate out from where you'd expect. A small thing, but the kind of detail that matters for a polished result.

Watermark positioning: I also ran into a watermark positioning issue where the default placement overlapped with my sidebar UI. The workaround was a ::ng-deep override - not ideal, but functional. The ngDiagram team already has an open GitHub issue for a proper positioning API, so this one is temporary.

None of these were blockers. The API always gave me enough to solve the problem. But if you're coming from a batteries-included library like GoJS, it's worth knowing that ngDiagram asks you to bring more of your own implementation - and in return, you get full control over how everything works.

As for delivery speed - it's hard to compare directly. I had more GoJS experience, but less practice using AI with it. With ngDiagram, it was the opposite: less library knowledge, but excellent AI support. It roughly evened out.

The Verdict

Working with ngDiagram felt natural. The AI support through MCP was outstanding, and the fact that I could lean on Angular patterns I already knew made the whole experience smooth. After a while, things clicked and I could move fast. By the end of the project, ngDiagram had earned a permanent spot in my toolbox.

If you're building in Angular, ngDiagram is a natural fit. The onboarding is fast. The MCP server makes AI assistance genuinely useful. The extensible APIs let you build what you need. CSS-based styling lets you achieve polished results naturally. It's a strong fit when you want full control over your diagramming features, and you're comfortable building on top of a solid core.

GoJS is a strong fit for different reasons. If your project needs a wide range of built-in interactions, layout algorithms, and tools ready to go from day one - or if you're working across multiple frameworks - GoJS delivers that. The documentation is deep, the community is established, and for large enterprise projects with complex requirements, that maturity is genuinely valuable.

The question is whether you'd rather build on a flexible core with Angular-native DX, or start with a comprehensive toolkit and adapt it to your stack.

ngDiagram's architecture is solid, and the library is still growing. The potential is there.

Try It Yourself

Documentation: https://www.ngdiagram.dev/docs
GitHub: https://github.com/synergycodes/ng-diagram
NPM: https://www.npmjs.com/package/ng-diagram
Website: https://www.ngdiagram.dev