What is ngx-workflow?

ngx-workflow is an Angular Signals library for building interactive flowchart and node-based workflow editors with ELK layout, smart edges, minimap, and studio chrome.

Which Angular versions does ngx-workflow support?

ngx-workflow supports Angular 17.1 through Angular 22.

How do I install ngx-workflow?

Install with npm install ngx-workflow, then import NgxWorkflowModule or the standalone diagram component.

Is ngx-workflow a React Flow alternative for Angular?

Yes. It is an Angular-native Signals alternative to React Flow / xyflow for flowchart and node-editor UIs.

Inputs API · ngx-workflow

Connection limits (quick example)

Cap how many edges can attach to a port. Priority: handleConfig[port].maxConnections → node.maxConnectionsPerPort → [maxConnectionsPerHandle].

<ngx-workflow-diagram
  [nodes]="nodes()"
  [edges]="edges()"
  [maxConnectionsPerHandle]="2"
  (nodesChange)="nodes.set($event)"
  (edgesChange)="edges.set($event)"
/>

// Per-node / per-port overrides
nodes.set([{
  id: 'process',
  label: 'Process',
  position: { x: 120, y: 80 },
  ports: 4,
  maxConnectionsPerPort: 1,
  handleConfig: {
    bottom: { maxConnections: 3 }
  }
}]);

These fields (and RGBA colors, edge animation, markers) are also editable in the properties sidebar when a node is selected (“Max connections / port” and “Per-port limits”).

Data

Input	Type	Default	Description
`[nodes]`	`Node[]`	`[]`	Controlled array of nodes to display. Syncs into diagram state when provided.
`[edges]`	`Edge[] \| undefined`	`undefined`	Controlled edges array. Pass an array (including []) for controlled mode; omit for uncontrolled internal state.
`[initialNodes]`	`Node[]`	`[]`	Seed nodes used once on first init when not driving [nodes] as controlled state.
`[initialEdges]`	`Edge[]`	`[]`	Seed edges used once on first init when not driving [edges] as controlled state.
`[nodeTypes]`	`Record<string, Type<any>>`	`{}`	Map of custom node type name → Angular component class.
`[defsTemplate]`	`TemplateRef<any>`	`undefined`	Angular template containing SVG <defs> (markers, gradients, filters).
`[edgeTemplate]`	`TemplateRef<any>`	`undefined`	Custom template for rendering edge labels / overlays.

Viewport

Input	Type	Default	Description
`[initialViewport]`	`Viewport`	`undefined`	Initial viewport state { x, y, zoom }. Useful for restoring saved views.
`[minZoom]`	`number`	`0.1`	Minimum allowed zoom level.
`[maxZoom]`	`number`	`4`	Maximum allowed zoom level.
`[autoPanOnNodeDrag]`	`boolean`	`true`	Pan canvas automatically when dragging a node near the viewport edge.
`[autoPanOnConnect]`	`boolean`	`true`	Pan canvas automatically when dragging a connection near the viewport edge.
`[autoPanSpeed]`	`number`	`15`	Pixels per frame for auto-pan.
`[autoPanEdgeThreshold]`	`number`	`50`	Distance in pixels from the viewport edge to trigger auto-pan.

Appearance

Input	Type	Default	Description
`[showBackground]`	`boolean`	`true`	Whether to show the background pattern (dots/lines/cross).
`[backgroundVariant]`	`'dots' \| 'lines' \| 'cross'`	`'dots'`	Background pattern style.
`[backgroundImage]`	`string \| null`	`null`	URL for a custom background image. Overrides pattern if set.
`[backgroundGap]`	`number`	`20`	Gap between background pattern elements in pixels.
`[backgroundSize]`	`number`	`1`	Size of background pattern elements (e.g. dot radius).
`[backgroundColor]`	`string`	`'#81818a'`	Color of the background pattern dots/lines.
`[backgroundBgColor]`	`string`	`'transparent'`	Base canvas background color.
`[colorMode]`	`'light' \| 'dark' \| 'system'`	`undefined (inherit host app)`	Color theme for this diagram only. When unset, inherits the host page theme and never mutates document.documentElement.
`[zIndexMode]`	`'default' \| 'layered'`	`'default'`	Strategy for node z-indexing / stacking.
`[showGrid]`	`boolean`	`false`	Show a grid overlay on the canvas.

Controls

Input	Type	Default	Description
`[showZoomControls]`	`boolean`	`true`	Show zoom in / out / fit view controls.
`[zoomControlsConfig]`	`ZoomControlsConfig \| undefined`	`undefined`	Customize zoom controls toolbar position (e.g. bottom-left, top-right), visible slots, custom action buttons, icons, or separators.
`[showMinimap]`	`boolean`	`true`	Show the minimap overlay.
`[showExportControls]`	`boolean`	`false`	Show export controls UI (PNG, SVG, clipboard, JSON).
`[showUndoRedoControls]`	`boolean`	`true`	Show undo / redo history controls.
`[showLayoutControls]`	`boolean`	`false`	Show auto-layout / alignment controls.
`[showPropertiesSidebar]`	`boolean`	`false`	Enable or disable the built-in node/edge properties editing sidebar on double-click.

Behavior

Input	Type	Default	Description
`[connectionValidator]`	`(source: string, target: string) => boolean`	`undefined`	Global custom validator for new connections (node ids only).
`[validateConnection]`	`(connection) => boolean`	`undefined`	Richer connection validation including source/target handle ids.
`[maxConnectionsPerHandle]`	`number \| undefined`	`undefined`	Global max edges per port. Overridden by node.maxConnectionsPerPort and handleConfig[port].maxConnections. Leave undefined for unlimited.
`[proximityThreshold]`	`number`	`200`	Distance (graph units) for auto-connect when dragging a node near another.
`[nodesResizable]`	`boolean`	`true`	Global toggle to enable/disable node resizing.
`[snapToGrid]`	`boolean`	`false`	Snap node positions to the grid while dragging.
`[gridSize]`	`number`	`20`	Grid size in pixels for snap-to-grid.
`[preventNodeOverlap]`	`boolean`	`false`	Enable collision detection to prevent nodes overlapping.
`[nodeSpacing]`	`number`	`10`	Minimum spacing between nodes when preventNodeOverlap is true.
`[edgeReconnectable]`	`boolean`	`false`	Allow dragging edge endpoints to reconnect them to other ports.
`[optimization]`	`FlowOptimization`	`{ virtualization: true, adaptiveBuffer: true, hideEdgesBelowZoom: 0.4 }`	Performance tuning options for large diagrams (spatial culling, adaptive zoom buffer, edge virtualization, and hideEdgesBelowZoom threshold).

Persistence

Input	Type	Default	Description
`[autoSave]`	`boolean`	`false`	Enable auto-saving of diagram state to localStorage.
`[autoSaveInterval]`	`number`	`1000`	Throttled auto-save interval in milliseconds.
`[maxVersions]`	`number`	`10`	Max number of auto-save version snapshots to keep.

Node model fields (not diagram inputs)

Set these on each Node object in [nodes]:

Field	Type	Description
`ports`	`0 \| 1 \| 2 \| 3 \| 4`	0=None, 1=Top, 2=Top/Bottom, 3=Left/Right, 4=All (default).
`maxConnectionsPerPort`	`number`	Default max edges for every port on this node.
`handleConfig[id].maxConnections`	`number`	Override limit for a specific port (`top`, `right`, `bottom`, `left`).
`handleConfig[id].isConnectable`	`boolean \| number \| fn`	Whether the port accepts connections (number = max count).
`easyConnect`	`boolean`	Drag from node body to start a connection (use `.drag-handle` to move).