Graph documentation

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 thousand nodes and edges. To handle a larger amount of nodes, Graph has clustering support.

Every dataset is different. Nodes can have different sizes based on content, interconnectivity can be high or low etc. Because of this, graph has a special option that the user can use to explore which settings may be good for you. Use configurePhysics as described in the Physics section or by example 25.

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

Contents

Example

Here a basic graph example. Note that unlike the Timeline, the Graph does not need the vis.css file.

More examples can be found in the examples directory. 

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

  <script type="text/javascript" src="../../dist/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/dist/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
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.
allowedToMoveX Boolean false If allowedToMoveX is false, then the node will not move from its supplied position. If an X position has been supplied, it is fixed in the X-direction. If no X value has been supplied, this argument will not do anything.
allowedToMoveY Boolean false If allowedToMoveY is false, then the node will not move from its supplied position. If an Y position has been supplied, it is fixed in the Y-direction. If no Y value has been supplied, this argument will not do anything.
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.
mass number 1 When using the Barnes Hut simulation method (which is selected by default), the mass of a node determines the gravitational repulsion during the simulation. Higher mass will push other nodes further away.
level number -1 This level is used in the hierarchical layout. If this is not selected, the level does not do anything.
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 | function no Title to be displayed when the user hovers over the node. The title can contain HTML code. If using a function, returning undefined will prevent the tooltip from being displayed.
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
arrowScaleFactor Number no If you are using arrows, this will scale the arrow. Values < 1 give smaller arrows, > 1 larger arrows. Default: 1.
color String | Object no Color for the edge.
color.color String no Color of the edge when not selected.
color.highlight String no Color of the edge when selected.
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.
fontFill string no Font fill for the background color of 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.
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.
length number physics.[method].springLength The resting length of the edge when modeled as a spring. By default the springLength determined by the physics is used. By using this setting you can make certain edges have different resting lengths.
title string | function no Title to be displayed when the user hovers over the edge. The title can contain HTML code. If using a function, returning undefined will prevent the tooltip from being displayed.
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
physics Object none Configuration of the physics system governing the simulation of the nodes and edges. Barnes-Hut nBody simulation is used by default. See section Physics for an overview of the available options.
configurePhysics Boolean false Enabling this setting will create a physics configuration div above the graph. You can use this to fine tune the physics system to suit your needs. Because of the many possible configurations, there is not a one-size-fits-all setting. By using this tool, you can adapt the physics to your dataset.
dataManipulation Object none Settings for manipulating the Dataset. See section Data manipulation for an overview of the available options.
clustering Object none Clustering configuration. Clustering is turned off by default. See section Clustering for an overview of the available options.
edges Object none Configuration options applied to all edges. See section Edges configuration for an overview of the available options.
freezeForStabilization Boolean false With the advent of the storePosition() function, the positions of the nodes can be saved after they are stabilized. The smoothCurves require support nodes and those positions are not stored. In order to speed up the initialization of the graph by using storePosition() and loading the nodes with the stored positions, the freezeForStabilization option freezes all nodes that have been supplied with an x and y position in place during the stabilization. That way only the support nodes for the smooth curves have to stabilize, greatly speeding up the stabilization process with cached positions.
groups Object none It is possible to specify custom styles for groups. Each node assigned a group gets the specified style. See Groups configuration for an overview of the available styles and an example.
height String "400px" The height of the graph in pixels or as a percentage.
keyboard Object none Configuration options for shortcuts keys. Sortcut keys are turned off by default. See section Keyboard navigation for an overview of the available options.
navigation Object none Configuration options for the navigation controls. See section Navigation controls for an overview of the available options.
nodes Object none Configuration options applied to all nodes. See section Nodes configuration for an overview of the available options.
smoothCurves Boolean true If true, edges are drawn as smooth curves. This is more computationally intensive since the edge now is a quadratic Bezier curve with control points on both nodes and an invisible node in the center of the edge. This support node is also handed by the physics simulation.
selectable Boolean true If true, nodes in the graph can be selected by clicking them. Long press can be used to select multiple nodes.
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.
stabilizationIterations Number 1000 If stabilize is set to true, this number is the (maximum) amount of physics steps the stabilization process takes before showing the result. If your simulation takes too long to stabilize, this number can be reduced. On the other hand, if your graph is not stabilized after loading, this number can be increased.
width String "400px" The width of the graph in pixels or as a percentage.

Nodes configuration

Nodes can be configured with different styles and shapes. To configure nodes, provide an object named nodes in the options for the Graph.

For example to give the nodes a custom color, shape, and size: 

var options = {
  // ...
  nodes: {
    color: {
      background: 'white',
      border: 'red',
      highlight: {
        background: 'pink',
        border: 'red'
      }
    },
    shape: 'star',
    radius: 24
  }
};

The following options are available for nodes. These options must be created inside an object nodes in the graphs options object.

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.
color.background String "#97C2FC" Default background color of the nodes
color.border String "#2B7CE9" Default border color of the nodes
color.highlight String | Object Object Default color of the node when the node is selected. In case of a string, the color is applied to both border and background of the node.
color.highlight.background String "#D2E5FF" Default background color of the node when selected.
color.highlight.border String "#2B7CE9" Default border color of the node when selected.
allowedToMoveX Boolean false If allowedToMoveX is false, then the node will not move from its supplied position. If an X position has been supplied, it is fixed in the X-direction. If no X value has been supplied, this argument will not do anything.
allowedToMoveY Boolean false If allowedToMoveY is false, then the node will not move from its supplied position. If an Y position has been supplied, it is fixed in the Y-direction. If no Y value has been supplied, this argument will not do anything.
fontColor String "black" Default font color for the text label in the nodes.
fontFace String "sans" Default font face for the text label in the nodes, for example "verdana" or "arial".
fontSize Number 14 Default font size in pixels for the text label in the nodes.
group String none Default group for the nodes.
image String none Default image url for the nodes. only applicable to shape image.
mass number 1 When using the Barnes Hut simulation method (which is selected by default), the mass of a node determines the gravitational repulsion during the simulation. Higher mass will push other nodes further away.
level number -1 This level is used in the hierarchical layout. If this is not selected, the level does not do anything.
widthMin Number 16 The minimum width for a scaled image. Only applicable to shape image.
widthMax Number 64 The maximum width for a scaled image. Only applicable to shape image.
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.
radius Number 5 The default radius for a node. Only applicable to shapes dot, star, triangle, triangleDown, and square.
radiusMin Number 5 The minimum radius for a scaled node. Only applicable to shapes dot, star, triangle, triangleDown, and square.
radiusMax Number 20 The maximum radius for a scaled node. Only applicable to shapes dot, star, triangle, triangleDown, and square.

Edges configuration

Edges can be configured with different length and styling. To configure edges, provide an object named edges in the options for the Graph.

For example to set the width of all edges to 2 pixels and give them a red color: 

var options = {
  // ...
  edges: {
    color: 'red',
    width: 2
  }
};

The following options are available for edges. These options must be created inside an object edges in the graphs options object.

Name Type Default Description
arrowScaleFactor Number 1 If you are using arrows, this will scale the arrow. Values < 1 give smaller arrows, > 1 larger arrows. Default: 1.
color String | Object Object Colors of the edge. This object contains both colors for the selected and unselected state.
color.color String "#848484" Color of the edge when not selected.
color.highlight String "#848484" Color of the edge when selected.
dash Object Object Object containing default properties for dashed lines. Available properties: length, gap, altLength.
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.
dash.length number 10 Default length of a dash in pixels on a dashed line. Only applicable when the line style is dash-line.
dash.gap number 5 Default length of a gap in pixels on a dashed line. Only applicable when the line style is dash-line.
length number physics.[method].springLength The resting length of the edge when modeled as a spring. By default the springLength determined by the physics is used. By using this setting you can make certain edges have different resting lengths.
style String "line" The default style of a edge. Choose from line (default), arrow, arrow-center, dash-line.
width Number 1 The default width of a edge.

Groups configuration

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 | Object "#D2E5FF" Default color of the node when the node is selected. In case of a string, the color is applied to both border and background of the node.
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.

Physics

The original simulation method was based on particel physics with a repulsion field (potential) around each node, and the edges were modelled as springs. The new system employed the Barnes-Hut gravitational simulation model. The edges are still modelled as springs. To unify the physics system, the damping, repulsion distance and edge length have been combined in an physics option. To retain good behaviour, both the old repulsion model and the Barnes-Hut model have their own parameters. If no options for the physics system are supplied, the Barnes-Hut method will be used with the default parameters. If you want to customize the physics system easily, you can use the configurePhysics option.

Note: if the behaviour of your graph is not the way you want it, use configurePhysics as described below or by example 25.

// These variables must be defined in an options object named physics.
// If a variable is not supplied, the default value is used.
var options = {
    physics: {
        barnesHut: {
            enabled: true,
            gravitationalConstant: -2000,
            centralGravity: 0.1,
            springLength: 95,
            springConstant: 0.04,
            damping: 0.09
        },
        repulsion: {
            centralGravity: 0.1,
            springLength: 50,
            springConstant: 0.05,
            nodeDistance: 100,
            damping: 0.09
        },
    }
barnesHut:
Name Type Default Description
enabled Boolean true This switches the Barnes-Hut simulation on or off. If it is turned off, the old repulsion model is used. Barnes-Hut is generally faster and yields better results.
gravitationalConstant Number -2000 This is the gravitational constand used to calculate the gravity forces. More information is available here.
centralGravity Number 0.1 The central gravity is a force that pulls all nodes to the center. This ensures independent groups do not float apart.
springLength Number 95 In the previous versions this was a property of the edges, called length. This is the length of the springs when they are at rest. During the simulation they will be streched by the gravitational fields. To greatly reduce the edge length, the gravitationalConstant has to be reduced as well.
springConstant Number 0.04 This is the spring constant used to calculate the spring forces based on Hooke′s Law. More information is available here.
damping Number 0.09 This is the damping constant. It is used to dissipate energy from the system to have it settle in an equilibrium. More information is available here.
repulsion:
Name Type Default Description
centralGravity Number 0.1 The central gravity is a force that pulls all nodes to the center. This ensures independent groups do not float apart.
springLength Number 50 In the previous versions this was a property of the edges, called length. This is the length of the springs when they are at rest. During the simulation they will be streched by the gravitational fields. To greatly reduce the edge length, the gravitationalConstant has to be reduced as well.
nodeDistance Number 100 This parameter is used to define the distance of influence of the repulsion field of the nodes. Below half this distance, the repulsion is maximal and beyond twice this distance the repulsion is zero.
springConstant Number 0.05 This is the spring constant used to calculate the spring forces based on Hooke′s Law. More information is available here.
damping Number 0.09 This is the damping constant. It is used to dissipate energy from the system to have it settle in an equilibrium. More information is available here.

Configuration:

Every dataset is different. Nodes can have different sizes based on content, interconnectivity can be high or low etc. Because of this, graph has a special option that the user can use to explore which settings may be good for him or her. This is ment to be used during the development phase when you are implementing vis.js. Once you have found settings you are happy with, you can supply them to graph using the physics options as described above. On start, the default settings will be loaded. Keep in mind that selecting the hierarchical simulation mode disables smooth curves. These will not be enabled again afterwards. 
var options = {
    configurePhysics:true
}

Data manipulation

By using the data manipulation feature of the graph you can dynamically create nodes, connect nodes with edges, edit nodes or delete nodes and edges. The toolbar is fully HTML and CSS so the user can style this to their preference. To control the behaviour of the data manipulation, users can insert custom functions into the data manipulation process. For example, an injected function can show an detailed pop-up when a user wants to add a node. In example 21, two functions have been injected into the add and edit functionality. This is described in more detail in the next subsection. To correctly display the manipulation icons, the vis.css file must be included. The user is free to alter or overload the CSS classes but without them the navigation icons are not visible. 

// These variables must be defined in an options object named dataManipulation.
// If a variable is not supplied, the default value is used.
var options = {
    dataManipulation: {
      enabled: false,
      initiallyVisible: false
    }
}
// OR to just load the module with default values:
var options: {
    dataManipulation: true
}
Name Type Default Description
enabled Boolean false Enabling or disabling of the data manipulation toolbar. If it is initially hidden, an edit button appears in the top left corner.
initiallyVisible Boolean false Initially hide or show the data manipulation toolbar.

Data manipulation: custom functionality

Users can insert custom functions into the add node, edit node, connect nodes, and delete selected operations. This is done by supplying them in the options. If the callback is NOT called, nothing happens. Example 21 has two working examples for the add and edit functions. The data the user is supplied with in these functions has been described in the code below. For the add data, you can add any and all options that are accepted for node creation as described above. The same goes for edit, however only the fields described in the code below contain information on the selected node. The callback for connect accepts any options that are used for edge creation. Only the callback for delete selected requires the same data structure that is supplied to the user.

If there is no injected function supplied for the edit operation, the button will not be shown in the toolbar. 

// If a variable is not supplied, the default value is used.
var options: {
    dataManipulation: true,
    onAdd: function(data,callback) {
        /** data = {id: random unique id,
        *           label: new,
        *           x: x position of click (canvas space),
        *           y: y position of click (canvas space),
        *           allowedToMoveX: true,
        *           allowedToMoveY: true
        *          };
        */
        var newData = {..}; // alter the data as you want.
                            // all fields normally accepted by a node can be used.
        callback(newData);  // call the callback to add a node.
    },
    onEdit: function(data,callback) {
        /** data = {id:...,
        *           label: ...,
        *           group: ...,
        *           shape: ...,
        *           color: {
        *             background:...,
        *             border:...,
        *             highlight: {
        *               background:...,
        *               border:...
        *             }
        *           }
        *          };
        */
        var newData = {..}; // alter the data as you want.
                            // all fields normally accepted by a node can be used.
        callback(newData);  // call the callback with the new data to edit the node.
    }
    onConnect: function(data,callback) {
        // data = {from: nodeId1, to: nodeId2};
        var newData = {..};      // check or alter data as you see fit.
        callback(newData);       // call the callback to connect the nodes.
    },
    onDelete: function(data,callback) {
        // data = {nodes: [selectedNodeIds], edges: [selectedEdgeIds]};
        var newData = {..}; // alter the data as you want.
                            // the same data structure is required.
        callback(newData);  // call the callback to delete the objects.
    }
};

Because the interface elements are CSS and HTML, the user will have to correct for size changes of the canvas. To facilitate this, a new event has been added called resize. A function can be bound to this event. This function is supplied with the new widht and height of the canvas. The CSS can then be updated accordingly. An code snippet from example 21 is shown below. 

graph.on("resize", function(params) {console.log(params.width,params.height)});

Clustering

The graph now supports dynamic clustering of nodes. This allows a user to view a very large dataset (> 50.000 nodes) without sacrificing performance. When loading a large dataset, the nodes are clustered initially (this may take a small while) to have a responsive visualization to work with. The clustering is both outside-in and inside-out. Outside-in means that nodes with only one connection will be contained, or clustered, in the node it is connected to. Inside-out clustering first determines which nodes are hubs. Hubs are defined as the nodes with the top 3% highest amount of connections (assuming normal distribution). These hubs then "grow", meaning they contain the nodes they are connected to within themselves. The edges that were connected to the nodes that are absorbed will be reconnected to the cluster.

A cluster is just a node that has references to the nodes and edges it contains. It has an internal counter to keep track of its size, which is then used to calculate the required forces. The contained nodes are removed from the global nodes index, greatly speeding up the system.

The clustering has the following user-configurable settings. The default values have been tested with the Graph examples and work well. The default state for clustering is off. 

// These variables must be defined in an options object named clustering.
// If a variable is not supplied, the default value is used.
var options = {
    clustering: {
      initialMaxNodes: 100,
      clusterThreshold:500,
      reduceToNodes:300,
      chainThreshold: 0.4,
      clusterEdgeThreshold: 20,
      sectorThreshold: 100,
      screenSizeThreshold: 0.2,
      fontSizeMultiplier:  4.0,
      maxFontSize: 1000,
      forceAmplification:  0.1,
      distanceAmplification: 0.1,
      edgeGrowth: 20,
      nodeScaling: {width:  1,
                    height: 1,
                    radius: 1},
      maxNodeSizeIncrements: 600,
      activeAreaBoxSize: 100,
      clusterLevelDifference: 2
    }
}
// OR to just load the module with default values:
var options: {
    clustering: true
}
Name Type Default Description
initialMaxNodes Number 100 If the initial amount of nodes is larger than this value, clustering starts until the total number of nodes is less than this value.
clusterThreshold Number 500 While zooming in and out, clusters can open up. Once there are more than absoluteMaxNumberOfNodes nodes, clustering starts until reduceToMaxNumberOfNodes nodes are left. This is done to ensure performance is continuously fluid.
reduceToNodes Number 300 While zooming in and out, clusters can open up. Once there are more than absoluteMaxNumberOfNodes nodes, clustering starts until reduceToMaxNumberOfNodes nodes are left. This is done to ensure performance is continiously fluid.
chainThreshold Number 0.4 Because of the clustering methods used, long chains of nodes can be formed. To reduce these chains, this threshold is used. A chainThreshold of 0.4 means that no more than 40% of all nodes are allowed to be a chain node (two connections). If there are more, they are clustered together.
clusterEdgeThreshold Number 20 This is the absolute edge length threshold in pixels. If the edge is smaller on screen (that means zooming out reduces this length) the node will be clustered. This is triggered when zooming out.
sectorThreshold Integer 50 If a cluster larger than sectorThreshold is opened, a seperate instance called a sector, will be created. All the simulation of nodes outside of this instance will be paused. This is to maintain performance and clarity when examining large clusters. A sector is collapsed when zooming out far enough. Also, when opening a cluster, if this cluster is smaller than this value, it is fully unpacked.
screenSizeThreshold Number 0.2 When zooming in, the clusters become bigger. A screenSizeThreshold of 0.2 means that if the width or height of this cluster becomes bigger than 20% of the width or height of the canvas, the cluster is opened. If a sector has been created, if the sector is smaller than 20%, we collapse this sector.
fontSizeMultiplier Number 4.0 This parameter denotes the increase in fontSize of the cluster when a single node is added to it.
maxFontSize Number 1000 This parameter denotes the largest allowed font size. If the font becomes too large, some browsers experience problems displaying this.
forceAmplification Number 0.6 This factor is used to calculate the increase of the repulsive force of a cluster. It is calculated by the following formula: repulsingForce *= 1 + (clusterSize * forceAmplification).
distanceAmplification Number 0.2 This factor is used to calculate the increase in effective range of the repulsive force of the cluster. A larger cluster has a longer range. It is calculated by the following formula: minDistance *= 1 + (clusterSize * distanceAmplification).
edgeGrowth Number 20 This factor determines the elongation of edges connected to a cluster.
nodeScaling.width Number 10 This factor determines how much the width of a cluster increases in pixels per added node.
nodeScaling.height Number 10 This factor determines how much the height of a cluster increases in pixels per added node.
nodeScaling.radius Number 10 This factor determines how much the radius of a cluster increases in pixels per added node.
maxNodeSizeIncrements Number 600 This limits the size clusters can grow to. The default value, 600, implies that if a cluster contains more than 600 nodes, it will no longer grow.
activeAreaBoxSize Number 100 Imagine a square with an edge length of activeAreaBoxSize pixels around your cursor. If a cluster is in this box as you zoom in, the cluster can be opened in a seperate sector. This is regardless of the zoom level.
clusterLevelDifference Number 2 At every clustering session, Graph will check if the difference between cluster levels is acceptable. When a cluster is formed when zooming out, that is one cluster level. If you zoom out further and it encompasses more nodes, that is another level. For example: If the highest level of your graph at any given time is 3, nodes that have not clustered or have clustered only once will join their neighbour with the lowest cluster level.

Graph has a menu with navigation controls, which is disabled by default. It can be configured with the following settings. To correctly display the navigation icons, the vis.css file must be included. The user is free to alter or overload the CSS classes but without them the navigation icons are not visible. 

// use of navigation controls
var options: {
  navigation: true
}

Keyboard navigation

The graph can be navigated using shortcut keys. The default state for the keyboard navigation is off. The predefined keys can be found in the example 20_navigation.html. 

// simple use of keyboard controls
var options: {
    keyboard: true
}

// advanced configuration for keyboard controls
var options: {
  keyboard: {
    speed: {
      x: 10,
      y: 10,
      zoom: 0.02
    }
  }
}
Name Type Default Description
speed.x Number 10 This defines the speed of the camera movement in the x direction when using the keyboard navigation.
speed.y Number 10 This defines the speed of the camera movement in the y direction when using the keyboard navigation.
speed.zoom Number 0.02 This defines the zoomspeed when using the keyboard navigation.

Hierarchical layout

The graph can be used to display nodes in a hierarchical way. This can be determined automatically, based on the amount of edges connected to each node, or defined by the user. If the user wants to manually determine the hierarchy, each node has to be supplied with a level (from 0 being heighest to n). The automatic method is shown in example 23 and the user-defined method is shown in example 24. This layout method does not support smooth curves or clustering. It automatically turns these features off. 

// simple use of the hierarchical layout
var options: {
    hierarchicalLayout: true
}

// advanced configuration for hierarchical layout
var options: {
    hierarchicalLayout: {
      enabled:false,
      levelSeparation: 150,
      nodeSpacing: 100,
      direction: "UD"
    }
}
// partial configuration automatically sets enabled to true
var options: {
    hierarchicalLayout: {
      nodeSpacing: 100,
      direction: "UD"
    }
}
Name Type Default Description
enabled Boolean false Enable or disable the hierarchical layout.
levelSeparation Number 150 This defines the space between levels (in the Y-direction, considering UP-DOWN direction).
nodeSpacing Number 100 This defines the space between nodes in the same level (in the X-direction, considering UP-DOWN direction). This is only relevant during the initial placing of nodes.
direction String UD This defines the direction the graph is drawn in. The supported directions are: Up-Down (UD), Down-Up (DU), Left-Right (LR) and Right-Left (RL). These need to be supplied by the acronyms in parentheses.

Localization

When using vis.js in other languages, one can use the localization option to overwrite the labels used in the data manipulation interface. 

var options: {
    labels:{
      add:"Add Node",
      edit:"Edit",
      link:"Add Link",
      del:"Delete selected",
      editNode:"Edit Node",
      back:"Back",
      addDescription:"Click in an empty space to place a new node.",
      linkDescription:"Click on a node and drag the edge to another
                       node to connect them.",
      addError:"The function for add does not support two arguments
                                                        (data,callback).",
      linkError:"The function for connect does not support two arguments
                                                        (data,callback).",
      editError:"The function for edit does not support two arguments
                                                        (data, callback).",
      editBoundError:"No edit function has been bound to this button.",
      deleteError:"The function for delete does not support two arguments
                                                        (data, callback).",
      deleteClusterError:"Clusters cannot be deleted."
    }
}
Name Type Default Description
labels object (shown above) Overwrite one or all labels used in the datamanipulation interface with localized strings.

Tooltips

The behaviour and style of the tooltips used to display node and edge title attributes can be customized. 

// tooltip behaviour and style options
var options: {
  tooltip: {
    delay: 300,
    fontColor: "black",
    fontSize: 14, // px
    fontFace: "verdana",
    color: {
      border: "#666",
      background: "#FFFFC6"
    }
  }
}
Name Type Default Description
delay Number 300 Time in milliseconds a user must hover over a node or edge before a tooltip appears.
fontColor String "black" Default color for tooltip text.
fontSize Number 14 Size in pixels of tooltip text.
fontFace String "verdana" Font family to used for tooltip text.
color.background String "#FFFFC6" Background color for the node.
color.border String "#666" Border color for the node.

Methods

Graph supports the following methods.

Method Return Type Description
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.
storePosition() none This will put the X and Y positions of all nodes in the dataset. It will also include allowedToMoveX and allowedToMoveY with the correct values. You can use this to stablize your graph once, then save the positions in a database so the next time you load the nodes, stabilization will be near instantaneous.
on(event, callback) none Create an event listener. The callback function is invoked every time the event is triggered. Avialable events: select. The callback function is invoked as callback(properties), where properties is an object containing event specific properties. See section Events for more information.
off(event, callback) none Remove an event listener created before via function on(event, callback). See section Events for more information.
redraw() none Redraw the graph. Useful when the layout of the webpage changed.
setData(data,[disableStart]) 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. Parameter disableStart is an optional Boolean and can disable the start of the simulation that would begin at the end of this function by default.
setOptions(options) none Set options for the graph. The available options are described in the section Configuration Options.
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.
zoomExtent() none Scales the graph so all the nodes are in center view.

Events

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

Here an example on how to catch a select event. 

graph.on('select', function (properties) {
  alert('selected nodes: ' + properties.nodes);
});

A listener can be removed via the function off: 

function onSelect (properties) {
  alert('selected nodes: ' + properties.nodes);
}

// add event listener
graph.on('select', onSelect);

// do stuff...

// remove event listener
graph.off('select', onSelect);

The following events are available.

name Description Properties
select Fired after the user selects or deselects a node by clicking it. Not fired when the method setSelectionis executed.
  • nodes: an array with the ids of the selected nodes
  • edges: an array with the ids of the selected edges
click Fired after the user clicks or taps on a touchscreen.
  • nodes: an array with the ids of the selected nodes
  • edges: an array with the ids of the selected edges
doubleClick Fired after the user double clicks or double taps on a touchscreen.
  • nodes: an array with the ids of the selected nodes
  • edges: an array with the ids of the selected edges
resize Fired when the size of the canvas has been updated (not neccecarily changed) by the setSize() function or by the setOptions() function.
  • width: the new width of the canvas
  • height: the new height of the canvas
stabilized Fired when the graph has been stabilized after initialization. This event can be used to trigger the .storePosition() function after stabilization.
  • iterations: number of iterations used to stabilize

Data policy

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