Graph documentation

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

Overview
Example
Loading
Data Format
- Nodes
- Edges
- DOT language
Configuration Options
Methods
Events
Data Policy

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:

container is the DOM element in which to create the graph.
data is an Object containing properties nodes and edges, which both contain an array with objects. Optionally, data may contain an options object. The parameter data is optional, data can also be set using the method setData. Section Data Format describes the data object.
options is an optional Object containing a name-value map with options. Options can also be set using the method setOptions. Section Configuration Options describes the available options.

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:

A property pair nodes and edges, both containing an Array with objects. The data formats are described in the sections Nodes and Edges. Example:
```
var data = {
    nodes: [...],
    edges: [...]
};
```
A property dot, containing a string with data in the DOT language. DOT support is described in section DOT_language. Example:
```
var data = {
    dot: '...'
};
```
A property options, containing an object with global options. Options can be provided as third parameter in the graph constructor as well. Section Configuration Options describes the available options.

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
color	String \| Object	no	Color for the node.
color.background	String	no	Background color for the node.
color.border	String	no	Border color for the node.
color.highlight	String \| Object	no	Color of the node when selected.
color.highlight.background	String	no	Background color of the node when selected.
color.highlight.border	String	no	Border color of the node when selected.
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	no	Font color for label in the node.
fontFace	String	no	Font face for label in the node, for example "verdana" or "arial".
fontSize	Number	no	Font size in pixels for label in the node.
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 `box`, `circle`, `ellipse` and `database`. The value of `radius` will override a value in property `value`.
shape	string	no	Define the shape for the node. Choose from `ellipse` (default), `circle`, `box`, `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 `box`, `circle`, `ellipse`, 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
color	string	no	A HTML color for the edge.
dash	Object	no	Object containing properties for dashed lines. Available properties: `length`, `gap`, `altLength`.
dash.altLength	number	no	Length of the alternated dash in pixels on a dashed line. Specifying `dash.altLength` allows for creating a dashed line with a dash-dot style, for example when `dash.length=10` and `dash.altLength=5`. See also the option `dahs.length`. Only applicable when the line style is `dash-line`.
dash.length	number	no	Length of a dash in pixels on a dashed line. Only applicable when the line style is `dash-line`.
dash.gap	number	no	Length of a gap in pixels on a dashed line. Only applicable when the line style is `dash-line`.
fontColor	String	no	Font color for the text label of the edge. Only applicable when property `label` is defined.
fontFace	String	no	Font face for the text label of the edge, for example "verdana" or "arial". Only applicable when property `label` is defined.
fontSize	Number	no	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-center`, 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
edges.color	String	"#2B7CE9"	The default color of a edge.
edges.dash	Object	Object	Object containing default properties for dashed lines. Available properties: `length`, `gap`, `altLength`.
edges.dash.altLength	number	none	Default length of the alternated dash in pixels on a dashed line. Specifying `dash.altLength` allows for creating a dashed line with a dash-dot style, for example when `dash.length=10` and `dash.altLength=5`. See also the option `dahs.length`. Only applicable when the line style is `dash-line`.
edges.dash.length	number	10	Default length of a dash in pixels on a dashed line. Only applicable when the line style is `dash-line`.
edges.dash.gap	number	5	Default 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-center`, `dash-line`.
edges.width	Number	1	The default width of a edge.
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.
nodes.color	String \| Object	Object	Default color of the nodes. When color is a string, the color is applied to both background as well as the border of the node.
nodes.color.background	String	"#97C2FC"	Default background color of the nodes
nodes.color.border	String	"#2B7CE9"	Default border color of the nodes
nodes.color.highlight	String \| Object	Object	Default color of the node when the node is selected. Applied to both border and background of the node.
nodes.color.highlight.background	String	"#D2E5FF"	Default background color of the node when selected.
nodes.color.highlight.border	String	"#2B7CE9"	Default border color of the node when 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	"ellipse"	The default shape for all nodes. Choose from `ellipse` (default), `circle`, `box`, `database`, `image`, `label`, `dot`, `star`, `triangle`, `triangleDown`, and `square`. 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',
            color: {
                border: 'black',
                background: 'white',
                highlight: {
                    border: 'yellow',
                    background: 'orange'
                }
            }
            fontColor: 'red',
            fontSize: 18
        }
        // 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
color	String \| Object	Object	Color of the node
color.border	String	"#2B7CE9"	Border color of the node
color.background	String	"#97C2FC"	Background color of the node
color.highlight	String	"#D2E5FF"	Color of the node when selected.
color.highlight.background	String	"#D2E5FF"	Background color of the node when selected.
color.highlight.border	String	"#D2E5FF"	Border color of the node when 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	"ellipse"	Choose from `ellipse` (default), `circle`, `box`, `database`, `image`, `label`, `dot`, `star`, `triangle`, `triangleDown`, and `square`. 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 `box` 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 ids	Returns an array with the ids of the selected nodes. Returns an empty array if no nodes are selected. The selections are not ordered.
redraw()	none	Redraw the graph. Useful when the layout of the webpage changed.
setSelection(selection)	none	Select nodes. `selection` is an array with ids of nodes to be selected. The array `selection` can contain zero or multiple ids. Example usage: `graph.setSelection([3, 5]);` will select nodes with id 3 and 5.
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() {
    alert('selected nodes: ' + graph.getSelection());
}

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 ids of the selected nodes 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.