Introduction

About

Cytoscape.js is an open-source graph theory library written in JavaScript. You can use Cytoscape.js for graph analysis and visualisation.

Cytoscape.js allows you to easily display and manipulate rich, interactive graphs. Because Cytoscape.js allows the user to interact with the graph and the library allows the client to hook into user events, Cytoscape.js is easily integrated into your webapp, especially since Cytoscape.js supports both desktop browsers, like Chrome, and mobile browsers, like on the iPad. Cytoscape.js includes all the gestures you would expect out-of-the-box, including pinch-to-zoom, box selection, panning, et cetera.

Cytoscape.js also has graph analysis in mind: The library contains a slew of useful functions in graph theory. You can use Cytoscape.js headlessly on Node.js to do graph analysis in the terminal or on a web server.

Cytoscape.js is an open-source project, and anyone is free to contribute. For more information, refer to the GitHub README.

The library was developed at the Donnelly Centre at the University of Toronto. It is the successor of Cytoscape Web.

Cytoscape.js & Cytoscape

Though Cytoscape.js shares its name with Cytoscape, Cytoscape.js is not Cytoscape. Cytoscape.js is a JavaScript library for programmers. It is not an app for end-users, nor can you just copy-paste some code to "automagically" make you a webapp.

Cytoscape.js is a JavaScript library: It gives you a reusable graph widget that you can integrate with the rest of your webapp with your own JavaScript code. The keen members of the audience will point out that this means that Cytoscape plugins — written in Java — will obviously not work in Cytoscape.js — written in JavaScript.

We are trying to make the two projects intercompatible as possible, and we do share philosophies with Cytoscape: Graph style and data should be separate, the library should provide core functionality with extensions adding functionality on top of the library, and so on.

Funding

Funding for Cytoscape.js and Cytoscape is provided by NRNB (U.S. National Institutes of Health, National Center for Research Resources grant numbers P41 RR031228 and GM103504) and by NIH grants 2R01GM070743 and 1U41HG006623. The following organizations help develop Cytoscape:

ISB | UCSD | MSKCC | Pasteur | Agilent | UCSF | Unilever | Toronto | NCIBI | NRNB

Notation

Architecture & API

There are two components in the architecture that a developer need concern himself in order to use Cytoscape.js, the core and the collection. In Cytoscape.js, the core is a developer's main entry point into the library. From the core, a developer can run layouts, alter the viewport, and perform other operations on the graph as a whole.

The core provides several functions to access elements in the graph. Each of these functions returns a collection, a set of elements in the graph. A set of functions are available on collections that allow the developer to filter the collection, perform operations on the collection, traverse the graph about the collection, get data about elements in the collection, and so on.

Notation

There are several types that different functions can be executed on, and the variable names used to denote these types in the documentation are outlined below:

Notation       Works on
--------       --------
cy ........... the core
eles ......... a collection of one or more elements (nodes and edges)
ele .......... a collection of a single element (node or edge)
nodes ........ a collection of one or more nodes
node ......... a collection of a single node
edges ........ a collection of one or more edges
edge ......... a collection of a single edge

By default, a function returns a reference back to the calling object to allow for jQuery-like chaining (e.g. obj.fn1().fn2().fn3()). Unless otherwise indicated in this documentation, a function is chainable in this manner unless a different return value is specified. This applies both to the core and to collections.

For functions that return a value, note that calling a singular — ele, node, or edge — function on a collection of more than one element will return the expected value for only the first element.

Position

A node's position refers to the centre point of its bounding box.

There is an important distinction to make for position: A position may be a model position or a rendered position.

A model position — as its name suggests — is the position stored in the model for an element. An element's model position remains constant, despite changes to zoom and pan.

A rendered position is an on-screen location relative to the viewport. For example, a rendered position of { x: 100, y: 100 } specifies a point 100 pixels to the right and 100 pixels down from the top-left corner of the viewport. An element's rendered position naturally changes as zoom and pan changes, because the element's on-screen position in the viewport changes as zooming and panning are applied.

In this documentation, "position" refers to model position unless otherwise stated.

Elements JSON

Examples are given that outline format of the elements JSON used to load elements into Cytoscape.js:

$('#cy').cytoscape({

  elements: [
    { // node n1
      group: 'nodes', // 'nodes' for a node, 'edges' for an edge

      // NB: id fields must be strings
      data: { // element data (put dev data here)
          id: 'n1', // mandatory for each element, assigned automatically on undefined
          parent: 'nparent', // indicates the compound node parent id; not defined => no parent
      },

      position: { // the model position of the node (optional on init, mandatory after)
          x: 100,
          y: 100
      },

      selected: false, // whether the element is selected (default false)

      selectable: true, // whether the selection state is mutable (default true)

      locked: false, // when locked a node's position is immutable (default false)

      grabbable: true, // whether the node can be grabbed and moved by the user

      classes: 'foo bar' // a space separated list of class names that the element has

      // NB: you should only use `css` for very special cases; use classes instead
      css: { backgroundColor: red } // overriden style properties
    },

    { // node n2
      group: 'nodes',
      data: { id: 'n2' },
      renderedPosition: { x: 200, y: 200 } // can alternatively specify position in rendered on-screen pixels
    },

    { // node n3
      group: 'nodes',
      data: { id: 'n3', parent: 'nparent' },
      position: { x: 123, y: 234 }
    },

    { // node nparent
      group: 'nodes',
      data: { id: 'nparent' }
    },

    { // edge e1
      group: 'edges',
      data: {
          id: 'e1',
          source: 'n1', // the source node id (edge comes from this node)
          target: 'n2'  // the target node id (edge goes to this node)
      }
    }
  ],

  // so we can see the ids
  style: [
    {
      selector: 'node',
      css: {
        'content': 'data(id)'
      }
    }
  ]

});

Performance

Background

You may notice that performance starts to degrade on graphs with large numbers of elements. This happens for several reasons:

• Performance is a function of graph size, so performance decreases as the number of elements increases.
• The rich visual styles that Cytoscape.js supports can be very expensive. Only drawing circles and straight lines is cheap, but drawing complex graphs is not.
• Edges are particularly expensive to render. Multigraphs become even more expensive with the need for bezier curve edges.
• Interactivity is expensive. Being able to pan, pinch-to-zoom, drag nodes around, et cetera is expensive — especially when having to rerender edges.

Optimisations

You can get much better performance out of Cytoscape.js by tuning your options, in descending order of significance:

• Haystacks make fast edges : Set your edges curve-style to haystack in your stylesheet. Haystack edges are straight lines, which are much less expensive to render than bezier edges.
• Hide edges during interactivity : Set hideEdgesOnViewport to true in your initialisation options. This makes interactivity a lot less expensive by hiding edges during pan, mouse wheel zoom, pinch-to-zoom, and node drag actions.
• Animations : You will get better performance without animations. If using animations anyway:
  • Try to limit the number of concurrent animating elements.
  • When using transition animations in the style, make sure transition-property is defined only for states that you want to animate. If you have transition-property defined in a default state, the animation will try to run more often than if you limit it to particular states you actually want to animate.
• Edge selection : If your app does not need edge selection, you can get performance gains by unselectifying edges (i.e. edges.unselectify()). This disables selection for edges, so their style will not have to be recalculated during box selection et cetera.
• Labels : Drawing labels is expensive.
  • If you can go without them or show them on tap/mouseover, you'll get better performance.
  • Consider not having labels for edges.
  • Consider setting min-zoomed-font-size in your style so that when labels are small — and hard to read anyway — they are not rendered. When the labels are at least the size you set (i.e. the user zooms in), they will be visible.
• Simplify edge style : Use solid edges. Dotted and dashed edges are much more expensive to draw, so you will get increased performance by not using them.
• Simplify node style : Keep your node styles simple to improve performance.
  • Background images are very expensive, so you should remove them if you need high performance.
  • Node borders can be slightly expensive, so you can experiment with removing them to see if it makes a noticeable difference for your use case.
• Opacity : Making elements semitransparent is more expensive than leaving them opaque. Try to use visibility: hidden or display: none to hide elements rather than using opacity.
• Concise stylsheets are fast stylesheets : Try to keep your stylesheets from getting overly long. Cut out unused blocks and try to limit the number of blocks — and therefore selectors — you have. Each time style needs to be recalculated, each block's selector needs to be compared to each element. Note that usually stylesheet length has a much lesser effect on performance than other factors.

By making these optimisations, you can increase the performance of Cytoscape.js such that you can have high performance graphs several orders of magnitude greater in size.

Selectors

Notes & caveats

A selector functions similar to a jQuery selector on DOM elements, but selectors in Cytoscape.js instead work on collections.

The selectors can be combined together to make powerful queries in Cytoscape.js, for example:

// get all nodes with weight more than 50 and height strictly less than 180
cy.elements("node[weight >= 50][height < 180]");

Selectors can be joined together (effectively creating a logical OR) with commas:

// get node j and the edges coming out from it
cy.elements("node#j, edge[source = 'j']");

It is important to note that strings need to be enclosed by quotation marks:

//cy.filter("node[name = Jerry]"); // this doesn't work
cy.filter("node[name = 'Jerry']"); // but this does

Group, class, & ID

node, edge, or * (group selector) Matches elements based on group (node for nodes, edge for edges, * for all).

.className Matches elements that have the specified class (e.g. use .foo for a class named "foo").

#id Matches element with the matching ID (e.g. #foo is the same as [id = 'foo'])

Data

[name]
Matches elements if they have the specified data attribute defined aka not undefined (e.g. [foo] for an attribute named "foo"). Here, null is considered a defined value.

[?name]
Matches elements if the specified data attribute is a truthy value (e.g. [?foo]).

[!name]
Matches elements if the specified data attribute is a falsey value (e.g. [!foo]).

[^name]
Matches elements if the specified data attribute is not defined aka undefined (e.g [^foo]). Here, null is considered a defined value.

[name = value]
Matches elements if their data attribute matches a specified value (e.g. [foo = 'bar'] or [num = 2]).

[name != value]
Matches elements if their data attribute doesn't match a specified value (e.g. [foo != 'bar'] or [num != 2]).

[name > value]
Matches elements if their data attribute is greater than a specified value (e.g. [foo > 'bar'] or [num > 2]).

[name >= value]
Matches elements if their data attribute is greater than or equal to a specified value (e.g. [foo >= 'bar'] or [num >= 2]).

[name < value]
Matches elements if their data attribute is less than a specified value (e.g. [foo < 'bar'] or [num < 2]).

[name <= value]
Matches elements if their data attribute is less than or equal to a specified value (e.g. [foo <= 'bar'] or [num <= 2]).

[name *= value]
Matches elements if their data attribute contains the specified value as a substring (e.g. [foo *= 'bar']).

[name ^= value]
Matches elements if their data attribute starts with the specified value (e.g. [foo ^= 'bar']).

[name $= value]
Matches elements if their data attribute ends with the specified value (e.g. [foo $= 'bar']).

@ (data attribute operator modifier)
Prepended to an operator so that is case insensitive (e.g. [foo @$= 'ar'], [foo @>= 'a'], [foo @= 'bar'])

[[]] (metadata brackets)
Use double square brackets in place of square ones to match against metadata instead of data (e.g. [[degree > 2]] matches elements of degree greater than 2). The properties that are supported include degree, indegree, and outdegree.

Compound nodes

> (child selector)
Matches direct children of the parent node (e.g. node > node).

  (descendant selector)
Matches descendants of the parent node (e.g. node node).

$ (subject selector)
Sets the subject of the selector (e.g. $node > node to select the parent nodes instead of the children).

State

Animation

• :animated : Matches elements that are currently being animated.
• :unanimated : Matches elements that are not currently being animated.

Selection

• :selected : Matches selected elements.
• :unselected : Matches elements that aren't selected.
• :selectable : Matches elements that are selectable.
• :unselectable : Matches elements that aren't selectable.

Locking

• :locked : Matches locked elements.
• :unlocked : Matches elements that aren't locked.

Visibility

• :visible : Matches elements that are visible (i.e. display: element and visibility: visible).
• :hidden : Matches elements that are hidden.
• :transparent : Matches elements that are transparent (i.e. opacity: 0).

User interaction:

• :grabbed : Matches elements that are being grabbed by the user.
• :free : Matches elements that are not currently being grabbed by the user.
• :grabbable : Matches elements that are grabbable by the user.
• :ungrabbable : Matches elements that are not grabbable by the user.
• :active : Matches elements that are active (i.e. user interaction, similar to :active in CSS).
• :inactive : Matches elements that are inactive (i.e. no user interaction).
• :touch : Matches elements when displayed in a touch-based enviroment (e.g. on a tablet).

In or out of graph

• :removed : Matches elements that have been removed from the graph.
• :inside : Matches elements that have are in the graph (they are not removed).

Compound nodes

• :parent : Matches parent nodes (they have one or more child nodes).
• :child : Matches child nodes (they each have a parent).

Edges

• :loop : Matches loop edges (same source as target).
• :simple : Matches simple edges (i.e. as would be in a simple graph, different source as target).

Style

Style in Cytoscape.js follows CSS conventions as closely as possible. In most cases, a property has the same name and behaviour as its corresponding CSS namesake. However, the properties in CSS are not sufficient to specify the style of some parts of the graph. In that case, additional properties are introduced that are unique to Cytoscape.js.

It is important to note that in your stylesheet, specificity rules are completely ignored. In CSS, specificity often makes stylesheets behave in ways contrary to developer's natural mental model. This is terrible, because it wastes time and overcomplicates things. Thus, there is no analogue of CSS specificity in Cytoscape.js stylesheets. For a given style property for a given element, the last matching selector wins. In general, you should be using something along the lines of OOCSS principles, anyway — making specificity essentially irrelevant.

Format

The style specified at initialisation can be in a functional format, in a plain JSON format, or in a string format — the plain JSON format and string format being more useful if you want to pull down the style from the server. If you pull the style from the server, you must initialise Cytoscape.js after the style has been loaded.

String format

Note that the trailing semicolons for each property are mandatory. Parsing will certainly fail without them.

An example style file:

/* comments may be entered like this */
node {
  background-color: green;
}

At initialisation:

$('#cy').cytoscape({
  // ...

  style: aStyleString // probably previously loaded via ajax

  // , ...
});

Plain JSON format

$('#cy').cytoscape({
  // ...

  style: [
    {
      selector: 'node',
      css: {
        'background-color': 'red'
      }
    }

    // , ...
  ]

  // , ...
});

Functional format

$('#cy').cytoscape({
  // ...

  style: cytoscape.stylesheet()
    .selector('node')
      .css({
        'background-color': 'blue'
      })

      // ...


  // , ...
});

Properties

Notes

• Colours may be specified by name (e.g. red), hex (e.g. #ff0000 or #f00), RGB (e.g. rgb(255, 0, 0)), or HSL (e.g. hsl(0, 100%, 50%)).
• Values requiring a number, such as a length, can be specified in pixel values (e.g. 24px), unitless values that are implicitly in pixels (24), or em values (e.g. 2em).
• Opacity values are specified as numbers ranging on 0 <= opacity <= 1.

Element properties

These properties can be used on any element.

Labels:

• color : The colour of the element's label.
• content : The text to display for an element's label.
• font-family : A comma-separated list of font names to use on the label text.
• font-size : The size of the label text.
• font-style : A CSS font style to be applied to the label text.
• font-weight : A CSS font weight to be applied to the label text.
• text-opacity : The opacity of the label text, including its outline.
• text-outline-color : The colour of the outline around the element's label text.
• text-outline-opacity : The opacity of the outline on label text.
• text-outline-width : The size of the outline on label text.
• min-zoomed-font-size : If zooming makes the effective font size of the label smaller than this, then no label is shown.

Size & visibility:

• opacity : The opacity of the element.
• visibility : Whether the element is visible; can be visible or hidden.
• width : The element's width; the line width for edges or the horizontal size of a node.
• z-index : A non-negative integer that specifies the z-ordering of the element. An element with a higher z-index is put on top of an element with a lower value.

Overlays (e.g. used in :active state):

• overlay-color : The colour of the overlay.
• overlay-padding : The area outside of the element within which the overlay is shown.
• overlay-opacity : The opacity of the overlay.

Transition animations:

• transition-property : A comma separated list of style properties to animate in this state.
• transition-duration : The length of the transition in seconds (e.g. 0.5s).
• transition-delay : The length of the delay in seconds before the transition occurs (e.g. 0.25).

Node properties

These properties apply only to nodes.

Labels:

• text-halign : The vertical alignment of a label; may have value left, center, or right.
• text-valign : The vertical alignment of a label; may have value top, center, or bottom.

Body:

• background-color : The colour of the node's body.
• background-blacken : Blackens the node's body for values from 0 to 1; whitens the node's body for values from 0 to -1.
• background-opacity : The opacity level of the node's body.
• border-color : The colour of the node's border.
• border-opacity : The opacity of the node's border.
• border-width : The size of the node's border.
• height : The height of the node's body.
• shape : The shape of the node's body; may be rectangle, roundrectangle, ellipse, triangle, pentagon, hexagon, heptagon, octagon, star. Note that each shape fits with the specified width and height, and so you may have to adjust width and height if you desire an equilateral shape (i.e. width !== height for several equilateral shapes).

Background image:

• background-image : The URL that points to the image that should be used as the node's background. PNG, JPG, and SVG are supported formats.
• background-fit : How the background image is fit to the node; may be none for original size, contain to fit inside node, or cover to cover the node.
• background-repeat : Whether to repeat the background image; may be no-repeat, repeat-x, repeat-y, or repeat.
• background-position-x : The x position of the background image, measured in percent (e.g. 50%) or pixels (e.g. 10px).
• background-position-y : The y position of the background image, measured in percent (e.g. 50%) or pixels (e.g. 10px).

Pie chart background:

These properties allow you to create pie chart backgrounds on nodes. Note that 16 slices maximum are supported per node, so in the properties 1 <= i <= 16. Of course, you must specify a numerical value for each property in place of i. Each nonzero sized slice is placed in order of i, starting from the 12 o'clock position and working clockwise.

You may find it useful to reserve a number to a particular colour for all nodes in your stylesheet. Then you can specify values for pie-i-background-size accordingly for each node via a mapper. This would allow you to create consistently coloured pie charts in each node of the graph based on element data.

• pie-size : The diameter of the pie, measured as a percent of node size (e.g. 100%) or an absolute length (e.g. 25px).
• pie-i-background-color : The colour of the node's ith pie chart slice.
• pie-i-background-size : The size of the node's ith pie chart slice, measured in percent (e.g. 25% or 25).

Compound nodes:

• padding-left : The size of the area on the left of the compound node that can not be occupied by child nodes.
• padding-right : The size of the area on the right of the compound node that can not be occupied by child nodes.
• padding-top : The size of the area on the top of the compound node that can not be occupied by child nodes.
• padding-bottom : The size of the area on the bottom of the compound node that can not be occupied by child nodes.

Edge properties

These properties apply only to edges:

• curve-style : The curving method used to separate two or more edges between two nodes; may be bezier (default) or haystack (for which loops are unsupported). Note that haystack edges work best with ellipse, rectangle, or similar nodes. Smaller node shapes, like triangle, will not be as aesthetically pleasing. Also note that edge arrows are unsupported for haystack edges.
• control-point-step-size : From the line perpendicular from source to target, this value specifies the inter-control-point distance.
• control-point-distance : Overrides control-point-step-size with a manual value. Because it overrides the step size, bezier edges with the same value will overlap. Thus, it's best to use this as a one-off value for particular edges if need be.
• control-point-weight : Weights control points along the line from source to target. This value ranges on [0, 1], with 0 towards the source node and 1 towards the target node.
• line-color : The colour of the edge's line.
• line-style : The style of the edge's line; may be solid, dotted, or dashed.
• source-arrow-color : The colour of the edge's arrow on the source side.
• source-arrow-shape : The shape of the edge's arrow on the source side; may be tee, triangle, square, circle, diamond, or none.
• source-arrow-fill : The fill state of the edge's source arrow; may be filled or hollow.
• target-arrow-color : The colour of the edge's arrow on the target side.
• target-arrow-shape : The shape of the edge's arrow on the target side; may be tee, triangle, square, circle, diamond, or none.
• target-arrow-fill : The fill state of the edge's target arrow; may be filled or hollow.

Core properties

These properties apply only to the core. You can use the special core selector string to set these properties.

• active-bg-color : The colour of the indicator shown when the background is grabbed by the user.
• active-bg-opacity : The opacity of the active background indicator.
• active-bg-size : The size of the active background indicator.
• selection-box-color : The background colour of the selection box used for drag selection.
• selection-box-border-color : The colour of the border on the selection box.
• selection-box-border-width : The size of the border on the selection box.
• selection-box-opacity : The opacity of the selection box.

Mappers

In addition to specifying the value of a property outright, the developer may also use a mapper to dynamically specify the property value.

data() specifies a direct mapping to an element's data field. For example, data(descr) would map a property to the value in an element's descr field in its data (i.e. ele.data("descr")). This is useful for mapping to properties like label text content (the content property).

mapData() specifies a linear mapping to an element's data field. For example, data(weight, 0, 100, blue, red) maps an element's weight to gradients between blue and red for weights between 0 and 100. An element with ele.data("weight") === 0 would be mapped to blue, for instance. Elements whose values fall outside of the specified range are mapped to the extremity values. In the previous example, an element with ele.data("weight") === -1 would be mapped to blue.

mapLayout() specifies a linear mapping like mapData() but uses special layout defined values (only supported for some layouts).

Events

Event object

Events passed to handler callbacks are similar to jQuery event objects in that they wrap native event objects, mimicking their API.

Fields:

• cy : a reference to the corresponding core instance
• cyTarget : indicates the element or core that first caused the event
• type : the event type string (e.g. "tap")
• namespace : the event namespace string (e.g. "foo" for "foo.tap")
• data : additional data object passed by .trigger()
• timeStamp : Unix epoch time of event

Fields for only user input device events:

• cyPosition : indicates the model position of the event
• cyRenderedPosition : indicates the rendered position of the event
• originalEvent : the original user input device event object

Event bubbling

All events that occur on elements get bubbled up to the core. You must take this into consideration when binding to the core so you can differentiate between events that happened on the background and ones that happened on elements. Use the eventObj.cyTarget field, which indicates the originator of the event (i.e. eventObj.cyTarget === cy || eventObj.cyTarget === someEle).

User input device events

These are normal browser events that you can bind to via Cytoscape.js. You can bind these events to the core and to collections.

• mousedown : when the mouse button is pressed
• mouseup : when the mouse button is released
• click : after mousedown then mouseup
• mouseover : when the cursor is put on top of the target
• mouseout : when the cursor is moved off of the target
• mousemove : when the cursor is moved somewhere on top of the target
• touchstart : when one or more fingers starts to touch the screen
• touchmove : when one or more fingers are moved on the screen
• touchend : when one or more fingers are removed from the screen

There are also some higher level events that you can use so you don't have to bind to different events for mouse-input devices and for touch devices.

• tapstart or vmousedown : normalised tap start event (either mousedown or touchstart)
• tapdrag or vmousemove : normalised move event (either touchmove or mousemove)
• tapend or vmouseup : normalised tap end event (either mouseup or touchend)
• tap or vclick : normalised tap event (either click, or touchstart followed by touchend without touchmove)
• taphold : normalised tap hold event
• cxttapstart : normalised right-click mousedown or two-finger tapstart
• cxttapend : normalised right-click mouseup or two-finger tapend
• cxttap : normalised right-click or two-finger tap
• cxtdrag : normalised mousemove or two-finger drag after cxttapstart but before cxttapend

Collection events

These events are custom to Cytoscape.js. You can bind to these events for collections.

• add : when an element is added to the graph
• remove : when an element is removed from the graph
• select : when an element is selected
• unselect : when an element is unselected
• lock : when an element is locked
• unlock : when an element is unlocked
• grab : when an element is grabbed by the mouse cursor or a finger on a touch input
• drag : when an element is grabbed and then moved
• free : when an element is freed (i.e. let go from being grabbed)
• position : when an element changes position
• data : when an element's data is changed
• style : when an element's style is changed

Graph events

These events are custom to Cytoscape.js, and they occur on the core.

• layoutstart : when a layout starts running
• layoutready : when a layout has set positions for all the nodes
• layoutstop : when a layout has finished running completely or otherwise stopped running
• load : when a new graph is loaded via initialisation or cy.load()
• ready : when a new instance of Cytoscape.js is ready to be interacted with
• initrender : when the first frame is drawn by the renderer (useful for synchronising with image exports etc)
• done : when a new instance of Cytoscape.js is ready to be interacted with and its initial layout has finished running
• pan : when the viewport is panned
• zoom : when the viewport is zoomed

Layouts

The function of a layout is to set the positions on the nodes in the graph. Layouts are extensions of Cytoscape.js such that it is possible for anyone to write a layout without modifying the library itself.

Several layouts are included with Cytoscape.js by default, and their options are described in the sections that follow with the default values specified. Note that you must set options.name to the name of the layout to specify which one you want to run.

Null

The null layout puts all nodes at (0, 0). It's useful for debugging purposes.

options = {
    name: 'null',

    ready: function(){}, // on layoutready
    stop: function(){} // on layoutstop
}

cy.layout( options );

Random

The random layout puts nodes in random positions within the viewport.

options = {
    name: 'random',

    ready: undefined, // callback on layoutready
    stop: undefined, // callback on layoutstop
    fit: true // whether to fit to viewport
};

cy.layout( options );

Preset

The preset layout puts nodes in the positions you specify manually.

options = {
    name: 'preset',

    fit: true, // whether to fit to viewport
    ready: undefined, // callback on layoutready
    stop: undefined, // callback on layoutstop
    positions: undefined, // map of (node id) => (position obj)
    zoom: undefined, // the zoom level to set (prob want fit = false if set)
    pan: undefined, // the pan level to set (prob want fit = false if set)
    padding: 30 // padding on fit
};

cy.layout( options );

Grid

The grid layout puts nodes in a well-spaced grid.

{
    name: 'grid',

    fit: true, // whether to fit the viewport to the graph
    padding: 30, // padding used on fit
    rows: undefined, // force num of rows in the grid
    columns: undefined, // force num of cols in the grid
    position: function( node ){}, // returns { row, col } for element
    ready: undefined, // callback on layoutready
    stop: undefined // callback on layoutstop
};

cy.layout( options );

Circle

The circle layout puts nodes in a circle.

options = {
    name: 'circle',

    fit: true, // whether to fit the viewport to the graph
    ready: undefined, // callback on layoutready
    stop: undefined, // callback on layoutstop
    rStepSize: 10, // the step size for increasing the radius if the nodes don't fit on screen
    padding: 30, // the padding on fit
    startAngle: 3/2 * Math.PI, // the position of the first node
    counterclockwise: false // whether the layout should go counterclockwise (true) or clockwise (false)
};

cy.layout( options );

Concentric

The concentric layout positions nodes in concentric circles, based on a metric that you specify to segregate the nodes into levels. This layout sets the concentric layout value based on your metric, which can be used with mapLayoutData().

    name: 'concentric',

    fit: true, // whether to fit the viewport to the graph
    ready: undefined, // callback on layoutready
    stop: undefined, // callback on layoutstop
    padding: 30, // the padding on fit
    startAngle: 3/2 * Math.PI, // the position of the first node
    counterclockwise: false, // whether the layout should go counterclockwise (true) or clockwise (false)
    minNodeSpacing: 10, // min spacing between outside of nodes (used for radius adjustment)
    height: undefined, // height of layout area (overrides container height)
    width: undefined, // width of layout area (overrides container width)
    concentric: function(){ // returns numeric value for each node, placing higher nodes in levels towards the centre
      return this.degree();
    },
    levelWidth: function(nodes){ // the variation of concentric values in each level
      return nodes.maxDegree() / 4;
    }

Breadthfirst

The breadthfirst layout puts nodes in a hierarchy, based on a breadthfirst traversal of the graph.

options = {
    name: 'breadthfirst',

    fit: true, // whether to fit the viewport to the graph
    ready: undefined, // callback on layoutready
    stop: undefined, // callback on layoutstop
    directed: false, // whether the tree is directed downwards (or edges can point in any direction if false)
    padding: 30, // padding on fit
    circle: false, // put depths in concentric circles if true, put depths top down if false
    roots: undefined, // the roots of the trees
    maximalAdjustments: 0 // how many times to try to position the nodes in a maximal way (i.e. no backtracking)
};

cy.layout( options );

Arbor

The arbor layout uses a force-directed physics simulation.

options = {
    name: 'arbor',

    liveUpdate: true, // whether to show the layout as it's running
    ready: undefined, // callback on layoutready 
    stop: undefined, // callback on layoutstop
    maxSimulationTime: 4000, // max length in ms to run the layout
    fit: true, // reset viewport to fit default simulationBounds
    padding: [ 50, 50, 50, 50 ], // top, right, bottom, left
    simulationBounds: undefined, // [x1, y1, x2, y2]; [0, 0, width, height] by default
    ungrabifyWhileSimulating: true, // so you can't drag nodes during layout

    // forces used by arbor (use arbor default on undefined)
    repulsion: undefined,
    stiffness: undefined,
    friction: undefined,
    gravity: true,
    fps: undefined,
    precision: undefined,

    // static numbers or functions that dynamically return what these
    // values should be for each element
    nodeMass: undefined, 
    edgeLength: undefined,

    stepSize: 1, // size of timestep in simulation

    // function that returns true if the system is stable to indicate
    // that the layout can be stopped
    stableEnergy: function( energy ){
      var e = energy; 
      return (e.max <= 0.5) || (e.mean <= 0.3);
    }
};


cy.layout( options );

Notes about arbor:

• For webworkers to work properly, you need to point your browser to a server URL (e.g. http://) rather than a local address (e.g. file://).
• Please note that the liveUpdate option is expensive, so if you are concerned about running time (e.g. for large graphs), you should set it to false.
• NB: You must reference the version of arbor.js included with Cytoscape.js in the <head> of your HTML document:

<head>
    ...

    <script src="arbor.js"></script>

    ...
</head>

Arbor does some automatic path finding because it uses web workers, and so it must be included this way. Therefore, you can not combine arbor.js with your other JavaScript files — as you probably would as a part of the minification of the scripts in your webapp.

CoSE

The cose (Compound Spring Embedder) layout uses a force-directed simulation to lay out compound graphs. It was implemented by Gerardo Huck as part of Google Summer of Code 2013 (Mentors: Max Franz, Christian Lopes, Anders Riutta, Ugur Dogrusoz).

Based on the article "A layout algorithm for undirected compound graphs" by Ugur Dogrusoz, Erhan Giral, Ahmet Cetintas, Ali Civril and Emek Demir.

options = {
    name: 'cose',

    // Called on `layoutready`
    ready               : function() {},

    // Called on `layoutstop`
    stop                : function() {},

    // Number of iterations between consecutive screen positions update (0 -> only updated on the end)
    refresh             : 0,

    // Whether to fit the network view after when done
    fit                 : true, 

    // Padding on fit
    padding             : 30, 


    // Whether to randomize node positions on the beginning
    randomize           : true,

    // Whether to use the JS console to print debug messages
    debug               : false,

    // Node repulsion (non overlapping) multiplier
    nodeRepulsion       : 10000,

    // Node repulsion (overlapping) multiplier
    nodeOverlap         : 10,

    // Ideal edge (non nested) length
    idealEdgeLength     : 10,

    // Divisor to compute edge forces
    edgeElasticity      : 100,

    // Nesting factor (multiplier) to compute ideal edge length for nested edges
    nestingFactor       : 5, 

    // Gravity force (constant)
    gravity             : 250, 

    // Maximum number of iterations to perform
    numIter             : 100,

    // Initial temperature (maximum node displacement)
    initialTemp         : 200,

    // Cooling factor (how the temperature is reduced between consecutive iterations
    coolingFactor       : 0.95, 

    // Lower temperature threshold (below this point the layout will end)
    minTemp             : 1
};

cy.layout( options );

Plugins

About plugins

Plugins are reusable UI widgets that can be used with Cytoscape.js in your webapps. Though Cytoscape.js does not require jQuery as a dependency, it has out-of-the-box compatibility with jQuery, and so it is natural that jQuery plugins be used in this manner.

Thus, a Cytoscape.js plugin is simply a jQuery plugin that is called on Cytoscape.js container and interacts with Cytoscape.js via its API.

Writing a plugin

Writing a jQuery plugin is a straightforward process, outlined in the jQuery plugin documentation. You can use the ready callback to get an instance of Cytoscape.js in your plugin code, assuming that the plugin is called on the Cytoscape.js container:

var $container = $(this); // `this` points to container inside plugin code
$container.cytoscape(function(){
    var cy = this; // now we have a reference to the core
});

You can then interact with the instance of Cytoscape.js in your plugin.

The jQuery Plugin Registry is where you will make your plugin available. You will probably want to prefix your plugin's name with "cytoscape" so it is clear that the plugin is for Cytoscape.js, rather than a generic jQuery plugin. Make sure to tag your plugin with "cytoscape.js" using the keywords field in your manifest file.

Downloads

Cytoscape.js plugins are available on the jQuery Plugin Registry under the "cytoscape.js" tag.

Core

The core object is your interface to the Cytoscape.js visualisation. It is your entry point to Cytoscape.js: All of Cytoscape.js's features are accessed through this object.

Initialisation

Script includes

To use Cytoscape.js in your HTML document:

<script src="cytoscape.js"></script>

Cytoscape.js uses the dimensions of your HTML DOM element container for layouts and rendering at initialisation. Thus, it is very important to place your CSS stylesheets in the <head> before any Cytoscape.js scripts. Otherwise, dimensions may be sporadically reported incorrectly, resulting in undesired behaviour.

To use Cytoscape.js in a CommonJS environment like Node.js:

var cytoscape = require('cytoscape');

To use Cytoscape.js with AMD/Require.js:

require(['cytoscape'], function(cytoscape){
  // ...
});

To install Cytoscape.js via Bower (in the terminal):

bower install cytoscape

Getting started

An instance of Cytoscape.js correponds to a graph. You can create an instance as follows:

cytoscape({
  container: document.getElementById('cy'),
  ready: function(){ console.log('ready') }
});

If you are running Cytoscape.js in Node.js or otherwise running it headlessly, you will not specify the container option. When running Cytoscape.js headlessly in the browser, you should specify options.renderer.name as "null" so that the default canvas renderer is not used to draw the graph. Outside of the browser (e.g. in Node.js), the null renderer is used by default.

If you've included jQuery on a HTML document, you can alternatively initialise Cytoscape.js on a HTML DOM element using the traditional jQuery style:

$("#cy").cytoscape({ // for some div with id 'cy'
  ready: function(){
    // you can access the core object API through cy

    console.log("ready");
  }

  // , ...
});

This initialises Cytoscape.js and returns back to you your instance of jQuery. You can continue using jQuery functions, as usual for a jQuery plugin.

For example,

$("#cy").cytoscape(options)
  .css("background", "red")
  .css("border-color", "black"); // can use jquery functions on 'cy' div

Because this style doesn't give you access to the cy object outside of the callback function, there is an option to get the cy object from a jQuery selector.

$("#cy").cytoscape(options);
var cy = $("#cy").cytoscape("get"); // now we have a global reference to `cy`

The ready callback

All of your code that uses the core object API, i.e. through the cy object in the examples above, must do so after the ready callback function has executed. You can specify the ready callback in the initialisation options, outlined in the following section.

Because the ready event may occur before you can bind to the core, you can use this shortcut to spread your code among several JavaScript files without having to call a bunch of global functions in options.ready.

NB: You should never call layouts, load elements into the graph, etc on ready. The graph is still performing the initial load at that point, so you can't modify things like that. You should use the initialisation options to properly set the elements and layout you want to use.

// in foo.js
$(function(){ // on jquery ready

  $("#cy").cytoscape(function(eventObject){ // on Cytoscape.js ready on the `cy` div
    // this code executes when Cytoscape.js is ready even though we
    // don't actually initialise Cytoscape.js on the `cy` div until
    // bar.js is loaded

    var cy = this; // `this` holds the reference to the core object

    console.log("Ready, Freddie!");
  });

});

// in bar.js (should be after foo.js in your js includes)
$(function(){ // on jquery ready
  $("#cy").cytoscape(options);
});

Initialisation options

An instance of Cytoscape.js has a number of options that can be set on initialisation. They are outlined below with their default values.

$("#cy").cytoscape({
  selectionType: (isTouchDevice ? 'additive' : 'single'),
  layout: { name: 'grid' /* , ... */ },
  zoom: 1,
  minZoom: 1e-50,
  maxZoom: 1e50,
  zoomingEnabled: true,
  userZoomingEnabled: true,
  pan: { x: 0, y: 0 },
  panningEnabled: true,
  hideEdgesOnViewport: false,
  renderer: { /* ... */ },
  style: undefined /* ... */,
  ready: function(evt){ /* ... */ },
  initrender: function(evt){ /* ... */ },
  elements: [ /* ... */ ]
});

selectionType : A string indicating the selection behaviour from user input. By default, this is set automatically for you based on the type of input device detected. On touch devices, "additive" is default — a new selection made by the user adds to the set of currenly selected elements. On mouse-input devices, "single" is default — a new selection made by the user becomes the entire set of currently selected elements (i.e. the previous elements are unselected).

• renderer.hideEdgesOnViewport : When set to true, the renderer does not render edges while the viewport is being manipulated. This makes panning and zooming more responsive for large graphs.

showOverlay : A boolean, indicating whether you'd like to see the "cytoscape.js" overlay in the bottom right of the viewport (default true).

layout : A plain object that specifies layout options. Which layout is initially run is specified by the name field. Refer to a layout's documentation for the options it supports, as described in cy.layout().

zoom : The initial zoom level of the graph. Make sure to disable viewport manipulation options, such as fit, in your layout so that it is not overridden when the layout is applied. You can set options.minZoom and options.maxZoom to set restrictions on the zoom level.

zoomingEnabled : Whether zooming the graph is enabled, both by user events and programmatically.

userZoomingEnabled : Whether user events (e.g. mouse wheel, pinch-to-zoom) are allowed to zoom the graph. Programmatic changes to zoom are unaffected by this option.

pan : The initial panning position of the graph. Make sure to disable viewport manipulation options, such as fit, in your layout so that it is not overridden when the layout is applied.

panningEnabled : Whether panning the graph is enabled, both by user events and programmatically.

userPanningEnabled : Whether user events (e.g. dragging the graph background) are allowed to pan the graph. Programmatic changes to pan are unaffected by this option.

• hideEdgesOnViewport : When set to true, the renderer does not render edges while the viewport is being manipulated. This makes panning and zooming more responsive for large graphs.

renderer : A plain object containing options for the renderer to be used. The options.renderer.name field specifies which renderer is used. You need not specify anything for the renderer option, unless you want to specify one of the rendering options below:

• renderer.name : The name of the renderer to use. By default, the 'canvas' renderer is used. If you build and register your own renderer, then you can specify its name here.

style : The stylesheet used to style the document.

For example:

$("#cy").cytoscape({
  /* ... */

  style: cytoscape.stylesheet()
    .selector('node')
      .css({
        'background-color': 'red',
        'border-color': '#ffff00'
      })
    .selector('edge')
      .css({
        'line-color': 'blue'
      })

  /* ... */
});

ready : A callback function that is called when Cytoscape.js is ready to be interacted with. You can not call functions on the cy object before this function executes.

initrender : A callback function that is called when Cytoscape.js has rendered its first frame. This is useful for grabbing screenshots etc after initialision, but in general you should use ready instead.

elements : An array of elements specified as plain objects.

For example:

$('#cy').cytoscape({
  /* ... */

  elements: [
    {
      data: { id: 'foo' }, 
      group: 'nodes'
    },

    {
      data: { id: 'bar' },
      group: 'nodes'
    },

    {
      data: { weight: 100 }, // elided id => autogenerated id 
      group: 'nodes',
      position: {
        x: 100,
        y: 100
      },
      classes: 'className1 className2',
      selected: true,
      selectable: true,
      locked: true,
      grabbable: true
    },

    {
      data: { id: 'baz', source: 'foo', target: 'bar' },
      group: 'edges'
    }
  ]

  /* ... */
});

You can alternatively specify separate arrays indexed in a object by the group names so you don't have to specify the group property over and over for each element:

$('#cy').cytoscape({
  /* ... */

  elements: {
    nodes: [
      { data: { id: 'foo' } }, // NB no group specified

      { data: { id: 'bar' } },

      {
        data: { weight: 100 }, // elided id => autogenerated id 
        group: 'nodes',
        position: {
          x: 100,
          y: 100
        },
        classes: 'className1 className2',
        selected: true,
        selectable: true,
        locked: true,
        grabbable: true
      }
    ],

    edges: [
      { data: { id: 'baz', source: 'foo', target: 'bar' } } // NB no group specified
    ]
  }

  /* ... */
});

Graph manipulation

Viewport manipulation

Events

Visuals

Export

Collection

A collection contains a set of nodes and edges. Calling a function applies the function to all elements in the collection. When reading values from a collection, eles.data() for example, the value of the first element in the collection is returned. This follows the jQuery convention. For example:

var weight = cy.nodes().data("weight");

console.log( cy.nodes()[0].data("weight") + ' == ' + weight ); // weight is the first ele's weight

You can insure that you're reading from the element you want by using a selector to narrow down the collection to one element (i.e. eles.size() === 1) or the eles.eq() function.

Graph manipulation

Data

Metadata

Position & dimensions

Selection

Events

Style

Animation

Comparison

Iteration

Building & filtering

Traversing

Algorithms

Compound nodes

Architecture

Cytoscape.js uses an event-driven model with a core API. The core has several extensions, each of which is notified of events by the core, as needed. Extensions modify the elements in the graph and notify the core of any changes.

The client application accesses Cytoscape.js solely through the core. Clients do not access extensions directly, apart from the case where a client wishes to write his own custom extension.

The following diagram summarises the extensions of Cytoscape.js, which are discussed in further detail later in this documentation.

Extensions

API

The extensions API is very simple, following this format:

cytoscape( type, name, extension );

The value of type can take on the following values:

• core : The extension adds a core function.
• collection : The extension adds a collection function.
• layout : The extension registers a layout prototype.
• renderer : The extension registers a renderer prototype.

The name argument indicates the name of the extension, which should be a single word in lower case.

Functions

Functions should be chainable, unless they need to return some other value. To make a function chainable, make sure to return this; at the end of your function.

Here is an example collection function:

cytoscape('collection', 'forEach', function( fn ){
  for( var i = 0; i < this.length; i++ ){
    fn.apply( this[i], [ i, this[i] ] );
  }

  return this; // chainability
});

cy.elements().forEach(function(){
  console.log( 'forEach ' + this.id() );
});

Layouts

A layout modifies the positions of nodes in the graph. A layout has number of options, which are specific to the particular layout.

Layouts may be blocking if they are fast — meaning you can execute your code to run after the layout on the line following the layout call. Layouts may also be continuous, in which case, callback functions are provided to know when the layout finishes.

A layout has two events that must be triggereed on the core, including layoutready and layoutstop:

• layoutready : This is triggered on the core (via cy.trigger('layoutready')) when the layout has set the positions on every node at least once. This lets the core know that the nodes now have valid positions and can be rendered. It is important to trigger layoutready on continuous layouts so that the nodes are shown moving. For blocking (non-continous) layouts, layoutready can just be triggered after the layout is done but before layoutstop.

• layoutstop : This is triggered on the core (via cy.trigger('layoutstop')) when the layout has finished. It should be triggered after layoutready. The layout should not change node positions after triggering layoutstop.

For an example layout, please refer to the null layout source code. The layout just sets each node to position (0, 0), and it is well documented. The Arbor layout is a good example of a continuous layout.

Renderers

For an example renderer, please refer to the canvas renderer.

The API of the renderer follows the actor model, and so it has a single main entry point, the notify() function. The core uses the notify() function to send event objects to the renderer. The format of the event object is as follows:

• event.type : A string containing the name of the event that has occured.
• event.collection : A collection of elements associated with the event.

If you're interested in writing a custom renderer for Cytoscape.js, please file an issue for more help if needed.