DEV Community: ngDiagram

How to build a BPMN editor in Angular with ngDiagram

Jacek Dębek — Fri, 10 Jul 2026 13:18:11 +0000

In short:

This tutorial builds a BPMN editor on ngDiagram. The editor gets a palette of shapes you drag onto the canvas, swimlanes, 3 typed connection styles, and per-lane auto-layout – about 1,700 lines of application code in total. The complete project is on GitHub.

What we will build

The editor breaks down into 9 features, and each one maps to one ngDiagram API:

A working canvas – provideNgDiagram(), initializeModel(), a sized <ng-diagram> host
A typed model – your BPMN subset as type strings and Node<T> / Edge<T> data
Node shapes – one component per shape family (events, tasks, gateways) plus one for the lane, registered in a template map
Edges and arrowheads – ng-diagram-base-edge plus SVG markers
A drag-and-drop palette – plain data objects inside <ng-diagram-palette-item>
Swimlanes – group nodes (isGroup), membership rules, NgDiagramGroupsService
Editor rules – one typed config: connection checks, edge creation, resize limits, routing
Auto-layout – bring your own engine (elkjs)
Theming – --ngd-* CSS variables

Each step below adds one feature and introduces the API behind it. The code samples come from the finished project – clone the repo and follow along. The article walks through the code that matters for ngDiagram; the repo holds the rest (styles, the toolbar and palette UI, helper internals). BPMN is only the example: the same building blocks make org charts, data pipelines, or network diagrams.

Why not bpmn-js?

bpmn-js is the right choice when you need standard BPMN 2.0 XML import and export – it is the fastest way to get that. It comes with 2 costs. Its license requires a visible watermark on every diagram, with no public paid option to remove it. And it has no official Angular wrapper, so you maintain the bridge between its event bus and Angular yourself.

This tutorial uses a different approach: a general diagramming canvas plus your own small BPMN model. Real diagrams use a small part of the notation, so you will define your own subset either way. ngDiagram is Angular-native – nodes are components, state is signals, theming is CSS variables – so every step below stays inside normal Angular patterns.

Full disclosure: I build diagramming tools at Synergy Codes, the company behind ngDiagram. Judge the code below for yourself. GoJS and JointJS are alternative diagramming libraries you could build a BPMN editor on – a comparison of all 4 options is at the end of the article.

Step 1 – set up the canvas

Start by installing the library: npm i ng-diagram. The library supports Angular 18 or newer; the project in this tutorial uses Angular 19. A canvas then needs 3 things: the provider, the engine stylesheet, and a host element with a real size. If the diagram renders blank, one of these 3 is missing.

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

ng-diagram { width: 100%; height: 100%; display: block; }

provideNgDiagram() goes on the component that wraps the whole editor – toolbar, palette, and canvas. Do not put it at the application root: the services attach to the diagram's DOM subtree, so they must live inside it. This scoping also keeps 2 diagrams on one page independent, if you ever need it.

// src/app/bpmn/pages/editor-page.component.ts (imports omitted)
@Component({
  selector: 'app-editor-page',
  standalone: true,
  imports: [ToolbarComponent, PaletteComponent, DiagramComponent],
  changeDetection: ChangeDetectionStrategy.OnPush,
  // ElkLayoutService and SwimlaneService are app services for steps 6 and 8.
  providers: [provideNgDiagram(), ElkLayoutService, SwimlaneService],
  templateUrl: './editor-page.component.html', // toolbar + palette + diagram
  styleUrl: './editor-page.component.scss',
})
export class EditorPageComponent {}

Inside the wrapper lives the diagram component – the owner of the <ng-diagram> canvas. In step 1 the class only creates the model; initializeModel needs an injection context, and a field initializer is one:

// src/app/bpmn/diagram/diagram.component.ts (imports omitted)
@Component({
  selector: 'app-bpmn-diagram',
  standalone: true,
  imports: [NgDiagramComponent, NgDiagramBackgroundComponent, NgDiagramMarkerComponent],
  changeDetection: ChangeDetectionStrategy.OnPush,
  templateUrl: './diagram.component.html',
  styleUrl: './diagram.component.scss',
})
export class DiagramComponent {
  protected readonly model$ = initializeModel(seedModel()); // seed nodes and edges

  // Added by the later steps: the template maps (steps 3–4), the config
  // (step 7), and the drop/resize handlers (step 6).
}

Its template binds everything to <ng-diagram>:

<!-- src/app/bpmn/diagram/diagram.component.html -->
<ng-diagram
  [model]="model$"
  [config]="config"
  [nodeTemplateMap]="nodeTemplateMap"
  [edgeTemplateMap]="edgeTemplateMap"
  (paletteItemDropped)="onPaletteItemDropped($event)"
  (nodeResized)="onNodeResized($event)"
>
  <ng-diagram-background type="dots" />
</ng-diagram>

This template is the finished shape – the config, the template maps, and the event handlers come from steps 3–7. The minimal working canvas is just <ng-diagram [model]="model$" /> with the dotted background child.

In the app: after npm start, the seeded diagram renders – pan and zoom already work.

Step 2 – describe BPMN as data

In ngDiagram, a diagram is data: an element on the canvas is a plain object with a type string and a data object. The whole "which BPMN" decision lives in a single model file, and it defines exactly those 2 things for every element: its type strings and its data shapes.

BPMN 2.0 defines well over 100 graphical elements, but you do not need them all. According to zur Muehlen and Recker's study of 120 real-world BPMN diagrams, the average model uses about 9 distinct constructs. So this editor models 9 shapes: events, tasks, gateways, and the swimlane ("lane" from here on).

First, the type strings. A type selects which Angular component renders the element – in step 3 a template map does the matching. Every object in the model carries one: a seed node looks like { id: 'start', type: BpmnNodeType.StartEvent, position: …, data: { label: 'Start' } }.

// src/app/bpmn/model/bpmn.model.ts
export const BpmnNodeType = {
  Task: 'bpmn-task',
  ExclusiveGateway: 'bpmn-exclusive-gateway',
  Swimlane: 'bpmn-swimlane',
  // ...9 type strings total – events, tasks, gateways, lane
} as const;

export const BPMN_EDGE_TYPE = 'bpmn-edge';

Second, the data shapes. Each element family declares an interface for its data object – the fields your app stores on the element:

// src/app/bpmn/model/bpmn.model.ts (continued)
export interface BpmnNodeData {
  label: string;
}

export interface SwimlaneData {
  label: string;
  /** Vertical stacking order (0 = topmost lane). */
  order: number;
}

export interface BpmnEdgeData {
  /** Line style. Defined as the BpmnEdgeKind const in the repo. */
  kind: 'sequence' | 'message' | 'association';
  /** Shown at the middle of the edge; editable in step 4. */
  label?: string;
  // (layout flags and index signatures trimmed – see the repo)
}

export type BpmnNode = Node<BpmnNodeData>;
export type SwimlaneNode = Node<SwimlaneData>;
export type BpmnEdge = Edge<BpmnEdgeData>;

The aliases at the end hand these interfaces to ngDiagram's generics. From here on, every API that touches a node – templates, updates, event payloads – sees Node<BpmnNodeData>, so a typo in a field name fails at compile time instead of rendering a broken node.

The edge kind comes back in step 4, where it picks the line style, and the lane order drives the vertical stacking in step 6.

Step 3 – nodes are Angular components

Every BPMN shape is a normal Angular component, and each of the 3 shape families – events, tasks, gateways – gets its own. This step builds the task template and registers it at the end.

The template structure

ngDiagram asks a node template for exactly 2 things: implement NgDiagramNodeTemplate<T> – which boils down to one required input named node – and render whatever markup you like. Inside that markup, 2 standard library pieces appear in every template: the ngDiagramNodeSelected directive on the wrapper (it adds the ng-diagram-node-selected class while the node is selected, so your CSS styles that state) and <ng-diagram-port> elements for connections. The task template's structure:

<!-- src/app/bpmn/diagram/templates/nodes/task-node/task-node.component.html (structure) -->
<div class="task-node" ngDiagramNodeSelected [node]="node()">

  <!-- your own markup: the rounded rectangle, the type icon, the label -->

  <ng-diagram-port id="top" type="both" side="top" />
  <ng-diagram-port id="right" type="both" side="right" />
  <ng-diagram-port id="bottom" type="both" side="bottom" />
  <ng-diagram-port id="left" type="both" side="left" />
</div>

A port's type takes source, target, or both and controls whether a connection may start or end there; edges reference ports by their id. Hovering anywhere over the node lights the ports up – that is the engine's ng-diagram-port-hoverable-over-node host class, set once in the base class below.

The editable label

Now the custom part – the markup in the middle. The label is editable inline: a double-click swaps the text for a native <input>, and 2 ngDiagram attributes make an input inside a node usable – data-no-drag and data-no-pan keep typing from dragging the node or panning the canvas. The editing state (editing(), commit, cancel) comes from a shared app directive, explained below the template. (.inline-editor carries the field's styling and <app-icon> renders from the app's SVG sprite – see the repo.)

<!-- task-node.component.html – the markup inside the wrapper -->
<div class="task" [class.task--typed]="type() !== T.Task">
  @switch (type()) {
    @case (T.UserTask) { <app-icon class="task__icon" name="person" /> }
    @case (T.ServiceTask) { <app-icon class="task__icon" name="gear" /> }
  }

  @if (editing()) {
    <input
      #editor
      class="inline-editor task__input"
      type="text"
      data-no-drag="true"
      data-no-pan="true"
      [value]="label()"
      (dblclick)="$event.stopPropagation()"
      (keydown.enter)="commit(editor.value)"
      (keydown.escape)="cancel()"
    />
  } @else {
    <span class="task__label" (dblclick)="startEdit($event)" title="Double-click to rename">
      {{ label() }}
    </span>
  }
</div>

The component and its base

The component class is only metadata – the logic sits in a shared base:

// src/app/bpmn/diagram/templates/nodes/task-node/task-node.component.ts (imports omitted)
@Component({
  selector: 'app-task-node',
  standalone: true,
  imports: [IconComponent, NgDiagramPortComponent, NgDiagramNodeSelectedDirective],
  changeDetection: ChangeDetectionStrategy.OnPush,
  templateUrl: './task-node.component.html',
  styleUrl: './task-node.component.scss',
})
export class TaskNodeComponent extends BpmnElementNode {}

BpmnElementNode is shared by all 3 element families. It implements the required node input, exposes the type and label computeds the template reads, and saves edited labels through updateNodeData on NgDiagramModelService – the injectable service that owns all model reads and writes.

// src/app/bpmn/diagram/templates/nodes/bpmn-element-node.ts (imports omitted)
@Directive({
  // Engine-provided hover styling: highlights all ports while over the node.
  host: { class: 'ng-diagram-port-hoverable-over-node' },
})
export abstract class BpmnElementNode
  extends InlineEditableLabel
  implements NgDiagramNodeTemplate<BpmnNodeData>
{
  private readonly model = inject(NgDiagramModelService);

  node = input.required<Node<BpmnNodeData>>();

  /** Templates only see class members – expose the type consts for @case. */
  protected readonly T = BpmnNodeType;
  protected readonly type = computed(() => this.node().type ?? '');
  protected readonly label = computed(() => this.node().data?.label ?? '');

  protected saveLabel(label: string): void {
    this.model.updateNodeData(this.node().id, { ...this.node().data, label });
  }
}

The editing state machine itself – enter on double-click, focus the field, save on Enter or a press outside, cancel on Escape – lives one level higher in InlineEditableLabel, a small app directive shared by all node and edge templates; a host plugs in by implementing saveLabel (see the repo).

EventNodeComponent and GatewayNodeComponent are the same kind of shell: their templates @switch on the node type to pick the glyph – a circle style per event type, a diamond with an x or + mark – with the editable label below it. Both are in the repo.

Registering the templates

With the components ready, register them. A template map matches each type string from step 2 to a component, and the shape families are arrays in the model file:

// src/app/bpmn/model/bpmn.model.ts – the shape families: events, tasks, gateways.
export const EVENT_TYPES: readonly BpmnNodeType[] = [
  BpmnNodeType.StartEvent,
  BpmnNodeType.EndEvent,
  BpmnNodeType.IntermediateEvent,
];
export const TASK_TYPES: readonly BpmnNodeType[] = [
  BpmnNodeType.Task,
  BpmnNodeType.UserTask,
  BpmnNodeType.ServiceTask,
];
export const GATEWAY_TYPES: readonly BpmnNodeType[] = [
  BpmnNodeType.ExclusiveGateway,
  BpmnNodeType.ParallelGateway,
];

// src/app/bpmn/diagram/diagram.component.ts
protected readonly nodeTemplateMap = new NgDiagramNodeTemplateMap([
  ...EVENT_TYPES.map((t) => [t, EventNodeComponent] as const),
  ...TASK_TYPES.map((t) => [t, TaskNodeComponent] as const),
  ...GATEWAY_TYPES.map((t) => [t, GatewayNodeComponent] as const),
  [BpmnNodeType.Swimlane, SwimlaneNodeComponent], // the lane – a group template, step 6
]);

In the app: double-click a task's label and rename it – Enter saves, Escape cancels.

Step 4 – edges: 3 line styles, 1 component

BPMN needs 3 connection styles – solid sequence flows, dashed message flows, dotted associations – and one edge component covers all of them.

The template structure

An edge template mirrors the node contract: implement NgDiagramEdgeTemplate<T> – one required input named edge – and render <ng-diagram-base-edge>, the library component that draws the routed path. Your template only configures it: the dasharray and the arrowhead ids come from computeds that read edge.data.kind (shown below).

<!-- src/app/bpmn/diagram/templates/edges/bpmn-edge.component.html -->
<ng-diagram-base-edge
  [edge]="edge()"
  [strokeDasharray]="dasharray()"
  [sourceArrowhead]="sourceArrow()"
  [targetArrowhead]="targetArrow()"
  [attr.title]="!label() && !editing() ? 'Double-click to add a label' : null"
  (dblclick)="startEdit($event)"
>
  @if (editing() || label()) {
    <ng-diagram-base-edge-label [id]="edge().id + '-label'" [positionOnEdge]="0.5">
      <!-- label text, or an input while editing – see the repo -->
    </ng-diagram-base-edge-label>
  }
</ng-diagram-base-edge>

The inline label

Labels sit in <ng-diagram-base-edge-label>, positioned along the path – 0.5 is the middle, which fits the "yes" / "no" labels on gateway exits. Double-click on the edge edits the label inline, the same pattern as node labels; an empty value removes it, and the title tooltip invites the user to add one.

The class is again mostly metadata plus a few computeds:

// src/app/bpmn/diagram/templates/edges/bpmn-edge.component.ts (imports omitted)
@Component({
  selector: 'app-bpmn-edge',
  standalone: true,
  imports: [NgDiagramBaseEdgeComponent, NgDiagramBaseEdgeLabelComponent],
  changeDetection: ChangeDetectionStrategy.OnPush,
  templateUrl: './bpmn-edge.component.html',
  styleUrl: './bpmn-edge.component.scss',
})
export class BpmnEdgeComponent
  extends InlineEditableLabel
  implements NgDiagramEdgeTemplate<BpmnEdgeData>
{
  edge = input.required<Edge<BpmnEdgeData>>();

  protected readonly label = computed(() => this.edge().data?.label ?? '');

  private readonly kind = computed<BpmnEdgeKind>(
    () => (this.edge().data?.kind ?? BpmnEdgeKind.Sequence) as BpmnEdgeKind,
  );

  protected readonly dasharray = computed(() => {
    switch (this.kind()) {
      case BpmnEdgeKind.Message:
        return '6 4';
      case BpmnEdgeKind.Association:
        return '1 4';
      default:
        return undefined;
    }
  });

  // sourceArrow / targetArrow pick the marker ids the same way,
  // and saveLabel stores the edited label – see the repo.
}

Selection styling

Selection needs no code at all. The base edge adds the .selected class to itself and reads the --edge-* CSS variables, so the selected stroke is 2 CSS rules:

/* src/app/bpmn/diagram/templates/edges/bpmn-edge.component.scss */
ng-diagram-base-edge {
  --edge-stroke-width: 1.6;
}
ng-diagram-base-edge.selected {
  --edge-stroke: var(--c-brand);
  --edge-stroke-width: 2.2;
}

/* (label chip styles – see the repo) */

Arrowheads

Arrowheads are plain SVG markers, defined once inside <ng-diagram-marker>, next to the <ng-diagram> element in the diagram component's template. One useful detail: fill="context-stroke" makes each marker inherit the color of its edge, so themed (and selected) edges get matching arrowheads for free.

<!-- src/app/bpmn/diagram/diagram.component.html -->
<ng-diagram-marker>
  <svg><defs>
    <marker id="bpmn-seq-arrow" viewBox="0 0 10 10" refX="9" refY="5"
      markerWidth="9" markerHeight="9" orient="auto-start-reverse">
      <path d="M0,0 L10,5 L0,10 z" fill="context-stroke" />
    </marker>
    <!-- message-flow open arrow + open circle: see the repo -->
  </defs></svg>
</ng-diagram-marker>

To put a marker on an edge, pass its id to the [sourceArrowhead] / [targetArrowhead] inputs from the template structure above. That is all the arrow computeds do – undefined means no arrowhead:

// src/app/bpmn/diagram/templates/edges/bpmn-edge.component.ts (fragment)
protected readonly targetArrow = computed(() => {
  switch (this.kind()) {
    case BpmnEdgeKind.Message:
      return 'bpmn-msg-end';
    case BpmnEdgeKind.Association:
      return undefined;
    default:
      return 'bpmn-seq-arrow';
  }
});

Registration and routing

The edge component registers in an NgDiagramEdgeTemplateMap, exactly like the node map in step 3 (see the repo). Orthogonal routing – the standard style for BPMN diagrams – is one line in step 7's config: edgeRouting: { defaultRouting: 'orthogonal' }.

In the app: double-click an edge to give it a label. Select the edge – the stroke and the arrowhead turn brand-colored.

Step 5 – a palette from plain data

A palette is a side panel with tiles that users drag onto the canvas to create new elements. ngDiagram's part is one wrapper component: put your own tile markup inside <ng-diagram-palette-item [item]="…"> and the engine makes the tile draggable. <ng-diagram-palette-item-preview> is the optional ghost shown while dragging:

<!-- src/app/bpmn/palette/palette.component.html -->
<ng-diagram-palette-item [item]="entry.item">
  <div class="tile" [title]="entry.label">
    <div class="tile__art">
      <app-icon [name]="entry.glyph" />
    </div>
    <div class="tile__label">{{ entry.label }}</div>
  </div>
  <ng-diagram-palette-item-preview>
    <div class="tile-preview">
      <app-icon [name]="entry.glyph" />
    </div>
  </ng-diagram-palette-item-preview>
</ng-diagram-palette-item>

The item input is a plain object describing the node the drop will create. This editor keeps all entries in a const array – adding a shape to the palette is one entry, no component work. The lane's item also prepares step 6, because a lane is a node with isGroup: true:

// src/app/bpmn/model/palette-data.ts – the `item` field of the lane's entry.
{
  type: BpmnNodeType.Swimlane,
  isGroup: true,
  resizable: true,
  rotatable: false,
  autoSize: false,
  size: { ...LANE_DEFAULT_SIZE },
  // `order` is assigned on drop (append to the bottom of the stack).
  data: { label: 'New Lane', order: -1 } as SwimlaneData as BasePaletteItemData,
}

autoSize: false with an explicit size appears on every element in this editor: BPMN shapes have fixed proportions, and fixed sizes are also what the swimlane math in step 6 relies on.

On drop, ngDiagram creates the real node and hands it to you in the (paletteItemDropped) event, together with dropPosition in diagram coordinates. Step 6 uses both.

In the app: drag a tile from the palette onto the canvas – a new node appears at the drop point.

Step 6 – swimlanes are groups

ngDiagram models containers as groups. A lane is a node with isGroup: true, members point to it through groupId, and the engine handles the rest: membership on drag, highlight when a node hovers over a lane, children moving with their lane.

Membership rules

One function in the config decides which nodes may join a lane:

// src/app/bpmn/diagram/diagram-config.ts
grouping: {
  // Only flow elements may be grouped, and only into a swimlane.
  canGroup: (node, group) => isSwimlane(group) && !isSwimlane(node),
},

The lane template

A group template follows the same contract as the node templates from step 3, with NgDiagramGroupNodeTemplate as the interface. The lane wraps itself in the engine's resize adornment – the selection frame with drag handles – and adds one more directive, ngDiagramGroupHighlighted:

<!-- src/app/bpmn/diagram/templates/nodes/swimlane-node/swimlane-node.component.html -->
<ng-diagram-node-resize-adornment>
  <div class="lane" ngDiagramNodeSelected ngDiagramGroupHighlighted [node]="node()">
    <div class="lane__header" [style.width.px]="headerWidth">
      <div class="lane__controls" data-no-drag="true" data-no-pan="true">
        <button type="button" class="lane__btn" title="Move lane up" (click)="moveUp($event)">
          <app-icon name="triangle-up" />
        </button>
        <button type="button" class="lane__btn" title="Move lane down" (click)="moveDown($event)">
          <app-icon name="triangle-down" />
        </button>
      </div>
      <!-- inline-editable title – see the repo -->
    </div>
    <div class="lane__body"></div>
  </div>
</ng-diagram-node-resize-adornment>

ngDiagramGroupHighlighted exposes the drop-zone state: while a node hovers over the lane, it adds .ng-diagram-group-highlight, and you style that class with your own CSS. The reorder buttons in the header sit behind data-no-drag, so clicking them never drags the lane.

Parenting on drop

For elements already on the diagram, this needs no code at all: dropping a node onto a group adds it to the group automatically. Only a drop from the palette needs extra handling – the engine creates the node, but into which lane it lands is your call. The handler checks which lane rectangle contains the drop point; paletteItemDropped fires after the node is committed to the model, so it can re-parent right away through NgDiagramGroupsService:

// src/app/bpmn/diagram/diagram.component.ts
onPaletteItemDropped(event: PaletteItemDroppedEvent): void {
  const node = event.node;
  if (isSwimlane(node)) {
    this.swimlanes.onLaneAdded(node.id); // stack + width-match the new lane
    return;
  }
  const lane = this.swimlanes.laneAtPoint(event.dropPosition);
  if (lane) this.groups.addToGroup(lane.id, [node.id]);
}

Lane geometry

The lane geometry lives in a dedicated SwimlaneService in the repo: it stacks lanes top to bottom, keeps all lanes the same width, and normalizes order after a reorder. Each operation is plain arithmetic over getChildren() (also on NgDiagramModelService) plus one batched updateNodes call.

Live resize

Resizing itself comes for free: the <ng-diagram-node-resize-adornment> wrapper from the lane template gives the lane its drag handles, and for a standalone node that is all you need. Lanes add extra behavior on top of it – width sync and stacking – and restyle the adornment.

The diagram template from step 1 binds the (nodeResized) event: it fires on every tick of a resize gesture, so while the user drags a lane, the other lanes follow live – widths stay equal, the stack stays flush (SwimlaneService.onLaneResized).

Lanes resize from the right and bottom edges only – the rest of the resize adornment is switched off with a small CSS override (a first-class option for this is planned in the adornment API):

/* src/app/bpmn/diagram/templates/nodes/swimlane-node/swimlane-node.component.scss */
:host ::ng-deep {
  .resize-line--top,
  .resize-line--left {
    pointer-events: none;
  }

  .resize-handle--top-left,
  .resize-handle--top-right,
  .resize-handle--bottom-left {
    display: none;
  }
}

The adornment's look itself is themable – the engine exposes --ngd-resize-* variables, and the app points them at its brand tokens:

/* src/styles.scss */
/* Engine bridge – point ngDiagram's themable tokens at the brand. */
:root {
  --ngd-resize-line-border-color: var(--c-brand);
  --ngd-resize-handle-background-color: var(--c-surface-2);
  --ngd-resize-handle-border-color: var(--c-brand);
  --ngd-resize-handle-border-radius: 2px;
}

In the app: drop a task from the palette into a lane – it becomes the lane's child. Then drag it over another lane – that lane highlights, and releasing moves the node into it.

Step 7 – editor rules live in the config

NgDiagramConfig is the engine's central settings object, passed once through the [config] binding from step 1. Its options are grouped by feature – linking, grouping, resize, edgeRouting, zoom, snapping, and more – and most of them are plain values or small callbacks the engine consults during gestures.

This editor uses 4 of those groups to enforce its BPMN rules: which elements may connect, what type a drawn edge gets, how small a lane may get, and how edges are routed.

// src/app/bpmn/diagram/diagram-config.ts
export function buildDiagramConfig(laneMinSize: (lane: Node) => Size): NgDiagramConfig {
  return {
    edgeRouting: {
      defaultRouting: 'orthogonal',
    },
    resize: {
      // Never let a lane (or any node) shrink smaller than the elements it holds.
      allowResizeBelowChildrenBounds: false,
      getMinNodeSize: (node: Node): Size =>
        isSwimlane(node) ? laneMinSize(node) : { width: 20, height: 20 },
    },
    grouping: {
      // Only real flow elements may be grouped, and only into a swimlane.
      canGroup: (node: Node, group: Node) => isSwimlane(group) && !isSwimlane(node),
    },
    linking: {
      // Swimlanes cannot be connection endpoints.
      validateConnection: (source: Node | null, _sourcePort: Port | null, target: Node | null) =>
        !!source && !!target && !isSwimlane(source) && !isSwimlane(target),
      // Every user-drawn connection becomes a typed sequence flow.
      finalEdgeDataBuilder: (edge: Edge) =>
        ({
          ...edge,
          type: BPMN_EDGE_TYPE,
          routing: 'orthogonal',
          data: { ...(edge.data ?? {}), kind: BpmnEdgeKind.Sequence },
        }) as Edge,
    },
  } satisfies NgDiagramConfig;
}

The diagram component builds this config once, handing it the lane minimum-size callback from SwimlaneService, and binds it to [config] from step 1:

// src/app/bpmn/diagram/diagram.component.ts
protected readonly config = buildDiagramConfig((lane) => this.swimlanes.laneMinSize(lane));

The key line is finalEdgeDataBuilder: every user-drawn connection becomes a typed sequence flow, so an untyped edge cannot exist. The model from step 2 is enforced at the gesture level.

laneMinSize computes the width floor from all lanes' content: lanes share the same width, so shrinking one lane must not push another lane's content out of bounds. Height is set per lane.

In the app: connect 2 tasks – the edge is created as a solid sequence flow with an arrowhead. Then try to shrink a lane below its content – the resize stops at the minimum size.

Step 8 – auto-layout with ELK, per lane

ngDiagram ships no built-in auto-layout – you bring your own engine. This project uses elkjs with the layered algorithm and RIGHT direction, because BPMN reads left to right.

The Layout button in the toolbar calls SwimlaneService.runLayout(). It lays out each lane's children with ELK – only the sequence flows inside that lane count, so cross-lane message flows never distort the arrangement – then a pure helper turns the results into lane frames and child positions: every lane gets the width of the widest content, and the lanes stack to fit. Everything lands in one batched updateNodes call, and the viewport stays where the user left it:

// src/app/bpmn/diagram/swimlanes/swimlane.service.ts
async runLayout(): Promise<void> {
  const lanes = this.lanes();
  if (lanes.length === 0) return;

  const layoutEdges = this.model.edges().filter((e) => isLayoutEdge(e as BpmnEdge));

  // Layout each lane's children independently (cross-lane edges ignored).
  const perLane = await Promise.all(
    lanes.map(async (lane) => {
      const children = this.childrenOf(lane.id).filter(isBpmnElement);
      const result = await this.elk.layoutLane(children, layoutEdges);
      return { lane, children, result };
    }),
  );

  this.model.updateNodes(computeAutoLayoutUpdates(perLane));
}

The details live next to it in the repo: swimlanes/lane-auto-layout.ts computes the updates, and layout/elk-layout.service.ts wraps the ELK call.

If you would rather show the whole diagram after a layout instead of leaving the viewport alone, wrap the write in a transaction that waits for re-measurement and call zoomToFit after it – it needs the new bounds, not the pre-layout ones:

// Example – NgDiagramService.transaction + NgDiagramViewportService.zoomToFit.
await this.ngDiagram.transaction(() => {
  this.model.updateNodes(computeAutoLayoutUpdates(perLane));
}, { waitForMeasurements: true });
this.viewport.zoomToFit({ padding: 60 });

In the app: scatter nodes across lanes and click Layout in the toolbar. Each lane arranges left to right, and all lanes share the same width.

Step 9 – theming with CSS tokens

The whole editor themes from one attribute: data-theme on <html>. Two sets of CSS variables react to it – the app's own design tokens and ngDiagram's --ngd-* tokens, which ship with a light and a dark theme built in. A small ThemeService writes the attribute and persists the choice; the toolbar button toggles it (see the repo).

The app tokens live in src/tokens.css. Components use semantic names, and each theme block points those names at different colors – flipping the attribute recolors every shape:

/* src/tokens.css (fragment) */
:root,
html[data-theme='light'] {
  --c-bpmn-node-fill: var(--prim-gray-100);
  --c-bpmn-node-stroke: var(--prim-gray-600);
}

html[data-theme='dark'] {
  --c-bpmn-node-fill: var(--prim-gray-700);
  --c-bpmn-node-stroke: var(--prim-gray-450);
}

The engine's canvas, selection ring, and default node colors theme themselves the same way. To restyle them, override the --ngd-* variables – this project keeps the engine defaults apart from the resize-adornment variables from step 6; an override looks like this:

/* Example – e.g. in src/styles.scss. Point engine tokens at your palette. */
html[data-theme='dark'] {
  --ngd-diagram-background-color: var(--c-canvas);
  --ngd-node-stroke-primary-hover: var(--c-brand);
}

In the app: flip the theme with the toolbar button. Canvas, lanes, shapes, and edges change together.

Summary

That is the whole editor – and look at what we did not have to build: drag and drop, coordinate math, model state, selection, resizing, grouping, edge routing. ngDiagram did the heavy, tedious work, so the editor's ~1,700 lines are almost entirely business logic: BPMN types, lane geometry, editor rules. And where a default did not fit, we overrode exactly the piece we needed – a config callback, a CSS variable, a template. The library is not a black box; it is built to be configured and changed.

The repo is a working starting template: swap the model file and the templates, and the same building blocks give you an org chart or a pipeline editor instead of BPMN.

If this saved you time, star ng-diagram on GitHub

When to pick a different library

Use bpmn-js when you need standard BPMN 2.0 XML interchange. Use GoJS or JointJS when diagrams grow very large – they render to canvas or plain SVG, which scales further than a component per node. For an embedded, branded editor inside an Angular product, ngDiagram is the direct fit.

	ngDiagram	bpmn-js	GoJS	JointJS
BPMN out of the box	No – you model it yourself	Yes – full BPMN 2.0 XML round-trip	No – samples, not a product	Shapes in the paid tier
Angular integration	Native – components, signals, typed outputs	No official wrapper – you own the bridge	Official thin wrapper (`gojs-angular`)	No official Angular wrapper
Nodes rendered as	Angular components in the DOM	SVG via custom renderers	Canvas scene-graph objects	SVG with its own model
Licensing	Apache 2.0; watermark off via config	Free, but license-mandated watermark	Commercial, per developer	Open core; advanced tier paid
Best when…	Branded editor in an Angular product	You need `.bpmn` XML files in and out	Large-scale diagrams	Large-scale diagrams

For scale, keep the numbers in view: real-world BPMN models run dozens to hundreds of elements, not tens of thousands. ngDiagram handles hundreds of nodes without tuning. For larger diagrams, it documents viewport virtualization: only elements near the viewport render to the DOM.

FAQ

Can ngDiagram import or export BPMN 2.0 XML?
Not out of the box. The model round-trips as JSON (toJSON() / initializeModel), and you can write a .bpmn mapping on top of the typed model when you need it. If standard XML interchange is the core requirement, use bpmn-js.

How many elements can a DOM-rendered diagram handle?
Hundreds of nodes work without tuning, and ngDiagram documents viewport virtualization for larger models. Real-world BPMN diagrams rarely exceed a few hundred elements.

How do users draw connections between elements?
They drag between ports. A config function (validateConnection) checks each connection and blocks lanes from being endpoints. A second function (finalEdgeDataBuilder) turns every drawn connection into a typed sequence flow.

Can the ngDiagram watermark be removed?
Yes. The documented hideWatermark: true config disables it. ngDiagram is Apache 2.0, so this is allowed by the license – unlike bpmn-js, whose license requires its watermark to stay visible.

What is ngDiagram and who maintains it?
ngDiagram is an open-source Angular diagramming library built from scratch by Synergy Codes and released under Apache 2.0. It provides composable building blocks – nodes, edges, groups – with native Angular patterns: components, services, dependency injection, and signal-based change detection. It targets production use with hundreds of nodes: workflow editors, org charts, industrial schematics, network topologies. Full guides live at ngdiagram.dev/docs.

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