Nodes are the fundamental building blocks of a diagram in ngDiagram. They represent entities such as components, processes, or data sources within your system. Each node can contain metadata, inputs, outputs, or custom content, and can be styled or configured to fit your use case.

interface Node<T = any> {
  id: string; // ID of the edge
  position: string; // The position of the node in the diagram.
  data: T; // Custom data associated with the node
  // ...optional properties
}

Node API Reference →

Adding Nodes to a Diagram

To add nodes to your diagram, include them in the nodes array of your model:

import '@angular/compiler';

import { Component } from '@angular/core';
import {
  initializeModel,
  NgDiagramBackgroundComponent,
  NgDiagramComponent,
  provideNgDiagram,
} from 'ng-diagram';

@Component({
  imports: [NgDiagramComponent, NgDiagramBackgroundComponent],
  providers: [provideNgDiagram()],
  // @mark-substring [model]="model"
  template: `
    <div class="not-content diagram">
      <ng-diagram [model]="model">
        <ng-diagram-background />
      </ng-diagram>
    </div>
  `,
  styles: [
    `
      .diagram {
        display: flex;
        height: var(--ng-diagram-height);
        border: var(--ng-diagram-border);
      }
    `,
  ],
})
export class DiagramComponent {
  model = initializeModel({
    nodes: [
      {
        id: '1',
        position: {
          x: 0,
          y: 0,
        },
        data: { label: 'Node 1' },
      },
    ],
  });
}

Default Node

NgDiagram provides a default node implementation that covers the most common scenarios.
The default node provides the following features:

• Fully styled component — Represents a visual entity with one input and one output.
• Rotation and resizing support — Enabled by default through resize.defaultResizable and nodeRotation.defaultRotatable.
• Label display — Shows a label, provided by convention in data.label.
• Interactive states — Responds to hover and selection for better interactivity.
• Simplicity — Ideal for representing simple text-based entities.

To use the default node template, leave the node’s type property empty.

Features

The default node comes with built-in support for resizing and rotating through interactive adornments. By default, these features are enabled through the resize.defaultResizable and nodeRotation.defaultRotatable configuration options, but can be overridden per node using the resizable and rotatable properties. These features can also be enabled in custom nodes by adding the adornments to their templates.

Resizing → | Rotation →

Ports

Nodes can expose one or more ports, which define the connection points for edges. By convention, the default node includes a single input and a single output port, but you can customize the number, placement, and appearance of ports in your own node templates.

Note

Nodes can also have no ports at all, but without ports, they cannot be connected to other nodes with edges.

Ports →

Customization

When the default appearance is too generic, you can easily customize it using CSS variables. This allows you to adjust colors, borders, and other visual properties without creating a new node type from scratch.

import '@angular/compiler';

import { Component } from '@angular/core';
import {
  initializeModel,
  NgDiagramBackgroundComponent,
  NgDiagramComponent,
  provideNgDiagram,
  type NgDiagramConfig,
} from 'ng-diagram';

@Component({
  imports: [NgDiagramComponent, NgDiagramBackgroundComponent],
  providers: [provideNgDiagram()],
  template: `
    <div class="not-content default-diagram">
      <ng-diagram [config]="config" [model]="model">
        <ng-diagram-background />
      </ng-diagram>
    </div>
  `,
  styles: `
    .default-diagram {
      display: flex;
      height: var(--ng-diagram-height);
      border: var(--ng-diagram-border);

      --ngd-node-border-color: #d04a02;
      --ngd-node-border-color-hover: #9b0018;
      --ngd-node-border-radius: 1.75rem;
      --ngd-node-bg-primary-default: #240f0f;

      --ngd-txt-primary-default: #ffffff;

      --ngd-port-border-color: #d04a02;
      --ngd-port-background-color-hover: #9b0018;

      --ngd-selected-node-box-shadow: 0 0 0 0.25rem #9b001852;
    }
  `,
})
export class DiagramComponent {
  config = {
    zoom: {
      zoomToFit: {
        onInit: true,
        padding: 190,
      },
    },
  } satisfies NgDiagramConfig;

  model = initializeModel({
    nodes: [
      {
        id: '1',
        position: { x: 0, y: 0 },
        data: { label: 'Node 1' },
      },
    ],
  });
}

For deeper customization, you can also define your own node templates, giving you full control over the node’s structure and behavior.

Custom Nodes →

Position

A node’s position can be set manually through the position property:

{
  id: 'node-1',
  data: { label: 'My Node' },
  position: { x: 100, y: 100 }
}

The position is defined in diagram coordinates. If you want to learn more about how the coordinate system works, see the Coordinate system

The position also updates automatically when a user moves the node by dragging it in the diagram.

Size

NgDiagram provides two main approaches to control node sizing:

• Manual sizing – explicitly set the node’s dimensions with the size property.
• Automatic sizing – let the node adjust to its content automatically.

The size property is optional. If not provided, the size will be calculated based on the content of the node.

To precisely control the size of a node, use the size property:

{
  id: 'node-1',
  data: { label: 'My Node' },
  size: { width: 120, height: 60 },
  autoSize: false
}

Note

By default, nodes use automatic sizing (autoSize: true). In this mode, the provided size property is ignored, and the node resizes itself to fit its content. The size property is then updated with the measured values.

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