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.
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>
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.
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
and edges
,
both containing an Array with objects. The data formats are described
in the sections Nodes and Edges.
Example:
var data = { nodes: [...], edges: [...] };
dot
,
containing a string with data in the
DOT language.
DOT support is described in section DOT_language.
Example:
var data = { dot: '...' };
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 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 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. |
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);
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. 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. |
width | String | "400px" | The width of the graph in pixels or as a percentage. |
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 . |
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. |
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 |
All code and data is processed and rendered in the browser. No data is sent to any server.