Skip to main content

Quick Start

Installation​

First create a new Angular application (if you need to, otherwise skip this and move to the install command below).

ng new visuallyjs-app

Then cd into your project directory and install VisuallyJs:

npm install @visuallyjs/browser-ui-angular

Module setup​

If your app is using standalone components you don't need to import the VisuallyJs module. But if you are not using standalone components you'll need to open up app.module.js and include the VisuallyJs module:

import { CUSTOM_ELEMENTS_SCHEMA } from "@angular/core"
import { VisuallyJsModule } from '@visuallyjs/browser-ui-angular'

...

@NgModule({
    imports:      [ BrowserModule, VisuallyJsModule],
    declarations: [ SomeComponent ],
    bootstrap:    [ SomeComponent ],
    schemas:[ CUSTOM_ELEMENTS_SCHEMA ]
})
note

Be sure to import the CUSTOM_ELEMENTS_SCHEMA schema when you import the VisuallyJs module. Without this import you will not be able to map components to node/group types.

MCP​

To speed up your development you can optionally setup our MCP server with your agent - we provide tools for searching the docs and the apidocs for each library integration. A full discussion of our MCP servers are available on this page, but if you've done this before, this is the command you need:

npx @visuallyjs/browser-ui-angular-mcp

Start building​

What do you want to build? VisuallyJs can be used to build a variety of different solutions. We split them up into four main categories:

Apps​

Apps use Angular components to render each node/group in the display. Functionality can be encapsulated in these components. Node/group sizes in an App are typically dependent on CSS and are managed automatically by VisuallyJs. Apps are great when you need rich content in your nodes/groups and you don't want to be limited to using SVG.

Diagrams​

Diagrams are pure SVG applications, that draw SVG shapes into an SVG canvas, and provide an API to manipulate each cell/link individually. VisuallyJs offers a Angular component that you can use to seamlessly embed a Diagram into your application, as well as several other components such as a miniview, a palette (from which shapes can be dragged onto the canvas), and basic controls such as pan/zoom/undo/redo etc.

Charts​

VisuallyJs includes a wide range of chart types—from standard Line and Bar charts to more specialized Pie, Donut, and Scatter charts, which can be rendered standalone, or integrated with the data model that is powering an App or Diagram on the same page.

Dashboards​

A powerful feature of VisuallyJs is the ability to mix and match different types of components on a single page. You can create a dashboard that combines a rich node-based canvas or a diagram with real-time charts, all powered by the same underlying data model.

For example, you might have an app representing a manufacturing process where clicking on a machine (a node in the app) updates a set of charts showing that machine's performance metrics. Or a supply chain visualizer with an attached sankey diagram giving you insights into the flow of materials - there are endless possibilities.

Build an App​

We'll use the vjs-surface component from @visuallyjs/browser-ui-angular to render a zoomable and pannable canvas.

Remove all the code from app.ts and replace with this:

import { Component } from '@angular/core';
import { VisuallyJsModule } from "@visuallyjs/browser-ui-angular"

@Component({
  selector: 'app-root',
  imports: [VisuallyJsModule],
  templateUrl: './app.html',
  styleUrl: './app.css'
})
export class App {
    
    data = {
        nodes:[
            { id:"1", label:"Hello", left:50, top:50 },
            { id:"2", label:"World", left:50, top:250 }
        ],
        edges:[
            { source:"1", target:"2" }
        ]
    }
    
}


And that's it! It's very easy to quickly build apps with VisuallyJs. That example uses a default component to render the nodes, which is great to get you up and running, but you'll typically want to provide your own. In this next snippet we supply the component to render each node and we add a miniview and some controls:

Remove all the code from app.ts and replace with this:

import { Component } from '@angular/core';
import { VisuallyJsModule } from "@visuallyjs/browser-ui-angular"

@Component({
  selector: 'app-root',
  imports: [VisuallyJsModule],
  templateUrl: './app.html',
  styleUrl: './app.css'
})
export class App {
    
    data = {
        nodes:[
            { id:"1", label:"Hello", left:50, top:50, bg:"cadetblue" },
            { id:"2", label:"World", left:50, top:250, bg:"forestgreen" }
        ],
        edges:[
            { source:"1", target:"2" }
        ]
    }
    
    viewOptions = {
      nodes:{
        default:{
          component:MyComponent
        }
      }        
    }        
}

Try clicking on the label for each node - you'll get a popup with its ID, which is sourced from the vertex tracked by the underlying BaseNodeComponent. This is a simple example but hopefully gives you an idea of what is possible when you use Angular components to render the nodes in your UI.

To find out more about building Angular apps with VisuallyJs, we'd suggest starting here.

Buid a Diagram​

Diagrams use SVG shapes to render their nodes and groups. It's straightforward to create one:

Remove all the code from app.ts and replace with this:

import { Component } from '@angular/core';
import { FLOWCHART_SHAPES, ArrowOverlay } from "@visuallyjs/browser-ui"
import { VisuallyJsModule } from "@visuallyjs/browser-ui-angular"

@Component({
  selector: 'app-root',
  imports: [VisuallyJsModule],
  templateUrl: './app.html',
  styleUrl: './app.css'
})
export class App {        
  data = {
    nodes:[
      { id:"1", label:"Begin", x:50, y:50, width:100, height:40, type:"terminus" },
      { id:"2", label:"Test", x:70, y:200, width:60, height:60, type:"decision" }
     ],
     edges:[
       { source:"1", target:"2" }
     ]
   }
   
   diagramOptions = {
     shapes:FLOWCHART_SHAPES,
     edges:{
       overlays:[
         { type:ArrowOverlay.type, options:{location:1}}
       ]
     },
     zoomToFit:true
   }            
}

Build a Chart​

VisuallyJs has support for many different types of charts. Here's a simple column chart:

which we generated with this code:

import { VisuallyJsModule } from "@visuallyjs/browser-ui-angular"
import { Component } from '@angular/core'
    
@Component({
  selector: 'app-root',
  imports: [VisuallyJsModule],
  template: '<vjs-column-chart [data]="data" [options]="chartOptions"/>',
  styleUrl: './app.css'
})
export class App {
    
  data = [
    {id:"USA",corn:387749,wheat:45321},
     {id:"China",corn:280000,wheat:140000},
     {id:"Brazil",corn:129000,wheat:10000},
     {id:"EU",corn:64300,wheat:140500},
     {id:"Argentina",corn:54000,wheat:19500},
     {id:"India",corn:34300,wheat:113500}
]
    
  chartOptions = {
  title: {
    text: "Corn vs wheat estimated production for 2023"
  },
  valueAxis: [
    {
      title: {
        text: "1000 metric tons (MT)"
      }
    }
  ],
  series: [
    {
      valueField: "corn",
      label: "Corn"
    },
    {
      valueField: "wheat",
      label: "Wheat"
    }
  ]
}   
}

Here we pass the data in to the chart when the chart is created, but there are a number of ways to supply data to chart, including the ability for a chart to source its data from the model backing an App or Diagram.

See the charts docs for a full discussion of how to use VisuallyJs to render charts.

Build a Dashboard​

It's easy to build dashboards with VisuallyJs where multiple components all reference the same data model. Here we'll show you a quick example which is from our dashboards documentation - a scatter chart that reflects the positions of the nodes in the canvas.

Remove all the code from app.ts and replace with this:

    import { Component } from '@angular/core';
    import { VisuallyJsModule } from "@visuallyjs/browser-ui-angular"

    @Component({
      selector: 'app-root',
      imports: [VisuallyJsModule],
      templateUrl: './app.html',
      styleUrl: './app.css'
    })
    export class App {
        
        data = {
            nodes:[
                { id:"1", label:"Hello", left:50, top:50 },
                { id:"2", label:"World", left:50, top:250 }
            ],
            edges:[
                { source:"1", target:"2" }
            ]
        }

chartOptions={
series:[
{
xAxisField:"left",
yAxisField:"top",
color:"#569934"
}
],
yAxis:{
inverted:true
}
}
        
    }

Next Steps​

Where to from here?

Apps
Read about building professional visual apps with Angular components
Diagrams
Read about how to build SVG diagrams with VisuallyJs
Charts
Read about VisuallyJs's powerful chart engine
Dashboards
Read more about how to build dashboards with VisuallyJs
Templates
Clone an app, diagram or chart template project
API Reference
Browse the VisuallyJs API docs