Skip to main content

Quick Start

Installation​

First create a new app (if you need to, otherwise skip this and move to the install command below). There are various tools for this, but we'd recommend Vite.

Javascript

npm init vite visuallyjs-app -- --template svelte

Typescript

npm init vite visuallyjs-app -- --template svelte-ts

Then cd into your project directory and install VisuallyJs:

npm install @visuallyjs/browser-ui-svelte

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-svelte-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 Svelte 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 Svelte 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 SurfaceComponent from @visuallyjs/browser-ui-svelte to render a zoomable and pannable canvas.

  1. Remove all the code from src/App.svelte and replace with this:
<script>
    import { SurfaceComponent } from "@visuallyjs/browser-ui-svelte"
    
    const data = {
        nodes:[
            { id:"1", label:"Hello", left:50, top:50 },
            { id:"2", label:"World", left:50, top:250 }
        ],
        edges:[
            { source:"1", target:"2" }
        ]
    }

</script>

<div class="my-container">
  <SurfaceComponent data={data}/>
</div>

  1. Remove all the code from src/app.css and replace with this:
@import "../node_modules/@visuallyjs/browser-ui/css/visuallyjs.css";

.my-container {
    width:600px;
    height:500px;
    position:relative;
    outline:1px solid;
}

.vjs-surface {
    width:100%;
    height:100%;
}


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.

Replace the contents of src/App.svelte with this:

<script>

  import { 
    SurfaceProvider, 
    SurfaceComponent, 
    ControlsComponent, 
    MiniviewComponent } from "@visuallyjs/browser-ui-svelte"

  import MyComponent from "./lib/MyComponent.svelte";

  const data = {
        nodes:[
            { id:"1", label:"Hello", left:50, top:50, bg:"cadetblue" },
            { id:"2", label:"World", left:50, top:200, bg:"forestgreen" }
        ],
        edges:[
            { source:"1", target:"2" }
        ]
    }

  const viewOptions = {
      nodes:{
        default:{
          component:MyComponent
          }
       }
    }

</script>

<div class="my-container">
  <SurfaceProvider>
    <SurfaceComponent data={data} viewOptions={viewOptions}/>
    <MiniviewComponent/>
    <ControlsComponent/>
  </SurfaceProvider>
</div>

Try clicking on the label for each node - you'll get a popup with its ID, which we sourced from the data prop of the component. You might have noticed that our MyComponent actually declares 4 props - they're not all used in this example, but VisuallyJs passes in the current Surface, the Vertex model object, the data backing the object, and the data model itself. With all these props available you can implement flexible and powerful components.

This is a simple example but hopefully gives you an idea of what is possible when you use Svelte components to render the nodes in your UI.

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

Build a Diagram​

Diagrams use SVG shapes to render their nodes and groups. It's straightforward to create one - first replace the contents of src/App.svelte with this code:

<script>
import { FLOWCHART_SHAPES, ArrowOverlay } from "@visuallyjs/browser-ui"
import { DiagramComponent } from "@visuallyjs/browser-ui-svelte"
    
const 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"}
  ]
}
    
const options = {
  shapes: FLOWCHART_SHAPES,
  edges: {
    overlays: [
      {
        type: ArrowOverlay.type,
        options: {
          location: 1
        }
      }
    ]
  },
  zoomToFit: true
}
    
</script>    

<div class="my-container">
    <DiagramComponent data={data} options={options}/>
</div>

Then, remove all the code from src/app.css and replace with this:

@import "@visuallyjs/browser-ui/css/visuallyjs.css";

.my-container {
    width:600px;
    height:500px;
    position:relative;
    outline:1px solid;
}

.vjs-surface {
    width:100%;
    height:100%;
}

Build a Chart​

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

which we generated with this code:

<script>
import { ColumnChartComponent } from "@visuallyjs/browser-ui-svelte"

const chartData = [ 
      { 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 }
  ]

  const 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"
            }
        ]
    }
</script>

<ColumnChartComponent data={chartData} 
        options={chartOptions} 
        className="my-container"/>

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.

Replace the contents of src/App.svelte with this:

<script>
  import { SurfaceProvider, SurfaceComponent, ScatterChartComponent } from "@visuallyjs/browser-ui-svelte"

  const data = {
      nodes:[
          { id:"1", label:"Hello", left:50, top:50 },
          { id:"2", label:"World", left:50, top:250 }
      ],
      edges:[
          { source:"1", target:"2" }
      ]
  }

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

</script>

<div class="my-container">
    <SurfaceProvider>
        <SurfaceComponent {data}/>
        <ScatterChartComponent options={chartOptions}/>
    </SurfaceProvider>
</div>

Next Steps​

Where to from here?

Apps
Read about building professional visual apps with Svelte components
Diagrams
Read about how to build SVG diagrams with VisuallyJs
Charts
Read about Visually'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