Network

Network is a visualization to display networks and networks consisting of nodes and edges. The visualization is easy to use and supports custom shapes, styles, colors, sizes, images, and more. The network visualization works smooth on any modern browser for up to a few thousand nodes and edges. To handle a larger amount of nodes, Network has clustering support. Network uses HTML canvas for rendering.

As of 4.0, the network consists of individual modules which handle specific parts of the network. These modules have their own docs, options, methods and events which you can access by clicking on the modules in the list below.

Show the getting started!

Creating a Network

Creating a vis network is easy. It requires you to include the vis.js and css files which you can get here. If you have these added to your application, you will need to specify your nodes and edges. You can use DOT language or export nodes and edges from Gephi if you'd like but we will do it without these for now. For more information on this click the tabs below. You can also use the vis.DataSets for dynamic data binding, for instance, changing the color, label or any option after you have initialized the network.

Once you have the data, all you need is a container div to tell vis where to put your network. Additionally you can use an options object to customize many aspects of the network. In code this looks like this:

<html>
<head>
    <script type="text/javascript" src="../../dist/vis.js"></script>
    <link href="../../dist/vis.css" rel="stylesheet" type="text/css" />

    <style type="text/css">
        #mynetwork {
            width: 600px;
            height: 400px;
            border: 1px solid lightgray;
        }
    </style>
</head>
<body>
<div id="mynetwork"></div>

<script type="text/javascript">
    // create an array with nodes
    var nodes = new vis.DataSet([
        {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 = new vis.DataSet([
        {from: 1, to: 3},
        {from: 1, to: 2},
        {from: 2, to: 4},
        {from: 2, to: 5}
    ]);

    // create a network
    var container = document.getElementById('mynetwork');

    // provide the data in the vis format
    var data = {
        nodes: nodes,
        edges: edges
    };
    var options = {};

    // initialize your network!
    var network = new vis.Network(container, data, options);
</script>
</body>
</html>

The result of the code above will be the basic example which is shown here.

Modules

configure	Generates an interactive option editor with filtering.
edges	Handles the creation and deletion of edges and contains the global edge options and styles.
groups	Contains the groups and some options on how to handle nodes with non-existing groups.
interaction	Used for all user interaction with the network. Handles mouse and touch events and selection as well as the navigation buttons and the popups.
layout	Governs the initial and hierarchical positioning.
manipulation	Supplies an API and optional GUI to alter the data in the network.
nodes	Handles the creation and deletion of nodes and contains the global node options and styles.
physics	Does all the simulation moving the nodes and edges to their final positions, also governs stabilization.

var options = {
  autoResize: true,
  height: '100%',
  width: '100%'
  locale: 'en',
  locales: locales,
  clickToUse: false,
  configure: {...},    // defined in the configure module.
  edges: {...},        // defined in the edges module.
  nodes: {...},        // defined in the nodes module.
  groups: {...},       // defined in the groups module.
  layout: {...},       // defined in the layout module.
  interaction: {...},  // defined in the interaction module.
  manipulation: {...}, // defined in the manipulation module.
  physics: {...},      // defined in the physics module.
}

network.setOptions(options);

The individual options are explained below. The ones referring to modules are explained in the corresponding module.

name	type	default	description
autoResize	Boolean	`true`	If true, the Network will automatically detect when its container is resized, and redraw itself accordingly. If false, the Network can be forced to repaint after its container has been resized using the function redraw() and setSize().
width	String	`'100%'`	the width of the canvas. Can be in percentages or pixels (ie. `'400px'`).
height	String	`'100%'`	the height of the canvas. Can be in percentages or pixels (ie. `'400px'`).
locale	String	`'en'`	Select the locale. By default, the language is English. If you want to use another language, you will need to define your own locale and refer to it here.
locales	Object	defaultLocales	Locales object. By default only `'en'` and `'nl'` are supported. Take a look at the locales section below for more explaination on how to customize this.
clickToUse	Boolean	false	Locales object. By default only `'en'` and `'nl'` are supported. Take a look at the locales section below for more explaination on how to customize this.

Custom locales

The locales object has the following format:

var locales = {
  en: {
    edit: 'Edit',
    del: 'Delete selected',
    back: 'Back',
    addNode: 'Add Node',
    addEdge: 'Add Edge',
    editNode: 'Edit Node',
    editEdge: 'Edit Edge',
    addDescription: 'Click in an empty space to place a new node.',
    edgeDescription: 'Click on a node and drag the edge to another node to connect them.',
    editEdgeDescription: 'Click on the control points and drag them to a node to connect to it.',
    createEdgeError: 'Cannot link edges to a cluster.',
    deleteClusterError: 'Clusters cannot be deleted.',
    editClusterError: 'Clusters cannot be edited.'
  }
}

If you want to define your own locale, you can change the key ('en' here) and change all the string. You can then use your new key in the locale option.

All Methods

This is a list of all the methods in the public API. They have been grouped by category, which correspond to the modules listed above.

Global methods for the network.
destroy()
Returns: none	Remove the network from the DOM and remove all Hammer bindings and references.
setData({`nodes: vis DataSet/Array`,`edges: vis DataSet/Array`})
Returns: none	Override all the data in the network. If stabilization is enabled in the physics module, the network will stabilize again. This method is also performed when first initializing the network.
setOptions(`Object options`)
Returns: none	Set the options. All available options can be found in the modules above. Each module requires it's own container with the module name to contain its options.
Methods related to the canvas.
canvasToDOM({`x: Number`,`y: Number`})
Returns: Object	This function converts canvas coordinates to coordinates on the DOM. Input and output are in the form of `{x:Number,y:Number}`. The DOM values are relative to the network container.
DOMtoCanvas({`x: Number`,`y: Number`})
Returns: Object	This function converts DOM coordinates to coordinates on the canvas. Input and output are in the form of `{x:Number,y:Number}`. The DOM values are relative to the network container.
redraw()
Returns: none	Redraw the network.
setSize(`String width`,`String height`)
Returns: none	Set the size of the canvas. This is automatically done on a window resize.
Clustering
cluster( `Object options`)
Returns: none	The options object is explained in full below. The joinCondition function is presented with all nodes.
clusterByConnection( `String nodeId`, `[Object options]` )
Returns: none	This method looks at the provided node and makes a cluster of it and all it's connected nodes. The behaviour can be customized by proving the options object. All options of this object are explained below. The joinCondition is only presented with the connected nodes.
clusterByHubsize( `Number hubsize`, `[Object options]`)
Returns: none	This method checks all nodes in the network and those with a equal or higher amount of edges than specified with the `hubsize` qualify. Cluster by connection is performed on each of them. The options object is described for `clusterByConnection` and does the same here.
clusterOutliers( `[Object options]`)
Returns: none	This method will cluster all nodes with 1 edge with their respective connected node.
findNode( `String nodeId`)
Returns: Array	Nodes can be in clusters. Clusters can also be in clusters. This function returns and array of nodeIds showing where the node is. Example: cluster 'A' contains cluster 'B', cluster 'B' contains cluster 'C', cluster 'C' contains node 'fred'. `network.clustering.findNode('fred')` will return `['A','B','C','fred']`.
isCluster( `String nodeId`)
Returns: Boolean	Returns true if the node whose ID has been supplied is a cluster.
openCluster( `String nodeId`)
Returns: none	Opens the cluster, releases the contained nodes and edges, removing the cluster node and cluster edges.
Layout
getSeed()
Returns: Number	If you like the layout of your network and would like it to start in the same way next time, ask for the seed using this method and put it in the `layout.randomSeed` option.
Manipulation methods to use the manipulation system without GUI.
enableEditMode()
Returns: none	Programatically enable the edit mode. Similar effect to pressing the edit button.
disableEditMode()
Returns: none	Programatically disable the edit mode. Similar effect to pressing the close icon (small cross in the corner of the toolbar).
addNodeMode()
Returns: none	Go into addNode mode. Having edit mode or manipulation enabled is not required. To get out of this mode, call `disableEditMode()`. The callback functions defined in `handlerFunctions` still apply. To use these methods without having the manipulation GUI, make sure you set `enabled` to false.
editNodeMode()
Returns: none	Go into editNode mode. The explaination from `addNodeMode` applies here as well.
addEdgeMode()
Returns: none	Go into addEdge mode. The explaination from `addNodeMode` applies here as well.
editEdgeMode()
Returns: none	Go into editEdge mode. The explaination from `addNodeMode` applies here as well.
deleteSelected()
Returns: none	Delete selected. Having edit mode or manipulation enabled is not required.
Methods to get information on nodes.
getPositions(`[Array of nodeIds]`)
Returns: Object	Returns the x y positions in canvas space of the nodes with the supplied nodeIds as an object: { nodeId1: {x: xValue, y:yValue}, nodeId2: {x: xValue, y:yValue}, ... } Alternative inputs are a String containing a nodeId or nothing. When a String is supplied, the position of the node corresponding to the ID is returned. When nothing is supplied, the positions of all nodes are returned.
storePositions()
Returns: none	When using the vis.DataSet to load your nodes into the network, this method will put the X and Y positions of all nodes into that dataset. If you're loading your nodes from a database and have this dynamically coupled with the DataSet, you can use this to stablize your network once, then save the positions in that database through the DataSet so the next time you load the nodes, stabilization will be near instantaneous. If the nodes are still moving and you're using dynamic smooth edges (which is on by default), you can use the option `stabilization.onlyDynamicEdges` in the physics module to improve initialization time. This method does not support clustering. At the moment it is not possible to cache positions when using clusters since they cannot be correctly initialized from just the positions.
getBoundingBox(`String nodeId`)
Returns: Object	Returns a bounding box for the node including label in the format: { top: Number, left: Number, right: Number, bottom: Number } These values are in canvas space.
getConnectedNodes(`String nodeId`)
Returns: Array	Returns an array of nodeIds of the all the nodes that are directly connected to this node.
getEdges(`String nodeId`)
Returns: Array	Returns an array of edgeIds of the edges connected to this node.
Physics methods to control when the simulation should run.
startSimulation()
Returns: none	Start the physics simulation. This is normally done whenever needed and is only really useful if you stop the simulation yourself and wish to continue it afterwards.
stopSimulation()
Returns: none	This stops the physics simulation and triggers a `stabilized` event. It can be restarted by dragging a node, altering the dataset or calling `startSimulation()`.
stabilize()
Returns: none	You can manually call stabilize at any time. All the stabilization options above are used.
Selection methods for nodes and edges.
getSelection()
Returns: Object	Returns an object with selected nodes and edges ids like this: { nodes: [Array of selected nodeIds], edges: [Array of selected edgeIds] }
getSelectedNodes()
Returns: Array	Returns an array of selected node ids like so: `[nodeId1, nodeId2, ..]`.
getSelectedEdges()
Returns: Array	Returns an array of selected edge ids like so: `[edgeId1, edgeId2, ..]`.
getNodeAt(`{x: xPosition DOM, y: yPosition DOM}`)
Returns: String	Returns a nodeId or undefined. The DOM positions are expected to be in pixels from the top left corner of the canvas.
getEdgeAt(`{x: xPosition DOM, y: yPosition DOM}`)
Returns: String	Returns a edgeId or undefined. The DOM positions are expected to be in pixels from the top left corner of the canvas..
selectNodes(`Array with nodeIds`,`[Boolean highlightEdges]`)
Returns: none	Selects the nodes corresponding to the id's in the input array. If highlightEdges is true or undefined, the neighbouring edges will also be selected. This method unselects all other objects before selecting its own objects. Does not fire events.
selectEdges(`Array with edgeIds`)
Returns: none	Selects the edges corresponding to the id's in the input array. This method unselects all other objects before selecting its own objects. Does not fire events.
unselectAll()
Returns: none	Unselect all objects. Does not fire events.
Methods to control the viewport for zoom and animation.
getScale()
Returns: Number	Returns the current scale of the network. 1.0 is comparible to 100%, 0 is zoomed out infinitely.
getPosition()
Returns: Number	Returns the current central focus point of the camera.
fit(`[Object options]`)
Returns: none	Zooms out so all nodes fit on the canvas. You can supply options to customize this: { nodes:[Array of nodeIds], animation: { // -------------------> can be a boolean too! duration: Number easingFunction: String } } The nodes can be used to zoom to fit only specific nodes in the view. The other options are explained in the `moveTo()` description below. All options are optional for the fit method.
focus( `String nodeId`, `[Object options]`)
Returns: none	You can focus on a node with this function. What that means is the view will lock onto that node, if it is moving, the view will also move accordingly. If the view is dragged by the user, the focus is broken. You can supply options to customize the effect: { scale: Number, offset: {x:Number, y:Number} locked: boolean animation: { // -------------------> can be a boolean too! duration: Number easingFunction: String } } All options except for locked are explained in the `moveTo()` description below. Locked denotes whether or not the view remains locked to the node once the zoom-in animation is finished. Default value is true. The options object is optional in the focus method.
moveTo(`Object options`)
Returns: none	You can animate or move the camera using the moveTo method. Options are: { position: {x:Number, y:Number}, scale: Number, offset: {x:Number, y:Number} animation: { // -------------------> can be a boolean too! duration: Number easingFunction: String } } The position (in canvas units!) is the position of the central focus point of the camera. The scale is the target zoomlevel. Default value is 1.0. The offset (in DOM units) is how many pixels from the center the view is focussed. Default value is {x:0,y:0}. For animation you can either use a Boolean to use it with the default options or disable it or you can define the duration (in milliseconds) and easing function manually. Available are: `linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeInQuart, easeOutQuart, easeInOutQuart, easeInQuint, easeOutQuint, easeInOutQuint`. You will have to define at least a scale or a position. Otherwise, there is nothing to move to.
releaseNode()
Returns: none	Programatically release the focussed node.

Cluster methods options object

The options object supplied to the cluster functions can contain these properties:

name	Type	description
joinCondition( `Object nodeOptions` )	Function	Optional for all but the cluster method. The cluster module loops over all nodes that are selected to be in the cluster and calls this function with their data as argument. If this function returns true, this node will be added to the cluster. You have access to all options (including the default) as well as any custom fields you may have added to the node to determine whether or not to include it in the cluster. Example: var nodes = [ {id: 4, label: 'Node 4'}, {id: 5, label: 'Node 5'}, {id: 6, label: 'Node 6', cid:1}, {id: 7, label: 'Node 7', cid:1} ] var options = { joinCondition:function(nodeOptions) { return nodeOptions.cid === 1; } } network.clustering.cluster(options);
processProperties( `Object nodeOptions` )	Function	Optional. Before creating the new cluster node, this (optional) function will be called with the properties supplied by you (`clusterNodeProperties`), all contained nodes and all contained edges. You can use this to update the properties of the cluster based on which items it contains. The function should return the properties to create the cluster node. In the example below, we ensure preservation of mass and value when forming the cluster: var options = { processProperties: function (clusterOptions, childNodes, childEdges) { var totalMass = 0; var totalValue = 0; for (var i = 0; i < childNodes.length; i++) { totalMass += childNodes[i].mass; totalValue = childNodes[i].value ? totalValue + childNodes[i].value : totalValue; } clusterOptions.mass = totalMass; if (totalValue > 0) { clusterOptions.value = totalValue; } return clusterOptions; }, }
clusterNodeProperties	Object	Optional. This is an object containing the options for the cluster node. All options described in the nodes module are allowed. This allows you to style your cluster node any way you want. This is also the style object that is provided in the processProperties function for fine tuning. If undefined, default node options will be used.
clusterEdgeProperties	Object	Optional. This is an object containing the options for the edges connected to the cluster. All options described in the edges module are allowed. Using this, you can style the edges connecting to the cluster any way you want. If none are provided, the optoins from the edges that are replaced are used. If undefined, default edge options will be used.

All Events

This is a list of all the events in the public API. They are collected here from all individual modules.

These events are fired by the interaction module. They are related to user input.

name	properties	description
Events triggered by human interaction, selection, dragging etc.
click	{ nodes: [Array of selected nodeIds], edges: [Array of selected edgeIds], event: [Object] original click event, pointer: { DOM: {x:pointer_x, y:pointer_y}, canvas: {x:canvas_x, y:canvas_y} } }	Fired when the user clicks the mouse or taps on a touchscreen device.
doubleClick	same as `click`.	Fired when the user double clicks the mouse or double taps on a touchscreen device. Since a double click is in fact 2 clicks, 2 click events are fired, followed by a double click event. If you do not want to use the click events if a double click event is fired, just check the time between click events before processing them.
oncontext	same as `click`.	Fired when the user click on the canvas with the right mouse button. The right mouse button does not select by default. You can use getNodeAt to select the node if you want.
hold	same as `click`.	Fired when the user clicks and holds the mouse or taps and holds on a touchscreen device. A click event is also fired in this case.
release	same as `click`.	Fired after drawing on the canvas has been completed. Can be used to draw on top of the network.
select	same as `click`.	Fired when the selection has changed by user action. This means a node or edge has been selected, added to the selection or deselected. All select events are only triggered on click and hold.
selectNode	same as `click`.	Fired when a node has been selected by the user.
selectEdge	same as `click`.	Fired when a edge has been selected by the user.
deselectNode	{ nodes: [Array of selected nodeIds], edges: [Array of selected edgeIds], event: [Object] original click event, pointer: { DOM: {x:pointer_x, y:pointer_y}, canvas: {x:canvas_x, y:canvas_y} } }, previousSelection: { nodes: [Array of previously selected nodeIds], edges: [Array of previously selected edgeIds] } }	Fired when a node (or nodes) has (or have) been deselected by the user. The previous selection is the list of nodes and edges that were selected before the last user event.
deselectEdge	same as `deselectNode`.	Fired when a edge (or edges) has (or have) been deselected by the user. The previous selection is the list of nodes and edges that were selected before the last user event.
dragStart	same as `click`.	Fired when starting a drag.
dragging	same as `click`.	Fired when dragging node(s) or the view.
dragEnd	same as `click`.	Fired when the drag has finished.
zoom	`{direction:'+'/'-'}`	Fired when the user zooms in or out. The properties tell you which direction the zoom is in.
showPopup	`id of item corresponding to popup`	Fired when the popup is shown.
hidePopup	none	Fired when the popup is hidden.
Events triggered the physics simulation. Can be used to trigger GUI updates.
startStabilizing	none	Fired when stabilization starts. This is also the case when you drag a node and the physics simulation restarts to stabilize again. Stabilization does not neccesarily imply 'without showing'.
stabilizationProgress	{ iterations: Number // iterations so far, total: Number // total iterations in options }	Fired when a multiple of the `updateInterval` number of iterations is reached. This only occurs in the 'hidden' stabilization.
stabilizationIterationsDone	none	Fired when the 'hidden' stabilization finishes. This does not necessarily mean the network is stabilized; it could also mean that the amount of iterations defined in the options has been reached.
stabilized	{ iterations: Number // iterations it took }	Fired when the network has stabilized or when the `stopSimulation()` has been called. The amount of iterations it took could be used to tweak the maximum amount of iterations needed to stabilize the network.
Event triggered by the canvas.
resize	{ width: Number // the new width of the canvas height: Number // the new height of the canvas oldWidth: Number // the old width of the canvas oldHeight: Number // the old height of the canvas }	Fired when the size of the canvas has been resized, either by a redraw call when the container div has changed in size, a setSize() call with new values or a setOptions() with new width and/or height values.
Events triggered by the rendering module. Can be used to draw custom elements on the canvas.
initRedraw	none	Fired before the redrawing begins. The simulation step has completed at this point. Can be used to move custom elements before starting drawing the new frame.
beforeDrawing	`canvas context`	Fired after the canvas has been cleared, scaled and translated to the viewing position but before all edges and nodes are drawn. Can be used to draw behind the network.
afterDrawing	`canvas context`	Fired after drawing on the canvas has been completed. Can be used to draw on top of the network.
Event triggered by the view module.
animationFinished	none	Fired when an animation is finished.

Network supports data in the DOT language. To use data in the DOT language, you can use the vis.network.convertDot converter to transform the DOT language into a vis.Network compatible nodes, edges and options objects. You can extend the options object with other options if you'd like.

Example usage:

// provide data in the DOT language
var DOTstring = 'dinetwork {1 -> 1 -> 2; 2 -> 3; 2 -- 4; 2 -> 1 }';
var parsedData = vis.network.convertDot(DOTstring);

var data = {
  nodes: parsedData.nodes,
  edges: parsedData.edges
}

var options = parsedData.options;

// you can extend the options like a normal JSON variable:
options.nodes = {
  color: 'red'
}

// create a network
var network = new vis.Network(container, data, options);

Network can import data straight from an exported json file from gephi. You can get the JSON exporter here: https://marketplace.gephi.org/plugin/json-exporter/. An example exists showing how to get a JSON file into Vis: 30_importing_from_gephi.

Example usage:

// load the JSON file containing the Gephi network.
var gephiJSON = loadJSON("./data/WorldCup2014.json"); // code in example 30

// you can customize the result like with these options. These are explained below.
// These are the default options.
var parserOptions = {
  edges: {
    inheritColors: false
  },
  nodes: {
    fixed: true,
    parseColor: false
  }
}

// parse the gephi file to receive an object
// containing nodes and edges in vis format.
var parsed = vis.network.convertGephi(gephiJSON, parserOptions);

// provide data in the normal fashion
var data = {
  nodes: parsed.nodes,
  edged: parsed.edges
};

// create a network
var network = new vis.Network(container, data);

Gephi parser options

There are a few options you can use to tell Vis what to do with the data from Gephi.

name	type	default	description
nodes.fixed	Boolean	`true`	When false, the nodes will move according to the physics model after import. If true, the nodes do not move at all. If set to true, the node positions have to be defined to avoid infinite recursion errors in the physics.
nodes.parseColor	Boolean	`false`	If true, the color will be parsed by the vis parser, generating extra colors for the borders, highlighs and hover. If false, the node will be the supplied color.
edges.inheritColor	Boolean	`false`	When true, the color supplied by gephi is ignored and the inherit color mode is used with the global setting.