Skip to content
NgDiagram

Overview

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

Creating Your First Diagram

Section titled “Creating Your First Diagram”

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 and Data Management

Section titled “Model and Data Management”

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

Service Isolation and Multiple Instances

Section titled “Service Isolation and Multiple Instances”

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 - Building Blocks

Section titled “Nodes - Building Blocks”

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)
  • Optional resize handles (when resizable is set on the node)
  • Optional rotation handle (when rotatable is set on the node)
  • Automatic port hover indicators
  • Automatic sizing by default (autoSize: true) - nodes resize to fit their content

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

➡️ Nodes Documentation | Custom Nodes

Groups - Organizing Nodes

Section titled “Groups - Organizing Nodes”

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

➡️ Groups Documentation

Edges - Connections

Section titled “Edges - Connections”

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)
  • Custom edge templates
  • Selection and hover states

➡️ Edges Documentation | Custom Edges

Ports - Connection Points

Section titled “Ports - Connection Points”

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 - Working Area

Section titled “Viewport - Working Area”

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

Labels and Arrowheads

Section titled “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 - Resize, Rotate, Selection

Section titled “Interactions - Resize, Rotate, Selection”

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

➡️ Selection | Resizing | Rotation

Configuration

Section titled “Configuration”

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

Configurable aspects:

  • background - Background dot grid size
  • 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
  • resize - Minimum node size constraints
  • 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 and zoom step

Services - Programmatic Control

Section titled “Services - Programmatic Control”

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, routing)
  • NgDiagramModelService - CRUD operations for nodes, edges, and metadata
  • NgDiagramViewportService - Control zoom, pan, and viewport positioning
  • 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

Section titled “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
  • selectionChanged - Fired when nodes/edges are selected or deselected
  • selectionMoved - Fired when selected nodes are moved (dragged)
  • viewportChanged - Fired when viewport is panned or zoomed
  • edgeDrawn - Fired when user manually creates an edge by dragging between nodes

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

Edge Routing

Section titled “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 - Drag to Create

Section titled “Palette - Drag to Create”

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

Section titled “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

➡️ Middleware Documentation

Styling System

Section titled “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

Next Steps

Section titled “Next Steps”

Now that you understand the core concepts:

  1. Follow the Quick Start to build your first diagram
  2. Explore Examples to see implementations
  3. Read Architecture for deeper understanding
  4. Master Services for programmatic control

Each section of this overview links to detailed documentation where you can find code examples and comprehensive guides.