A comprehensive overview of ngDiagram’s core concepts, helping you understand the library’s capabilities without reading the entire documentation.

Getting Started

The simplest way to start is by installing the library, importing the required styles, and creating a component with the NgDiagramComponent and provideNgDiagram() in its providers. The diagram component needs a model with nodes and edges to display.

Quick Start Guide for step-by-step setup

Model & Data

ngDiagram uses a reactive model to manage diagram state. You initialize the model with nodes and edges, each having required properties like ID and position. The model is the single source of truth for your diagram’s data.

Key concepts:

• Initialize model with initializeModel()
• Nodes require: id, position, data
• Edges require: id, source, target, sourcePort, targetPort, data
• Custom properties can be stored in the data field of nodes and edges
• Use metadata for diagram-level custom information

You can also implement custom model adapters to connect to external data sources like databases or real-time services.

State Management → | Custom Model Example → | Model initialization →

Caution

Never modify nodes or edges directly. Always use services to update the model to maintain reactivity.

Service Isolation

Every diagram requires provideNgDiagram() in its component’s providers array, which supplies all necessary services with proper scope isolation. This architecture allows you to have multiple independent diagrams on the same page, each with its own state and services.

Benefits:

• Isolated service instances per diagram
• Independent state management
• Multiple diagrams on one page
• No conflicts between instances

Architecture Documentation →

Nodes

ngDiagram provides default nodes that work out of the box with built-in features like selection, dragging, and ports. Default nodes display a label and have standard connection points.

Default node features:

• Automatic rendering with label (shows node data label or falls back to node ID)
• Built-in selection and hover states
• Drag to reposition
• Two bidirectional connection ports (left and right)
• Resize handles
• Rotation handle
• Automatic port hover indicators
• Automatic sizing by default (autoSize: true) - nodes resize to fit their content

Note

To set a manual size for nodes, you must explicitly set autoSize: false along with the size property. Without this, the size property will be overridden by the automatic sizing behavior.

For specific requirements, you can create custom nodes with any Angular template, form controls, or visual elements you need.

Components for custom nodes:

• NgDiagramPortComponent - Define custom ports with specific IDs, sides, and connection types
• NgDiagramNodeResizeAdornmentComponent - Add resize handles to custom nodes
• NgDiagramNodeRotateAdornmentComponent - Add rotation handle to custom nodes
• NgDiagramNodeSelectedDirective - Apply selection styling to custom nodes

Nodes Documentation → | Custom Nodes →

Groups

Groups are special nodes that can contain other nodes, helping organize complex diagrams into logical sections. They support nesting and group-aware interactions.

Group capabilities:

• Container for other nodes
• Nested groups support
• Visual hierarchy
• Group-aware dragging
• NgDiagramGroupHighlightedDirective - Apply highlight styling to custom group nodes during drag-over operations

Groups Documentation →

Edges

Edges connect nodes through ports. Default edges automatically calculate paths between nodes and support different routing algorithms. Like nodes, you can create custom edge templates for specialized visualizations.

Edge features:

• Automatic path calculation
• Three routing modes (orthogonal, straight, bezier)
• Labels support (default edges support labels out of the box)
• Custom arrowheads (customizable using SVG markers)
• Custom edge templates
• Selection and hover states

Edges Documentation → | Custom Edges →

Ports

Ports define where edges can connect to nodes. Default nodes have two ports (left and right), but you can define custom ports with specific positions and connection rules in custom node templates.

Port system:

• Default ports: port-left, port-right (bidirectional)
• Four possible sides: top, right, bottom, left
• Three connection types: source (outgoing only), target (incoming only), both (bidirectional)
• Custom port positions and IDs in custom node templates
• Visual hover indicators when dragging connections

Ports Documentation →

Viewport

The viewport is the interactive space where all diagram elements are rendered and manipulated. It determines what part of the diagram is visible and supports navigation and scaling.

Viewport features:

• Zoom in/out for detail or overview
• Pan to navigate large diagrams
• All elements are positioned relative to the viewport’s coordinate system

Viewport Features →

Background

The diagram background can display visual patterns to help with alignment and spatial awareness. The NgDiagramBackgroundComponent needs to be added to your diagram template to display the background.

Background capabilities:

• Built-in patterns: dots, grid with major/minor lines
• Customizable via background configuration (dotSpacing, cellSize, majorLinesFrequency)
• Support for custom backgrounds via content projection
• Automatically scales with viewport zoom

Background Documentation →

Labels and Arrowheads

Custom edges can display labels for showing information along connections. You can add multiple labels with different positions in your custom edge templates. Arrowheads are customizable using SVG markers.

Visual enhancements:

• Edge labels in custom edges
• Multiple labels per edge
• Custom arrowhead designs
• SVG-based customization for arrowheads

Labels Documentation → | Arrowheads →

Interactions

Nodes can be configured for different interaction modes. Enable resizing to allow users to change node dimensions, rotation for angular adjustments. Selection state is tracked automatically, but custom components need to implement visual feedback.

Interaction options:

• Resizable: Enable resize handles on nodes by setting resizable: true
• Rotatable: Enable rotation handle on nodes by setting rotatable: true
• Selection: Click to select nodes and edges
  • Custom nodes: Use NgDiagramNodeSelectedDirective as hostDirective for selection styles
  • Custom edges: Use NgDiagramBaseEdgeComponent or implement selection styles manually
  • Default templates have selection styles built-in
• Copy/Paste: Copy, cut, and paste diagram elements
  • Keyboard shortcuts can be updated via configureShortcuts(), defaults are: Ctrl/Cmd+C (copy), Ctrl/Cmd+X (cut), Ctrl/Cmd+V (paste)
  • Programmatic access via NgDiagramClipboardService

Selection → | Resizing → | Rotation → | Keyboard Shortcuts →

Configuration

Most diagram behavior is configurable through the config object passed to the diagram component.

Configurable aspects:

• background - Background dot spacing, cell size, and major lines frequency
• boxSelection - Box selection behavior (partial inclusion, real-time selection)
• computeEdgeId - Function to generate unique edge IDs
• computeNodeId - Function to generate unique node IDs
• debugMode - Enable additional console logging
• edgeRouting - Default routing algorithm (orthogonal, bezier, polyline) and routing-specific settings
• grouping - Rules for which nodes can be grouped together
• linking - Edge creation validation, snap distance, and custom edge builders
• nodeRotation - Rotation snapping angles and default rotatable state
• resize - Minimum node size constraints and default resizable state
• selectionMoving - Edge panning behavior when dragging near viewport edges
• snapping - Grid snapping for dragging and resizing with customizable snap points
• zIndex - Layer management for selected elements and edge-node relationships
• zoom - Min/max zoom levels, zoom step, and zoom-to-fit settings

Services

ngDiagram provides injectable services for all diagram operations. Services are the only way to safely update the model and control diagram behavior programmatically.

Core services:

• NgDiagramService - Diagram API access:
  • Config, events, transactions
  • Middleware registration
  • Routing management (registerRouting(), unregisterRouting(), getRegisteredRoutings())
  • Programmatic linking (startLinking())
  • Environment info (getEnvironment())
• NgDiagramModelService - CRUD operations:
  • Nodes, edges, and metadata management
  • Model serialization (toJSON())
  • Reactive signals for nodes, edges, metadata
• NgDiagramViewportService - Viewport control:
  • Zoom, pan, and positioning (zoomToFit())
  • Coordinate conversion (clientToFlowPosition(), flowToClientPosition())
  • Navigation helpers (centerOnNode(), centerOnRect())
• NgDiagramSelectionService - Manage selection state for nodes and edges
• NgDiagramNodeService - Node-specific operations (move, resize, rotate)
• NgDiagramGroupsService - Group/ungroup nodes and manage group hierarchies
• NgDiagramClipboardService - Copy/paste/cut operations for diagram elements

Services use Angular signals for reactive state management, making it easy to build reactive UI components.

Services Documentation →

Events

The diagram emits events for user interactions and state changes. Subscribe to these events to react to user actions or synchronize with external systems.

Available events:

• diagramInit - Fired when diagram is fully initialized with all nodes and edges measured
• edgeDrawn - Fired when user manually creates an edge by dragging between nodes
• selectionChanged - Fired when nodes/edges are selected or deselected
• selectionMoved - Fired when selected nodes are moved (dragged)
• selectionRemoved - Fired when selected nodes/edges are removed from the diagram
• selectionRotated - Fired when selected nodes are rotated
• groupMembershipChanged - Fired when nodes are grouped or ungrouped
• viewportChanged - Fired when viewport is panned or zoomed
• clipboardPasted - Fired when elements are pasted from clipboard
• nodeResized - Fired when a node is resized
• paletteItemDropped - Fired when a palette item is dropped onto the diagram

Events can be subscribed to via @Output bindings on the ng-diagram component or programmatically through NgDiagramService.addEventListener().

Edge Routing

Edges support multiple routing algorithms for different visual styles. You can control how edges are drawn between nodes using both automatic and manual approaches.

Built-in routing algorithms:

• Orthogonal - Right-angle paths between nodes
• Polyline - Straight line segments between points
• Bezier - Smooth curved connections with control points

Routing modes:

• Auto mode (routingMode: 'auto') - Algorithm automatically calculates the path between nodes
• Manual mode (routingMode: 'manual') - You provide custom waypoints in the points array, algorithm renders the path through your points

Set routing per edge with the routing property, or globally through configuration with edgeRouting.defaultRouting. For complete custom routing algorithms, use NgDiagramService.registerRouting().

Routing Documentation →

Palette

The palette system enables drag-and-drop node creation. Build your own palette container using the provided components to let users drag items onto the diagram.

Palette components:

• NgDiagramPaletteItemComponent - Wrapper for draggable palette items
• NgDiagramPaletteItemPreviewComponent - Live preview shown while dragging

Palette features:

• Drag-and-drop to create nodes at drop location
• Custom item templates and preview templates
• Support for creating both regular nodes and group nodes
• Visual feedback with live preview during drag

Palette Documentation → | Palette Example →

Custom Middlewares

ngDiagram uses a middleware system that allows you to intercept and modify any state changes. Register custom middleware via NgDiagramService.registerMiddleware() to override any aspect of the application and create low-level features.

Middleware capabilities:

• Intercept all state updates before they’re applied
• Modify or cancel operations
• Add custom side effects
• Implement complex business logic
• Create custom behaviors and constraints

Caution

Use middlewares carefully - poorly implemented middleware can break core functionality and severely impact performance. Always test thoroughly and ensure your middleware properly passes through unhandled operations.

Middleware Documentation →

Styling System

ngDiagram provides a comprehensive CSS variable system for theming and customization. You can override colors, borders, and other visual properties to match your application’s design.

Styling Guide →

---

Explore our Examples to see these concepts in action.