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!

Contents

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.

Options

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.
locales Object defaultLocales Locales object. By default 'en', 'de', 'es', 'it', 'nl' 'pt-br', 'ru' are supported. Take a look at the locales section below for more explaination on how to customize this.
clickToUse Boolean false When a Network is configured to be clickToUse, it will react to mouse and touch events only when active. When active, a blue shadow border is displayed around the Network. The network is set active by clicking on it, and is changed to inactive again by clicking outside the Network or by pressing the ESC key.
configure Object Object All options in this object are explained in the configure module.
edges Object Object All options in this object are explained in the edges module.
nodes Object Object All options in this object are explained in the nodes module.
groups Object Object All options in this object are explained in the groups module.
layout Object Object All options in this object are explained in the layout module.
interaction Object Object All options in this object are explained in the interaction module.
manipulation Object Object All options in this object are explained in the manipulation module.
physics Object Object All options in this object are explained in the physics module.


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 strings. You can then use your new key in the locale option.



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()
setData({nodes: vis DataSet/Array,edges: vis DataSet/Array})
setOptions(Object options)
on(String event name, Function callback)
off(String event name, Function callback)
once(String event name, Function callback)
Methods related to the canvas.
canvasToDOM({x: Number,y: Number})
DOMtoCanvas({x: Number,y: Number})
redraw()
setSize(String width,String height)
Clustering
cluster( Object options)
clusterByConnection( String nodeId, [Object options] )
clusterByHubsize( [Number hubsize], [Object options])
clusterOutliers( [Object options])
findNode( String/Number nodeId)
getClusteredEdges( String baseEdgeId)
getBaseEdge( String clusteredEdgeId)
getBaseEdges(String clusteredEdgeId)
updateEdge( String startEdgeId, Object options)
updateClusteredNode( String clusteredNodeId, Object options)
isCluster( String nodeId)
getNodesInCluster( String clusterNodeId)
openCluster( String nodeId, Object options)
Layout
getSeed()
Manipulation methods to use the manipulation system without GUI.
enableEditMode()
disableEditMode()
addNodeMode()
editNode()
addEdgeMode()
editEdgeMode()
deleteSelected()
Methods to get information on nodes and edges.
getPositions([Array of nodeIds])
storePositions()
moveNode(nodeId, Number x, Number y)
getBoundingBox(String nodeId)
getConnectedNodes(String nodeId or edgeId, [String direction])
getConnectedEdges(String nodeId)
Physics methods to control when the simulation should run.
startSimulation()
stopSimulation()
stabilize([iterations])
Selection methods for nodes and edges.
getSelection()
getSelectedNodes()
getSelectedEdges()
getNodeAt({x: xPosition DOM, y: yPosition DOM})
getEdgeAt({x: xPosition DOM, y: yPosition DOM})
selectNodes(Array with nodeIds,[Boolean highlightEdges])
selectEdges(Array with edgeIds)
setSelection( Object selection, [Object options])
unselectAll()
Methods to control the viewport for zoom and animation.
getScale()
getViewPosition()
fit([Object options])
focus( String nodeId, [Object options])
moveTo(Object options)
releaseNode()
Methods to use with the configurator module.
getOptionsFromConfigurator()


Cluster methods options object

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

Name Type Description
joinCondition(
  nodeOptions: Object
)
or
joinCondition(
  parentNodeOptions: Object,
  childNodeOptions: Object
)
Function Optional for all but the cluster method.
clusterByConnection is the only function that will pass 2 nodeOptions objects as arguments to the joinCondition callback.
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);
clusterByConnection will pass 2 nodeOptions objects as arguments to the joinCondition callback.
processProperties(
  clusterOptions: Object,
  childNodesOptions: Array,
  childEdgesOptions: Array
)
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.

Default functionality only allows clustering if the cluster will contain 2 or more nodes. To allow clustering of single nodes you can use the allowSingleNodeCluster : true property.
    clusterNodeProperties: {
        allowSingleNodeCluster: true
    }
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 options from the edges that are replaced are used. If undefined, default edge options will be used.


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 Object Fired when the user clicks the mouse or taps on a touchscreen device. Passes an object with properties structured as:
{
  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}
  }
}
This is the structure common to all events. Specifically for the click event, the following property is added:
{
...
  items: [Array of click items],
}
Where the click items can be:
  {nodeId:NodeId}            // node with given id clicked on
  {nodeId:NodeId labelId:0}  // label of node with given id clicked on
  {edgeId:EdgeId}            // edge with given id clicked on
  {edge:EdgeId, labelId:0}   // label of edge with given id clicked on
The order of the items array is descending in z-order. Thus, to get the topmost item, get the value at index 0.
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 the method 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 an edge has been selected by the user.
deselectNode Object 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. Passes an object with properties structured as:
{
  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]
  }
}
deselectEdge same as deselectNode. Fired when an 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.
controlNodeDragging Object Fired when dragging control node. Control Edge is edge that is being dragged and contains ids of 'from' and 'to' nodes. If control node is not dragged over another node, 'to' field is undefined. Passes an object with properties structured as:
{
    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}
    },    
    controlEdge: {from:from_node_id, to:to_node_id}
}
controlNodeDragEnd same as controlNodeDragging. Fired when the control node drag has finished.
hoverNode {node: nodeId} Fired if the option interaction:{hover:true} is enabled and the mouse hovers over a node.
blurNode {node: nodeId} Fired if the option interaction:{hover:true} is enabled and the mouse moved away from a node it was hovering over before.
hoverEdge {edge: edgeId} Fired if the option interaction:{hover:true} is enabled and the mouse hovers over an edge.
blurEdge {edge: edgeId} Fired if the option interaction:{hover:true} is enabled and the mouse moved away from an edge it was hovering over before.
zoom Object Fired when the user zooms in or out. The properties tell you which direction the zoom is in. The scale is a number greater than 0, which is the same that you get with network.getScale(). When fired by clicking the zoom in or zoom out navigation buttons, the pointer property of the object passed will be null. Passes an object with properties structured as:
{
  direction: '+'/'-',
  scale: Number,
  pointer: {x:pointer_x, y:pointer_y}
}
showPopup id of item corresponding to popup Fired when the popup (tooltip) is shown.
hidePopup none Fired when the popup (tooltip) 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 necessarily imply 'without showing'.
stabilizationProgress Object Fired when a multiple of the updateInterval number of iterations is reached. This only occurs in the 'hidden' stabilization. Passes an object with properties structured as:
{
  iterations: Number // iterations so far,
  total: Number      // total iterations in options
}
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 Object 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. Passes an object with properties structured as:
{
  iterations: Number // iterations it took
}
Event triggered by the canvas.
resize Object 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. Passes an object with properties structured as:
{
  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
}
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.
Event triggered by the configuration module.
configChange Object Fired when a user changes any option in the configurator. The options object can be used with the setOptions method or stringified using JSON.stringify(). You do not have to manually put the options into the network: this is done automatically. You can use the event to store user options in the database.


Importing data

Network contains conversion utilities to import data from Gephi and graphs in the DOT language.

Import data from Gephi

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

Example usage:

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

// 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.parseGephiNetwork(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, highlights 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.

Import data in DOT language

Network supports data in the DOT language. To use data in the DOT language, you can use the vis.parseDOTNetwork converter function to transform the DOT language string into a Vis Network compatible nodes, edges and options. You can alter or extend the returned nodes, edges and options if you like.

Example usage:

// provide data in the DOT language
var DOTstring = 'dinetwork {1 -> 1 -> 2; 2 -> 3; 2 -- 4; 2 -> 1 }';
var parsedData = vis.parseDOTNetwork(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);