# ngDiagram
[](https://badge.fury.io/js/ng-diagram)
[](https://opensource.org/license/apache-2-0)
A robust Angular library for building interactive diagrams, node-based editors, and visual programming interfaces. Designed with Angular and TypeScript, it offers a complete toolkit to create sophisticated, customizable, and high-performance diagramming applications.
Unlike generic diagramming libraries, **ngDiagram** is Angular-first - built on Angular signals and templates for seamless integration and performance.
## โจ Features
- **๐ฏ Interactive Elements**: Draggable, resizable, and rotatable nodes
- **๐ Flexible Edges**: Orthogonal, polyline, and bezier routing, custom arrowheads, labels, and floating edges that connect without ports
- **๐งฉ Custom Templates**: Your own Angular components as nodes and edges โ templates, signals, DI, everything works
- **๐ฆ Groups**: Container nodes with nesting and group-aware dragging
- **๐๏ธ Rich Interactions**: Selection, box selection, copy/paste, snapping, panning, zooming, and more
- **โจ๏ธ Keyboard Shortcuts**: Configurable, platform-aware bindings for all common actions
- **๐ฑ Touch Support**: Pinch zoom, two-finger panning, and long-press box selection out of the box
- **๐บ๏ธ Minimap**: Bird's-eye overview widget with click-and-drag navigation
- **๐จ Consistent Styling**: Built-in design system with CSS variables and light/dark themes
- **๐ฑ๏ธ Embedded Palette**: Built-in drag-and-drop palette system for adding nodes to diagrams
- **โก Performance**: Signal-based reactivity, spatial hashing, and viewport virtualization for large diagrams
- **๐ Extensible Architecture**: Middleware pipeline for custom behaviors and business logic
- **๐ค AI-Ready Docs**: Official [MCP server](https://www.npmjs.com/package/@ng-diagram/mcp) lets AI assistants search the docs and API from your editor
## ๐ What You Can Build
With ngDiagram, you can create:
- **Flow Diagrams**: Process flows, decision trees, and workflow visualizations
- **Node-Based Editors**: Visual programming interfaces and data flow editors
- **Network Diagrams**: System architectures and network topologies
- **Mind Maps**: Hierarchical information structures and brainstorming tools
- **Circuit Diagrams**: Electronic schematics and technical drawings
- **Custom Visualizations**: Any diagram type with custom node and edge templates
See our [Templates](#-templates) for production-ready examples you can fork and customize.
## ๐ฎ Try the Demo
See ngDiagram in action: **[Live Demo](https://synergycodes.github.io/ng-diagram-demo/)** | **[Source Code](https://github.com/synergycodes/ng-diagram-demo)**
## ๐ Video Course
Learn ngDiagram by building an Angular workflow builder from scratch โ a step-by-step video series by the team:
1. **[Angular workflow builder from scratch | ngDiagram Ep. 1: Project setup](https://youtu.be/Ck_lPtyKE_Q)**
2. **[Angular signals, zero glue code | ngDiagram Ep. 2: Properties panel](https://youtu.be/8CdH9Rk99KE)**
3. **[Custom nodes in an Angular workflow builder | ngDiagram Ep. 3: Node types](https://youtu.be/UzK0h9wcyEo)**
The series is ongoing โ new episodes are in production. Follow the [Synergy Codes YouTube channel](https://www.youtube.com/@synergycodes) to catch the next one.
## ๐งฉ Templates
Production-ready starter kits built with ngDiagram. Fork, customize, ship.
| Template | Description | Demo | Source |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **Org Chart** | Tree-based org chart with drag-and-drop reordering, expand/collapse, ELK.js layout, minimap, dark/light theme | [Live Demo](https://www.ngdiagram.dev/templates/org-chart/) | [Source](https://github.com/synergycodes/ng-diagram-orgchart) |
| **Electric Circuit** | Electronic circuit editor with a searchable SVG parts library, smart wire junctions, and SVG/JPEG/JSON export | [Live Demo](https://www.ngdiagram.dev/templates/electric-circuit/) | [Source](https://github.com/synergycodes/ng-diagram-electric-circuit) |
| **Single-Line Diagram** | High-voltage substation SLD editor with IEC 60617 symbols and a schema-driven properties panel | [Live Demo](https://www.ngdiagram.dev/templates/single-line-diagram/) | [Source](https://github.com/synergycodes/ng-diagram-single-line-diagram) |
| **AV Schematic** | Audio/video signal-flow editor with typed connectors (XLR, HDMI, Speakon) and PNG/DXF export for AutoCAD | [Live Demo](https://www.ngdiagram.dev/templates/av/) | [Source](https://github.com/synergycodes/ng-diagram-av-schematic) |
| **Assembly Line** | Production-line monitor with Edit/Monitor modes, a live data feed, threshold-colored KPIs, sparklines, and PNG/SVG/DXF export | [Live Demo](https://www.ngdiagram.dev/templates/assembly-line/) | [Source](https://github.com/synergycodes/ng-diagram-assembly-line) |
## ๐ Quick Start
### Installation
```bash
npm install ng-diagram
```
### Import Styles
**โ ๏ธ Important:** You must import the required styles for the diagram to display correctly.
Because the library uses **CSS variables**, import the stylesheet in your **global file** (e.g. `src/styles.scss`), not inside a component.
```css
/* src/styles.scss */
@import 'ng-diagram/styles.css';
```
### Create Your First Diagram
```typescript
import { Component } from '@angular/core';
import { NgDiagramComponent, initializeModel, provideNgDiagram } from 'ng-diagram';
@Component({
imports: [NgDiagramComponent],
providers: [provideNgDiagram()],
template: ` `,
styles: `
:host {
display: flex;
height: 300px;
}
`,
})
export class MyDiagramComponent {
model = initializeModel({
nodes: [
{ id: '1', position: { x: 100, y: 150 }, data: { label: 'Node 1' } },
{ id: '2', position: { x: 400, y: 150 }, data: { label: 'Node 2' } },
],
edges: [
{
id: '1',
source: '1',
sourcePort: 'port-right',
targetPort: 'port-left',
target: '2',
data: {},
},
],
});
}
```
That's it! You now have a working diagram with default node and edge templates.
## ๐จ Customization
### Custom Nodes
Create custom node components with any Angular template:
```typescript
import { Component, input } from '@angular/core';
import { NgDiagramPortComponent, type NgDiagramNodeTemplate, type Node } from 'ng-diagram';
type CustomNodeData = { title: string; description: string };
@Component({
selector: 'app-custom-node',
imports: [NgDiagramPortComponent],
template: `
{{ node().data.title }}
{{ node().data.description }}
`,
styles: [
`
.custom-node {
background: #fff;
border: 2px solid #333;
border-radius: 8px;
padding: 16px;
min-width: 200px;
}
`,
],
})
export class CustomNodeComponent implements NgDiagramNodeTemplate {
node = input.required>();
}
```
### Custom Edges
Create custom edge components with unique visual styles:
```typescript
import { Component, input } from '@angular/core';
import { NgDiagramBaseEdgeComponent, type Edge, type NgDiagramEdgeTemplate } from 'ng-diagram';
@Component({
selector: 'app-custom-edge',
imports: [NgDiagramBaseEdgeComponent],
template: ` `,
})
export class CustomEdgeComponent implements NgDiagramEdgeTemplate {
edge = input.required();
}
```
## ๐ ๏ธ Core Building Blocks
The library ships **components** for the diagram canvas, backgrounds, ports, palette, and minimap; **injectable services** (model, nodes, selection, viewport, clipboard, groups) for programmatic control; and **directives** for selection and highlight styling. Start with the [Services guide](https://www.ngdiagram.dev/docs/intro/services/) and browse the full API reference in the [documentation](https://www.ngdiagram.dev/docs).
## ๐ฉโ๐ป About the Creators
ngDiagram is built and maintained by [**Synergy Codes**](https://www.synergycodes.com) - a team of developers whoโve spent **over a decade designing and delivering diagramming solutions** for clients worldwide.
We are continuously distilling everything we know about building interactive diagrams, editors, and visual tools into this library. Our goal is simple: to empower Angular developers to create diagramming applications faster, easier, and with confidence.
When you use this library, you can be sure youโre in **good hands** - backed by a team that knows diagrams inside out.
## ๐ Documentation
For comprehensive documentation, examples, and API reference, visit:
**๐ [Full Documentation](https://www.ngdiagram.dev/docs)**
The documentation includes:
- Detailed API reference
- Interactive examples
- Customization guides
- Best practices
- Advanced use cases
## ๐ค MCP Server
Use AI assistants like Claude, Cursor, or Windsurf to search ngDiagram docs and API directly from your editor. No browser needed.
```json
{
"mcpServers": {
"ng-diagram-docs": {
"command": "npx",
"args": ["-y", "@ng-diagram/mcp"]
}
}
}
```
See [@ng-diagram/mcp](https://www.npmjs.com/package/@ng-diagram/mcp) for setup details and Windows configuration.
## ๐ง Requirements
- **Angular**: 18.0.0 or higher
- **TypeScript**: 5.6.0 or higher
- **Node.js**: 18.19.1 or higher
## ๐ License
This project is licensed under the Apache 2.0 License - see the [LICENSE](https://github.com/synergycodes/ng-diagram/blob/main/LICENSE) file for details.
## ๐ Links
- **Documentation**: [https://www.ngdiagram.dev/docs](https://www.ngdiagram.dev/docs)
- **GitHub**: [https://github.com/synergycodes/ng-diagram](https://github.com/synergycodes/ng-diagram)
- **NPM**: [https://www.npmjs.com/package/ng-diagram](https://www.npmjs.com/package/ng-diagram)
- **MCP Server**: [@ng-diagram/mcp](https://www.npmjs.com/package/@ng-diagram/mcp) - let AI assistants search ngDiagram docs and API
- **Website**: [https://www.ngdiagram.dev](https://www.ngdiagram.dev)
## ๐ Support
- **Issues**: [GitHub Issues](https://github.com/synergycodes/ng-diagram/issues)
- **Discussions**: [GitHub Discussions](https://github.com/synergycodes/ng-diagram/discussions), [Discord](https://discord.gg/FDMjRuarFb)
- **Project consulting**: [Contact](https://www.ngdiagram.dev/contact)
- **Documentation**: [https://www.ngdiagram.dev/docs](https://www.ngdiagram.dev/docs)
---
Built with โค๏ธ by the [Synergy Codes](https://www.synergycodes.com/) team