Graph documentation

Author Jos de Jong, Almende B.V.
Webpage http://visjs.org
License Apache License, Version 2.0

Contents

Overview

Graph is a visualization to display graphs and networks consisting of nodes and edges. The visualization is easy to use and supports custom shapes, styles, colors, sizes, images, and more.

The graph visualization works smooth on any modern browser for up to a few hundred nodes and edges.

To get started with Graph, install or download the vis.js library.

Example

Here a basic graph example. More examples can be found in the examples directory. 

<!doctype html>
<html>
<head>
    <title>Graph | Basic usage</title>

    <script type="text/javascript" src="../../vis.js"></script>
</head>

<body>

<div id="mygraph"></div>

<script type="text/javascript">
    // create an array with nodes
    var nodes = [
        {id: 1, label: 'Node 1'},
        {id: 2, label: 'Node 2'},
        {id: 3, label: 'Node 3'},
        {id: 4, label: 'Node 4'},
        {id: 5, label: 'Node 5'}
    ];

    // create an array with edges
    var edges = [
        {from: 1, to: 2},
        {from: 1, to: 3},
        {from: 2, to: 4},
        {from: 2, to: 5}
    ];

    // create a graph
    var container = document.getElementById('mygraph');
    var data= {
        nodes: nodes,
        edges: edges,
    };
    var options = {
        width: '400px',
        height: '400px'
    };
    var graph = new vis.Graph(container, data, options);
</script>

</body>
</html>

Loading

Install or download the vis.js library. in a subfolder of your project. Include the library script in the head of your html code: 

<script type="text/javascript" src="vis/vis.js"></script>
The constructor of the Graph is vis.Graph. 
var graph = new vis.Graph(container, data, options);
The constructor accepts three parameters:

Data Format

The data parameter of the Graph constructor is an object which can contain different types of data. The following properties are supported in the data object:

Nodes

Nodes typically have an id and label. A node must contain at least a property id. Nodes can have extra properties, used to define the shape and style of the nodes.

A JavaScript Array with nodes is constructed like: 

var nodes = [
    {
        id: 1,
        label: 'Node 1'
    },
    // ... more nodes
];

Nodes support the following properties:

Name Type Required Description
backgroundColor String "#97C2FC" Background color for the node.
borderColor String "#2B7CE9" Border color for the node.
group Number | String no A group number or name. The type can be number, string, or an other type. All nodes with the same group get the same color schema.
fontColor String "black" Font color for label in the node.
fontFace String "sans" Font face for label in the node, for example "verdana" or "arial".
fontSize Number 14 Font size in pixels for label in the node.
highlightColor String "#D2E5FF" Background color of the node when selected.
id Number | String yes A unique id for this node. Nodes may not have duplicate id's. Id's do not need to be consecutive. An id is normally a number, but may be any type.
image string no Url of an image. Only applicable when the shape of the node is image.
radius number no Radius for the node. Applicable for all shapes except rect, circle, and database. The value of radius will override a value in property value.
shape string no Define the shape for the node. Choose from rect (default), circle, database, image, label, dot, star, triangle, triangleDown, and square.

In case of image, a property with name image must be provided, containing image urls.

The shapes dot, star, triangle, triangleDown, and square, are scalable. The size is determined by the properties radius or value.

When a property label is provided, this label will be displayed inside the shape in case of shapes rect, circle, and database. For all other shapes, the label will be displayed right below the shape.
label string no Text label to be displayed in the node or under the image of the node. Multiple lines can be separated by a newline character \n .
title string no Title to be displayed when the user hovers over the node. The title can contain HTML code.
value number no A value for the node. The radius of the nodes will be scaled automatically from minimum to maximum value. Only applicable when the shape of the node is dot. If a radius is provided for the node too, it will override the radius calculated from the value.
x number no Horizontal position in pixels. The horizontal position of the node will be fixed. The vertical position y may remain undefined.
y number no Vertical position in pixels. The vertical position of the node will be fixed. The horizontal position x may remain undefined.

Edges

Edges are connections between nodes. An edge must at least contain properties from and to, both referring to the id of a node. Edges can have extra properties, used to define the type and style.

A JavaScript Array with edges is constructed as: 

var edges = [
    {
        from: 1,
        to: 3
    },
    // ... more edges
];

Edges support the following properties:

Name Type Required Description
altdashlength number no Length of the alternated dash in pixels on a dashed line. Specifying altdashlength allows for creating a dashed line with a dash-dot style, for example when dashlength=10 and altdashlength=5. See also the option dashlength. Only applicable when the line style is dash-line.
color string no A HTML color for the edge.
dashlength number no Length of a dash in pixels on a dashed line. Only applicable when the line style is dash-line.
dashgap number no Length of a gap in pixels on a dashed line. Only applicable when the line style is dash-line.
fontColor String "black" Font color for the text label of the edge. Only applicable when property label is defined.
fontFace String "sans" Font face for the text label of the edge, for example "verdana" or "arial". Only applicable when property label is defined.
fontSize Number 14 Font size in pixels for the text label of the edge. Only applicable when property label is defined.
from Number | String yes The id of a node where the edge starts. The type must correspond with the type of the node id's. This is normally a number, but can be any type.
length number no The length of the edge in pixels.
style string no Define a line style for the edge. Choose from line (default), arrow, arrow-end, or dash-line.
label string no Text label to be displayed halfway the edge.
title string no Title to be displayed when the user hovers over the edge. The title can contain HTML code.
to Number | String yes The id of a node where the edge ends. The type must correspond with the type of the node id's. This is normally a number, but can be any type.
value number no A value for the edge. The width of the edges will be scaled automatically from minimum to maximum value. If a width is provided for the edge too, it will override the width calculated from the value.
width number no Width of the line in pixels. The width will override a specified value, if a value is specified too.

DOT language

Graph supports data in the DOT language. To provide data in the DOT language, the data object must contain a property dot with a String containing the data.

Example usage: 

// provide data in the DOT language
var data = {
    dot: 'digraph {1 -> 1 -> 2; 2 -> 3; 2 -- 4; 2 -> 1 }'
};

// create a graph
var graph = new vis.Graph(container, data);

Configuration Options

Options can be used to customize the graph. Options are defined as a JSON object. All options are optional. 

var options = {
    width:  '100%',
    height: '400px',
    edges: {
        color: 'red',
        width: 2
    }
};

The following options are available.

Name Type Default Description
backgroundColor String or Object "white" The background color for the main area of the chart. Can be either a simple HTML color string, for example: 'red' or '#00cc00', or an object with optional properties stroke, strokeWidth, and fill.
backgroundColor.stroke String "#666" The color of the chart border, as an HTML color string.
backgroundColor.strokeWidth Number 1 The border width, in pixels.
backgroundColor.fill String "white" The chart fill color, as an HTML color string.
groups Object none It is possible to specify custom styles for groups. Each node assigned a group gets the specified style. See Groups for an overview of the available styles and an example.
height String "400px" The height of the graph in pixels or as a percentage.
edges.altdashlength number none Length of the alternated dash in pixels on a dashed line. Specifying altdashlength allows for creating a dashed line with a dash-dot style, for example when dashlength=10 and altdashlength=5. See also the option dashlength. Only applicable when the line style is dash-line.
edges.color String "#2B7CE9" The default color of a edge.
edges.dashlength number 10 Length of a dash in pixels on a dashed line. Only applicable when the line style is dash-line.
edges.dashgap number 5 Length of a gap in pixels on a dashed line. Only applicable when the line style is dash-line.
edges.length Number 100 The default length of a edge.
edges.style String "line" The default style of a edge. Choose from line (default), arrow, arrow-end, dash-line.
edges.width Number 1 The default width of a edge.
nodes.borderColor String "#2B7CE9" Default border color of the nodes
nodes.backgroundColor String "#97C2FC" Default background color of the nodes
nodes.highlightColor String "#D2E5FF" Default background color of the node when the node is selected.
nodes.fontColor String "black" Default font color for the text label in the nodes.
nodes.fontFace String "sans" Default font face for the text label in the nodes, for example "verdana" or "arial".
nodes.fontSize Number 14 Default font size in pixels for the text label in the nodes.
nodes.group String none Default group for the nodes.
nodes.image String none Default image url for the nodes. only applicable with shape image.
nodes.widthMin Number 16 The minimum width for a scaled image. Only applicable with shape image.
nodes.widthMax Number 64 The maximum width for a scaled image. Only applicable with shape image.
nodes.shape String "rect" The default shape for all nodes. Choose from rect (default), circle, database, image, label, dot. This shape can be overridden by a group shape, or by a shape of an individual node.
nodes.radius Number 5 The default radius for a node. Only applicable with shape dot.
nodes.radiusMin Number 5 The minimum radius for a scaled node. Only applicable with shape dot.
nodes.radiusMax Number 20 The maximum radius for a scaled node. Only applicable with shape dot.
selectable Boolean true If true, nodes in the graph can be selected by clicking them, or by keeping the Shift key down and dragging a selection area around them. When the Ctrl key is down, the new selection is appended to the previous selection. If not, the new selection replaces the previous selection.
stabilize Boolean true If true, the graph is stabilized before displaying it. If false, the nodes move to a stabe position visibly in an animated way.
width String "400px" The width of the graph in pixels or as a percentage.

Groups

It is possible to specify custom styles for groups of nodes. Each node having assigned to this group gets the specified style. The options groups is an object containing one or multiple groups, identified by a unique string, the groupname.

A group can have the following styles: 

var options = {
    // ...

    groups: {
        mygroup: {
            shape: 'circle',
            borderColor: 'black',
            backgroundColor: 'white',
            fontColor: 'red',
            fontSize: 18,
            highlightColor: 'yellow'
        }
        // add more groups here
    }
};

var nodes = [
    {id: 1, label: 'Node 1'},                    // will get the default style
    {id: 2, label: 'Node 2', group: 'mygroup'},  // will get the style from 'mygroup'
    // ... more nodes
];

The following styles are available for groups:

Name Type Default Description
borderColor String "#2B7CE9" Border color of the node
backgroundColor String "#97C2FC" Background color of the node
highlightColor String "#D2E5FF" Background color of the node when the node is selected.
image String none Default image for the nodes. Only applicable in combination with shape image.
fontColor String "black" Font color of the node.
fontFace String "sans" Font name of the node, for example "verdana" or "arial".
fontSize Number 14 Font size for the node in pixels.
shape String "rect" Choose from rect (default), circle, database, image, label, dot. In case of image, a property with name image must be provided, containing image urls.
radius Number 5 Default radius for the node. Only applicable in combination with shapes rect and dot.

Methods

Graph supports the following methods.

Method Return Type Description
setData(data) none Loads data. Parameter data is an object containing nodes, edges, and options. Parameters nodes, edges are an Array. Options is a name-value map and is optional.
setOptions(options) none Set options for the graph. The available options are described in the section Configuration Options.
getSelection() Array of selection elements Standard getSelection() implementation. Returns an array with one or multiple selections. Each selection contains the property row. The selections are not ordered.
redraw() none Redraw the graph. Useful when the layout of the webpage changed.
setSelection(selection) none Standard setSelection(selection) implementation. selection is an array with selection elements. The visualization accepts one or multiple selection elements, which must have the property row. Example usage: graph.setSelection([{"row": 3}]);.
setSize(width, height) none Parameters width and height are strings, containing a new size for the visualization. Size can be provided in pixels or in percentages.

Events

Graph fires events after one or multiple nodes are selected. The event can be catched by creating a listener.

Here an example on how to catch a select event. 

function onselect() {
    var sel = graph.getSelection();

    var info = 'selected row(s): ';
    for (var i = 0; i < sel.length; i++) {
        info += sel[i].row + ' ';
    }

    alert(info);
}

vis.events.addListener(graph, 'select', onselect);

The following events are available.

name Description Properties
select Fired after the user selects or unselects a node by clicking it, or when selecting a number of nodes by dragging a selection area around them. Not fired when the method setSelection is executed. The corresponding rows in the Array are selected.
The selected rows can be retrieved via the method getSelection. 		none

Data Policy

All code and data are processed and rendered in the browser. No data is sent to any server.