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 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, text: 'Node 1'},
            {id: 2, text: 'Node 2'},
            {id: 3, text: 'Node 3'},
            {id: 4, text: 'Node 4'},
            {id: 5, text: '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}
        ];

        // specify options
        var options = {
            width: '400px',
            height: '400px'
        };

        // create a graph
        var graph = new vis.Graph(document.getElementById('mygraph'));

        // draw the graph with the created data and options
        graph.draw(nodes, edges, 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 class name of the Graph is vis.Graph 
var graph = new vis.Graph(container);
After being loaded, the graph can be drawn via the function draw(), provided with data and options. 
graph.draw(nodes, edges, packages, options);
where nodes, edges, and packages are an Array, and options is a name-value map in the JSON format. Both edges and packages are optional.

Data Format

Graph accepts the following data

Nodes

The node array is required for the graph visualization. The array must contain at least a property id. The array can have extra properties, used to define the type and style of individual nodes.

A JavaScript Array with nodes is constructed like: 

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

The node properties are defined as:

Name Type Required Description
action string no By specifying action, a node can be created, updated, or deleted. This is useful in combination with timestamp to animate history, or for dynamically updating the graph. Available values are: create, update (default), or delete.
backgroundColor String "#97C2FC" Background color for the node.
borderColor String "#2B7CE9" Border color for the node.
group * 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 text in the node.
fontFace String "sans" Font face for text in the node, for example "verdana" or "arial".
fontSize Number 14 Font size in pixels for text in the node.
highlightColor String "#D2E5FF" Background color of the node when selected.
id * 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 style of the node is image.
radius number no Radius for the node. Applicable for all styles except rect, circle, and database. The value of radius will override a value in property value.
style string no Define the shape for the node. Choose from rect (default), circle, database, image, text, 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 text is provided, this text will be displayed inside the shape in case of styles rect, circle, and database. For all other shapes, the text will be displayed right below the shape.
text string no Text to be displayed in the node or under the image of the node. Multiple lines can be separated by a newline character \n .
timestamp Date | Number no Timestamp used for filtering nodes when animating. See section Animation for more information.
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 style 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

The array with edges must at least contain properties from and to. The array can have extra properties, used to define the type and style of individual edges.

A JavaScript Array with edges is constructed as: 

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

The edge properties are defined as:

Name Type Required Description
action string no By specifying action, a link can be created, updated, or deleted. This is useful in combination with timestamp to animate history, or for dynamically updating the graph. An action on a link can only be used when the link has an id. Available values are: create (default), update, or delete.
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 link.
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 link. Only applicable when "text" is defined.
fontFace String "sans" Font face for the text label of the link, for example "verdana" or "arial". Only applicable when "text" is defined.
fontSize Number 14 Font size in pixels for the text label of the link. Only applicable when "text" is defined.
from * yes The id of a node where the link 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 link in pixels.
style string no Define a drawing style for the link. Choose from line (default), arrow, arrow-end, moving-arrows, or dash-line.
text string no Text to be displayed halfway the link.
timestamp Date | Number no Timestamp used for filtering edges when animating. See section Animation for more information.
title string no Title to be displayed when the user hovers over the link. The title can contain HTML code.
to * yes The id of a node where the link 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 link. The width of the edges will be scaled automatically from minimum to maximum value. If a width is provided for the link 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.

Packages

The array with packages must at least contain properties from and to. The array can have extra properties, used to define the type and style of individual packages.

There are two types of packages:

A JavaScript Array with packages is constructed as: 

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

The package properties are defined as:

Name Type Required Description
action string no By specifying action, a package can be created or deleted. Available values are: create (default), update, or delete. When a package is created with an id which already exists, the existing package will be updated. The action property can be used in combination with timestamp to animate history.
color string no A HTML color for the package.
duration number no Duration in seconds the animation of the package moving from start to end node. Only applicable when progress is not provided.
from * yes The id of a node where the link starts. The type must correspond with the type of the node id's. This is normally a number, but can be any type.
id * yes A unique id for the package. Packages cannot have duplicate id's. An id is required for packages with manually defined progress, in order to be able to update or delete them lateron.
image string no Url of an image. Only applicable when style is image.
progress number no A number between 0 and 1 which determines the progress of the package between the start and end node. If progress is defined, the package must also have an id defined.
radius number no The radius of the package. Only applicable when style is dot.
style string no Define a drawing style for the package. Choose from dot (default), image, star, triangle, triangleDown, or square. In case of an image, a property with image url must be provided in the package.
title string no Title to be displayed when the user hovers over the package. The title can contain HTML code.
to * yes The id of a node where the link ends. The type must correspond with the type of the node id's. This is normally a number, but can be any type.
timestamp Date or number no The time on which this package is added or removed. Only applicable in combination with the property action. When timestamp is provided, a slider with start and stop button is created to enable playing history.
value number no A value for the package. The radius of the packages will be scaled automatically from minimum to maximum value. Only applicable when the style of the node is dot. If a parameter radius is provided for the node too, this will override the radius calculated from the value.

Data Import

Graph contains parser to import data in the DOT language. There following methods are available:

Method Return Type Description
vis.Graph.util.parseDOT(data) Object Parse a string containing data in DOT language into a JSON object. The returned object contains two arrays, nodes, edges, containing the parsed nodes and edges.
vis.Graph.util.DOTToGraph(data) Object Convert a string containing a graph in DOT language into a map containing with nodes and edges in the format of Graph. The returned object contains parameters nodes, edges, and options, which can be used directly to draw a graph using draw(nodes, edges, options).

Example usage: 

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

    // parse data in DOT-notation
    var dot = 'digraph {1 -> 1 -> 2; 2 -> 3; 2 -- 4; 2 -> 1 }';
    data = vis.Graph.util.DOTToGraph(dot);

    // draw the data
    graph.draw(data.nodes, data.edges, data.options);

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 link.
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 link.
edges.style String "line" The default style of a link. Choose from line (default), arrow, moving-arrows, dash-line.
edges.width Number 1 The default width of a link.
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 text in the nodes.
nodes.fontFace String "sans" Default font face for text in the nodes, for example "verdana" or "arial".
nodes.fontSize Number 14 Default font size in pixels for text 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 style image.
nodes.widthMin Number 16 The minimum width for a scaled image. Only applicable with style image.
nodes.widthMax Number 64 The maximum width for a scaled image. Only applicable with style image.
nodes.style String "rect" The default style for all nodes. Choose from rect (default), circle, database, image, text, dot. This style can be overridden by a group style, or by a style of an individual node.
nodes.radius Number 5 The default radius for a node. Only applicable with style dot.
nodes.radiusMin Number 5 The minimum radius for a scaled node. Only applicable with style dot.
nodes.radiusMax Number 20 The maximum radius for a scaled node. Only applicable with style dot.
packages.color String "#2B7CE9" Default color for all packages
packages.duration Number 1.0 Default duration of animated packages in seconds.
packages.image String none Default image for all packages. Style of the packages must be set to image
packages.widthMin Number 16 The minimum width for a scaled package. Only applicable with style image.
packages.widthMax Number 64 The maximum width for a scaled package. Only applicable with style image.
packages.radius Number 5 Default radius for all packages.
packages.radiusMin Number 5 The minimum radius for a scaled package. Only applicable with style dot.
packages.radiusMax Number 20 The maximum radius for a scaled package. Only applicable with style dot.
packages.style String "dot" Default style for all packages. Choose from dot (default) or image. In case of an image, a property with image url must be provided in the package.
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': {
      'style': 'circle',
      'borderColor': 'black',
      'backgroundColor': 'white',
      'fontColor': 'red',
      'fontSize': 18,
      'highlightColor': 'yellow'
    }
    // add more groups here
  }
};

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

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 style 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.
style String "rect" Choose from rect (default), circle, database, image, text, 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 styles rect and dot.

Dynamic Data

The Graph is normally rendered using the method draw. The graph can handle dynamic data in two ways:

Animation

Historical data can be animated over time. To create an animation, the data sets with nodes, edges, and packages must have a property timestamp, and has a property action describing the change (create, update, or delete). The Graph will automatically create an animation which runs from the earliest to the latest encountered timestamp. When the Graph is rendered at a certain timestamp, all elements with a timestamp older than the current time will be rendered, and all elements without a timestamp.

The animation state and speed can be manipulated using methods animationSetAcceleration, animationSetDuration, animationSetFramerate, animationStart, and animationStop.

The following package table shows how to change the state of a package over time: 

var packageTable = new google.visualization.DataTable();
packageTable.addColumn('number', 'id');
packageTable.addColumn('number', 'from');
packageTable.addColumn('number', 'to');
packageTable.addColumn('string', 'action');
packageTable.addColumn('string', 'title');
packageTable.addColumn('number', 'progress');
packageTable.addColumn('datetime', 'timestamp');

// package with id 7 moved over time from node 1 to node 2
//                   id, from, to, action,  title,              progress,  timestamp
packageTable.addRow([7,  1,    2, 'create', 'Copy data [0%]',   0.00,      new Date(2012,6,4,14,0,0)]);
packageTable.addRow([7,  1,    2, 'update', 'Copy data [10%]',  0.10,      new Date(2012,6,4,14,10,0)]);
packageTable.addRow([7,  1,    2, 'update', 'Copy data [20%]',  0.20,      new Date(2012,6,4,14,15,0)]);
packageTable.addRow([7,  1,    2, 'update', 'Copy data [50%]',  0.50,      new Date(2012,6,4,14,20,0)]);
packageTable.addRow([7,  1,    2, 'update', 'Copy data [80%]',  0.80,      new Date(2012,6,4,14,30,0)]);
packageTable.addRow([7,  1,    2, 'update', 'Copy data [100%]', 1.00,      new Date(2012,6,4,14,35,0)]);
packageTable.addRow([7,  1,    2, 'delete', undefined,          undefined, new Date(2012,6,4,14,40,0)]);

Changeset

The data of a rendered Graph can be changed dynamically. Data can be updated by appending a changeset to the Graph using methods addNodes, addEdges, and addPackages. The appended data can contain new nodes, edges, and packages, but can also adjust existing elements. For example, the title of a Node or the width of a link can be updated.

The changeset is a regular Array like used The action property describes one of the following changes

Methods

Graph supports the following methods.

Method Return Type Description
addEdges(edges) none Dynamically appends edges to the graph. Parameter edges contains an Array. A link can be created, updated, or deleted by specifying the property action and choose a value create, update, or delete.
addNodes(nodes) none Dynamically adds nodes to the graph. Parameter nodes contains an Array. A node can be created, updated, or deleted by specifying the property action and choose a value create, update, or delete.
addPackages(packages) none Dynamically appends packages to the graph. Parameter packages contains an Array. A package can be created, updated, or deleted by specifying the property action and choose a value create, update, or delete.
animationSetAcceleration(acceleration) none Set the time acceleration for animation of history. Only applicable when packages with a timestamp are available. When acceleration is 1, history is played in real time. And for example acceleration of 10 will play history then times the speed of real time.
animationSetDuration(duration) none Duration of the animation in seconds. Only applicable when packages with a timestamp are available. The animation speed is scaled such that the total duration of playing the history equals the set duration.
animationSetFramerate(framerate) none Set the framerate in frames per second for animation of history. Only applicable when packages with a timestamp are available.
animationStart() none Start animation of history. Only applicable when packages with a timestamp are available.
animationStop() none Stop animation of history. Only applicable when packages with a timestamp are available.
draw(nodes, edges, packages, options) none Loads data, sets the provided options, and draws the graph. Parameters nodes, edges, and packages are an Array, and options is a name-value map in the JSON format. Both edges and packages are optional and can be left undefined.
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 after the camera position is changed externally, when data is changed, or 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.
start() none Start animation. Only applicable when there are animated edges or nodes, or when the nodes are not yet moved to a stable position.
stop() none Stop animation. Only applicable when there are animated edges or nodes.

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
ready The graph is loaded and ready for external method calls. If you want to interact with the graph, and call methods after you draw it, you should set up a listener for this event before you call the draw method, and call them only after the event was fired. none

Data Policy

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