Cytoscape.js
Demos
Introduction
Factsheet
- A fully featured graph library written in pure JS
- Permissive open source license (MIT)
- Designed for users first, for both frontfacing app usecases and developer usecases
- Highly optimised
- Compatible with
- All modern browsers (At least ES5 and canvas support are required; feature detection is used for optional performance enhancements)
- CommonJS/Node.js
- AMD/Require.js
- jQuery
- npm
- Bower
- Meteor/Atmosphere
- The R language via RCyjs
- Supports rendering images of graphs on Node.js with Cytosnap
- Has a full suite of unit tests that can be run in the browser or the terminal
- Documentation includes live code examples, doubling as an interactive requirements specification; example graphs may also be freely modified in your browser’s JS console
- Fully serialisable and deserialisable via JSON
- Uses layouts for automatically or manually positioning nodes
- Supports selectors for terse filtering and graph querying
- Uses stylesheets to separate presentation from data in a rendering agnostic manner
- Abstracted and unified touch events on top of a familiar event model
- Builtin support for standard gestures on both desktop and touch
- Chainable for convenience
- Supports functional programming patterns
- Supports set theory operations
- Includes graph theory algorithms, from BFS to PageRank
- Animatable graph elements and viewport
- Fully extendable (and extensions can be autoscaffolded for you)
- Well maintained, with only a sliver of active bug time (i.e. minimised time to bugfix)
- Listed by Zenodo for per-version DOIs
- Listed by OMIC Tools
- Used by
- Active Value Advisors : How-4
- Agile Protein Interactomes DataServer
- Aras
- Ben-Gurion University of the Negev
- DiffNet
- TissueNet
- BioGRID
- BlueSail CRM
- Classcraft
- Cray Inc.
- CyberSift
- CyNetShare
- DARPA
- Duo Labs : CloudMapper
- dSysMap
- Elsevier
- Excel : GIGRAPH
- Ganister
- GCHQ : Gaffer
- GeneMANIA
- Graphlytic
- ICSI Haystack Project
- InfoTrack
- The Kanji Map
- Musicalized
- NDEx
- OHDSI
- Pathway Commons
- py2cytoscape
- Rezza
- Sainsbury Laboratory : PINet
- Southwest Harbor Public Library, Maine : Digital Archive : AvantRelationships
- Sotera Defense Solutions, Inc. : Graphene
- Steemit
- Stringify
- Threat Crowd
- Trace
- University of Cambridge : Intermine
- University of Leipzig, Institute for Medical Informatics, Statistics and Epidemiology (IMISE) : SNIK research project
- University of Maryland : Center for Bioinformatics and Computational Biology : MetagenomeScope
- University of Southern California, San Diego : Visualization of structurally related compounds in Mass Spectrometry with Molecular Networks at GNPS
- Virginia Tech T. M. Murali’s Research Group : GraphSpace
- Visual Interaction GmbH
About
Cytoscape.js is an open-source graph theory (a.k.a. network) library written in JS. 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 app, 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 many 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 created at the Donnelly Centre at the University of Toronto. It is the successor of Cytoscape Web.
Packages
- npm :
npm install cytoscape
- bower :
bower install cytoscape
- jspm :
jspm install npm:cytoscape
- meteor :
npm install cytoscape
Releases
- 3.2
- 3.1
- 3.0
- 2.7
- 2.6
- 2.5
- 2.4
- 2.3
- 2.2
- 2.1
- 2.0
Citation
To cite Cytoscape.js in a paper, please cite the Oxford Bioinformatics issue:
Cytoscape.js: a graph theory library for visualisation and analysis
Franz M, Lopes CT, Huck G, Dong Y, Sumer O, Bader GD
Bioinformatics (2016) 32 (2): 309-311 first published online September 28, 2015 doi:10.1093/bioinformatics/btv557 (PDF)
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
Graph model
Cytoscape.js supports many different graph theory usecases. It supports directed graphs, undirected graphs, mixed graphs, loops, multigraphs, compound graphs (a type of hypergraph), and so on.
We are regularly making additions and enhancements to the library, and we gladly accept feature requests and pull requests.
Architecture & API
There are two components in the architecture that a developer need concern himself in order to use Cytoscape.js, the core (i.e. a graph instance) 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. 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.
Note that a collection is immutable by default, meaning that the set of elements within a collection can not be changed. The API returns a new collection with different elements when necessary, instead of mutating the existing collection. This allows the developer to safely use set theory operations on collections, use collections functionally, and so on. Note that because a collection is just a list of elements, it is inexpensive to create new collections.
For very performance intensive code, a collection can be treated as mutable with eles.merge()
and eles.unmerge()
. Most apps should never need these functions.
Functions
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:
Shorthand | 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 |
layout | a layout |
ani | an animation |
By default, a function returns a reference back to the calling object to allow for 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.
Object ownership
When passing objects to Cytoscape.js for creating elements, animations, layouts, etc., the objects are considered owned by Cytoscape. Objects like elements have several levels to them, and doing deep copies of those objects every time they are passed to Cytoscape creates additional expense. When desired, the dev can copy objects manually before passing them to Cytoscape. However, copying is not necessary for most developers most of the time.
Gestures
Cytoscape.js supports several gestures:
- Grab and drag background to pan : touch & desktop
- Pinch to zoom : touch & desktop (with supported trackpad)
- Mouse wheel to zoom : desktop
- Two finger trackpad up or down to zoom : desktop
- Tap to select : touch & desktop
- Tap background to unselect : desktop
- Taphold background to unselect : desktop & touch
- Multiple selection via modifier key (shift, command, control, alt) + tap : desktop
- Box selection : touch (three finger swipe) & desktop (modifier key + mousedown then drag)
- Grab and drag nodes : touch & desktop
All gesture actions can be controlled by the dev, toggling them on or off whenever needed.
Position
A node’s position refers to the centre point of its body.
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. Numeric style property values are specified in model co-ordinates, e.g. an node with width 20px will be 20 pixels wide at zoom 1.
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. The model position and rendered position are the same at zoom 1 and pan (0, 0).
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. Panning is always measured in rendered coordinates.
In this documentation, “position” refers to model position unless otherwise stated.
A node’s position can be set manually, or it can be set automatically using a layout. Because the positions of two nodes influence the lengths of the edges in between them, a layout effectively sets edge lengths.
Elements JSON
Examples are given that outline format of the elements JSON used to load elements into Cytoscape.js:
cytoscape({
container: document.getElementById('cy'),
elements: [
{ // node n1
group: 'nodes', // 'nodes' for a node, 'edges' for an edge
// NB the group field can be automatically inferred for you but specifying it
// gives you nice debug messages if you mis-init elements
data: { // element data (put json serialisable dev data here)
id: 'n1', // mandatory (string or number) id for each element, assigned automatically on undefined
parent: 'nparent', // indicates the compound node parent id; not defined => no parent
},
// scratchpad data (usually temp or nonserialisable data)
scratch: {
_foo: 'bar' // app fields prefixed by underscore; extension fields unprefixed
},
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
},
{ // node n2
data: { id: 'n2' },
renderedPosition: { x: 200, y: 200 } // can alternatively specify position in rendered on-screen pixels
},
{ // node n3
data: { id: 'n3', parent: 'nparent' },
position: { x: 123, y: 234 }
},
{ // node nparent
data: { id: 'nparent', position: { x: 200, y: 100 } }
},
{ // edge e1
data: {
id: 'e1',
// inferred as an edge because `source` and `target` are specified:
source: 'n1', // the source node id (edge comes from this node)
target: 'n2' // the target node id (edge goes to this node)
}
}
],
layout: {
name: 'preset'
},
// so we can see the ids
style: [
{
selector: 'node',
style: {
'content': 'data(id)'
}
}
]
});
Compound nodes
Compound nodes are an addition to the traditional graph model. A compound node contains a number of child nodes, similar to how a HTML DOM element can contain a number of child elements.
Compound nodes are specified via the parent
field in an element’s data
. Similar to the source
and target
fields of edges, the parent
field is immutable: A node’s parent can be specified when the node is added to the graph, and after that point, this parent-child relationship is immutable. However, you can effectively move child nodes via eles.move()
.
A compound parent node does not have independent dimensions (position and size), as those values are automatically inferred by the positions and dimensions of the descendant nodes.
As far as the API is concerned, compound nodes are treated just like regular nodes — except in explicitly compound functions like node.parent()
. This means that traditional graph theory functions like eles.dijkstra()
and eles.neighborhood()
do not make special allowances for compound nodes, so you may need to make different calls to the API depending on your usecase.
For instance:
var a = cy.$('#a'); // assume a compound node
// the neighbourhood of `a` contains directly connected elements
var directlyConnected = a.neighborhood();
// you may want everything connected to its descendants instead
// because the descendants "belong" to `a`
var indirectlyConnected = a.add( a.descendants() ).neighborhood();
Getting started
This section will familiarise you with the basic steps necessary to start using Cytoscape.js.
Including Cytoscape.js
If you are using a HTML environment, then include Cytoscape.js in a <script>
tag, e.g.:
<script src="cytoscape.js"></script>
To use Cytoscape.js from a CDN, use CDNJS. Please do not hotlink to copies of Cytoscape.js from the documentation — they’re just for the demos.
Note that 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-related code. Otherwise, dimensions may be sporadically reported incorrectly, resulting in undesired behaviour.
Your stylesheet may include something like this (assuming a DOM element with ID cy
is used as the container):
#cy {
width: 300px;
height: 300px;
display: block;
}
To install Cytoscape.js via npm:
npm install cytoscape
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:
bower install cytoscape
To install Cytoscape.js via Meteor/Atmosphere:
npm install cytoscape
Cytoscape.js supports environments with ES5 or newer, as it is transpiled by Babel and it uses only basic features of the standard library. Feature detection is used for optional features that improve performance. However, a future version of Cytoscape.js may require a more up-to-date version of the standard library. You may want to use babel-polyfill
or core-js
if you want to support old browsers in future.
Initialisation
An instance of Cytoscape.js corresponds to a graph. You can create an instance as follows:
var cy = cytoscape({
container: document.getElementById('cy') // container to render in
});
You can pass a jQuery instance as the container
for convenience:
var cy = cytoscape({
container: $('#cy')
});
If you are running Cytoscape.js in Node.js or otherwise running it headlessly, you will not specify the container
option. In implicitly headless environments like Node.js, an instance is automatically headless. To explicitly run a headless instance (e.g. in the browser) you can specify options.headless
as true
.
Specifying basic options
For visualisation, the container
, elements
, style
, and layout
options usually should be set:
var cy = cytoscape({
container: document.getElementById('cy'), // container to render in
elements: [ // list of graph elements to start with
{ // node a
data: { id: 'a' }
},
{ // node b
data: { id: 'b' }
},
{ // edge ab
data: { id: 'ab', source: 'a', target: 'b' }
}
],
style: [ // the stylesheet for the graph
{
selector: 'node',
style: {
'background-color': '#666',
'label': 'data(id)'
}
},
{
selector: 'edge',
style: {
'width': 3,
'line-color': '#ccc',
'target-arrow-color': '#ccc',
'target-arrow-shape': 'triangle'
}
}
],
layout: {
name: 'grid',
rows: 1
}
});
Next steps
Now that you have a core (graph) instance with basic options, explore the core API. It’s your entry point to all the features in Cytoscape.js.
If you have code questions about Cytoscape.js, please feel free to post your question to Stackoverflow.
Core
The core object is your interface to a graph. It is your entry point to Cytoscape.js: All of the library’s features are accessed through this object.
Initialisation
Initialisation
A graph can be created as follows:
var cy = cytoscape({ /* options */ });
You can initialise the core without any options. If you want to use Cytoscape as a visualisation, then a container
DOM element is required, e.g.:
var cy = cytoscape({
container: document.getElementById('cy')
});
Note that in order to guarantee custom font usage, the fonts in question must be loaded before Cytoscape is initialised.
The following sections go over the options in more detail.
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.
Note that everything is optional. By default, you get an empty graph with the default stylesheet. Environments outside the browser (e.g. Node.js) are automatically set as headless for convenience.
var cy = cytoscape({
// very commonly used options
container: undefined,
elements: [ /* ... */ ],
style: [ /* ... */ ],
layout: { name: 'grid' /* , ... */ },
// initial viewport state:
zoom: 1,
pan: { x: 0, y: 0 },
// interaction options:
minZoom: 1e-50,
maxZoom: 1e50,
zoomingEnabled: true,
userZoomingEnabled: true,
panningEnabled: true,
userPanningEnabled: true,
boxSelectionEnabled: false,
selectionType: 'single',
touchTapThreshold: 8,
desktopTapThreshold: 4,
autolock: false,
autoungrabify: false,
autounselectify: false,
// rendering options:
headless: false,
styleEnabled: true,
hideEdgesOnViewport: false,
hideLabelsOnViewport: false,
textureOnViewport: false,
motionBlur: false,
motionBlurOpacity: 0.2,
wheelSensitivity: 1,
pixelRatio: 'auto'
});
Very commonly used options
container
: A HTML DOM element in which the graph should be rendered. This is unspecified if Cytoscape.js is run headlessly. The container is expected to be an empty div; the visualisation owns the div.
elements
: An array of elements specified as plain objects. For convenience, this option can alternatively be specified as a promise that resolves to the elements JSON.
style
: The stylesheet used to style the graph. For convenience, this option can alternatively be specified as a promise that resolves to the stylesheet.
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. If you want to specify your node positions yourself in your elements JSON, you can use the preset
layout — by default it does not set any positions, leaving your nodes in their current positions (e.g. specified in options.elements
at initialisation time).
Initial viewport state
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.
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.
Interaction options
minZoom
: A minimum bound on the zoom level of the graph. The viewport can not be scaled smaller than this zoom level.
maxZoom
: A maximum bound on the zoom level of the graph. The viewport can not be scaled larger than this 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.
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.
boxSelectionEnabled
: Whether box selection (i.e. drag a box overlay around, and release it to select) is enabled. If enabled, the user must taphold to pan the graph.
selectionType
: A string indicating the selection behaviour from user input. For 'additive'
, a new selection made by the user adds to the set of currently selected elements. For 'single'
, a new selection made by the user becomes the entire set of currently selected elements (i.e. the previous elements are unselected).
touchTapThreshold
& desktopTapThreshold
: A nonnegative integer that indicates the maximum allowable distance that a user may move during a tap gesture, on touch devices and desktop devices respectively. This makes tapping easier for users. These values have sane defaults, so it is not advised to change these options unless you have very good reason for doing so. Larger values will almost certainly have undesirable consequences.
autoungrabify
: Whether nodes should be ungrabified (not grabbable by user) by default (if true
, overrides individual node state).
autolock
: Whether nodes should be locked (not draggable at all) by default (if true
, overrides individual node state).
autounselectify
: Whether nodes should be unselectified (immutable selection state) by default (if true
, overrides individual element state).
Rendering options
headless
: A convenience option that initialises the instance to run headlessly. You do not need to set this in environments that are implicitly headless (e.g. Node.js). However, it is handy to set headless: true
if you want a headless instance in a browser.
styleEnabled
: A boolean that indicates whether styling should be used. For headless (i.e. outside the browser) environments, display is not necessary and so neither is styling necessary — thereby speeding up your code. You can manually enable styling in headless environments if you require it for a special case. Note that it does not make sense to disable style if you plan on rendering the graph.
hideEdgesOnViewport
: A rendering hint that when set to true
makes the renderer not render edges while the viewport is being manipulated. This makes panning, zooming, dragging, et cetera more responsive for large graphs. This option is now largely moot, as a result of performance enhancements.
textureOnViewport
: A rendering hint that when set to true
makes the renderer use a texture during panning and zooming instead of drawing the elements, making large graphs more responsive. This option is now largely moot, as a result of performance enhancements.
motionBlur
: A rendering hint that when set to true
makes the renderer use a motion blur effect to make the transition between frames seem smoother. This can increase the perceived performance for a large graphs. This option is now largely moot, as a result of performance enhancements.
motionBlurOpacity
: When motionBlur: true
, this value controls the opacity of motion blur frames. Higher values make the motion blur effect more pronounced. This option is now largely moot, as a result of performance enhancements.
wheelSensitivity
: Changes the scroll wheel sensitivity when zooming. This is a multiplicative modifier. So, a value between 0 and 1 reduces the sensitivity (zooms slower), and a value greater than 1 increases the sensitivity (zooms faster). This option is set to a sane value that works well for mainstream mice (Apple, Logitech, Microsoft) on Linux, Mac, and Windows. If the default value seems too fast or too slow on your particular system, you may have non-default mouse settings in your OS or a niche mouse. You should not change this value unless your app is meant to work only on specific hardware. Otherwise, you risk making zooming too slow or too fast for most users.
pixelRatio
: Overrides the screen pixel ratio with a manually set value (1.0
recommended, if set). This can be used to increase performance on high density displays by reducing the effective area that needs to be rendered, though this is much less necessary on more recent browser releases. If you want to use the hardware’s actual pixel ratio, you can set pixelRatio: 'auto'
(default).
Graph manipulation
Add elements to the graph and return them.
Add a specified element to the graph.
- eleObj
A plain object that specifies the element.
Add the specified elements to the graph.
- eleObjs
An array of elements specified by plain objects.
Details
If plain element objects are used, then the same format used at initialisation must be followed.
If a collection of existing elements is specified to a different core instance, then copies of those elements are added, which allows for elements to be effectively transferred between instances of Cytoscape.js.
Examples
Add a node from a plain object.
cy.add({
group: "nodes",
data: { weight: 75 },
position: { x: 200, y: 200 }
});
Add nodes and edges to the graph as plain objects:
// can use reference to eles later
var eles = cy.add([
{ group: "nodes", data: { id: "n0" }, position: { x: 100, y: 100 } },
{ group: "nodes", data: { id: "n1" }, position: { x: 200, y: 200 } },
{ group: "edges", data: { id: "e0", source: "n0", target: "n1" } }
]);
Remove elements from the graph and return them.
Remove elements in the graph matching the specified selector.
- selector
Elements matching this selector are removed.
Details
Note that removing a node necessarily removes its connected edges.
Though the elements specified to this function are removed from the graph, they may still exist in memory. However, almost all functions will not work on removed elements. For example, the eles.neighborhood()
function will fail for a removed element: An element outside of the context of the graph can not have a neighbourhood defined. In effect, removed elements just exist so you can restore them back to the originating core instance or to a new instance.
Examples
Remove an element:
var j = cy.$("#j");
cy.remove( j );
Remove a collection:
var collection = cy.elements("node[weight > 50]");
cy.remove( collection );
Remove elements matching a selector:
cy.remove("node[weight > 50]"); // remove nodes with weight greater than 50
Return a new, empty collection.
Get an empty collection.
Details
This function is useful for building up collections.
Examples
Keep a collection of nodes that have been clicked:
var collection = cy.collection();
cy.nodes().on("click", function(){
collection = collection.add(this);
});
cy.$id()
,Get an element from its ID in a very performant way.
- id
The ID of the element to get.
Examples
cy.getElementById('j');
Using the shorter alias:
cy.$id('j');
Get elements in the graph matching a selector or a filter function.
Get elements in the graph matching the specified selector.
- selector
The selector the elements should match.
Get elements in the graph matching the specified selector.
- selector
The selector the elements should match.
Get nodes in the graph matching the specified selector.
- selector
The selector the nodes should match.
Get edges in the graph matching the specified selector.
- selector
The selector the edges should match.
Get elements in the graph matching the specified selector.
- selector
The selector the elements should match.
Get elements in the graph matching the specified filter function.
Details
If no elements in the graph match the selector, an empty collection is returned.
The function cy.$()
acts as an alias to cy.filter()
: It’s just convenient to save you typing. It is analogous to the jQuery $
alias used to search the document
Examples
Get nodes with weight greater than 50:
cy.nodes("[weight>50]");
Get edges with source node n0
:
cy.edges("[source='j']");
Get all nodes and edges with weight greater than 50:
cy.elements("[weight>50]");
cy.filter("[weight>50]"); // works the same as the above line
Get nodes with weight greater than 50 with a filter function:
cy.filter(function(element, i){
if( element.isNode() && element.data("weight") > 50 ){
return true;
}
return false;
});
Allow for manipulation of elements without triggering multiple style calculations or multiple redraws.
- function()
A callback within which you can make batch updates to elements.
Starts batching manually (useful for asynchronous cases).
Ends batching manually (useful for asynchronous cases).
Details
Normally, when you modify elements, each modification can trigger a style calculation and a redraw — depending on timing for a redraw. For example, the following will cause two style calculations and at least one draw:
cy.$('#j')
.data('weight', '70') // style update
.addClass('funny') // style update AGAIN
.removeClass('serious') // style update YET AGAIN
// at least 1 redraw here
// possibly 3 total depending on speed of above operations
// (for one ele almost certainly 1 redraw, but consider many eles)
;
This is not a problem for a handful of operations on a handful of elements, but for many operations on many elements you end up with redundant style calculations and probably redundant redraws. In the worst case, you have eles.length * numOps
style updates and redraws — and both style updates and redraws can be expensive. In the worst case when using cy.batch()
, you limit the style updates to eles.length
and you limit the redraws to just one.
Thus, this function is useful for making many changes to elements at once. When the specified callback function is complete, only elements that require it have their style updated and the renderer makes at most a single redraw.
This makes for very efficient modifications to elements, but it has some caveats. While inside the batch callback,
- you can not reliably read element style or dimensions (it may have changed, or computed values may be out of date),
- you probably do not want to use
eles.style()
et cetera because they force a style bypass rather than a recalculation.
Examples
Synchronous style:
cy.batch(function(){
cy.$('#j')
.data('weight', '70')
.addClass('funny')
.removeClass('serious')
;
});
Asynchronous style:
cy.startBatch();
cy.$('#j')
.data('weight', '70')
.addClass('funny')
.removeClass('serious')
;
cy.endBatch();
A convenience function to explicitly destroy the instance.
Details
The cy.destroy()
function is not necessary but can be convenient in some cases. It cleans up references and rendering loops such that the memory used by an instance can be garbage collected.
If you remove the container DOM element from the page, then the instance is cleaned up automatically. Similarly, calling cy.destroy()
does this cleanup and removes all the container’s children from the page.
When running Cytoscape.js headlessly, using cy.destroy()
is necessary only if you’ve explicitly enabled style functionality.
To drop the memory used by an instance, it is necessary to drop all of your own references to that instance so it can be garbage collected.
Set or get scratchpad data, where temporary or non-JSON data can be stored. App-level scratchpad data should use namespaces prefixed with underscore, like '_foo'
. This is analogous to the more common ele.scratch()
but for graph global data.
Get the entire scratchpad object for the core.
Get the scratchpad at a particular namespace.
- namespace
A namespace string.
Set the scratchpad at a particular namespace.
- namespace
A namespace string.
- value
The value to set at the specified namespace.
Remove scratchpad data. You should remove scratchpad data only at your own namespaces. This is analogous to the more common ele.removeScratch()
but for graph global data.
Remove the scratchpad data at a particular namespace.
- namespace
A namespace string.
Events
cy.bind()
, cy.listen()
, cy.addListener()
,Bind to events that occur in the graph.
Examples
Bind to events that bubble up from elements matching the specified node
selector:
cy.on('tap', 'node', function(evt){
var node = evt.target;
console.log( 'tapped ' + node.id() );
});
Bind to all tap events that the core receives:
cy.on('tap', function(event){
// target holds a reference to the originator
// of the event (core or element)
var evtTarget = event.target;
if( evtTarget === cy ){
console.log('tap on background');
} else {
console.log('tap on some element');
}
});
cy.pon()
,Get a promise that is resolved with the first of any of the specified events emitted on the graph.
Examples
cy.pon('tap').then(function( event ){
console.log('tap promise fulfilled');
});
Bind to events that occur in the graph, and run the handler only once.
Examples
cy.one('tap', 'node', function(){
console.log('tap!');
});
cy.$('node').eq(0).trigger('tap'); // tap!
cy.$('node').eq(1).trigger('tap'); // nothing b/c already tapped
cy.off()
, cy.unbind()
, cy.unlisten()
,Remove event handlers.
Examples
For all handlers:
cy.on('tap', function(){ /* ... */ });
// unbind all tap handlers, including the one above
cy.removeListener('tap');
For a particular handler:
var handler = function(){
console.log('called handler');
};
cy.on('tap', handler);
var otherHandler = function(){
console.log('called other handler');
};
cy.on('tap', otherHandler);
// just unbind handler
cy.removeListener('tap', handler);
cy.trigger()
,Emit one or more events.
- events
A space separated list of event names to emit.
- extraParams [optional]
An array of additional parameters to pass to the handler.
Examples
cy.on('tap', function(evt, f, b){
console.log('tap', f, b);
});
cy.emit('tap', ['foo', 'bar']);
Run a callback as soon as the graph becomes ready (i.e. data loaded and initial layout completed). If the graph is already ready, then the callback is called immediately. If data is loaded synchronously and the layout used is discrete/synchronous/unanimated/unspecified, then you don't need cy.ready()
.
- function(event)
The callback run as soon as the graph is ready, inside which
event.cy
refers to the core (cy
).- event
The
ready
event.
- event
Viewport manipulation
Get the HTML DOM element in which the graph is visualised. A nully value is returned if the instance is headless.
cy.centre()
,Pan the graph to the centre of a collection.
Centre on all elements in the graph.
Details
If no collection is specified, then the graph is centred on all nodes and edges in the graph.
Examples
Centre the graph on node j
:
var j = cy.$("#j");
cy.center( j );
Pan and zooms the graph to fit to a collection.
Fit to all elements in the graph.
Fit to the specified elements.
- eles [optional]
The collection to fit to.
- padding [optional]
An amount of padding (in pixels) to have around the graph
Details
If no collection is specified, then the graph is fit to all nodes and edges in the graph.
Examples
Fit the graph on nodes j
and e
:
cy.fit( cy.$('#j, #e') );
Reset the graph to the default zoom level and panning position.
Resets the zoom and pan.
Details
This resets the viewport to the origin (0, 0) at zoom level 1.
Examples
setTimeout( function(){
cy.pan({ x: 50, y: -100 });
}, 1000 );
setTimeout( function(){
cy.zoom( 2 );
}, 2000 );
setTimeout( function(){
cy.reset();
}, 3000 );
Get or set the panning position of the graph.
Get the current panning position.
Set the current panning position.
- renderedPosition
The rendered position to pan the graph to.
Details
This function pans the graph viewport origin to the specified rendered pixel position.
Examples
Pan the graph to (100, 100) rendered pixels.
cy.pan({
x: 100,
y: 100
});
console.log( cy.pan() ); // prints { x: 100, y: 100 }
Relatively pan the graph by a specified rendered position vector.
- renderedPosition
The rendered position vector to pan the graph by.
Details
This function shifts the viewport relatively by the specified position in rendered pixels. That is, specifying a shift of 100 to the right means a translation of 100 on-screen pixels to the right.
Examples
Pan the graph 100 pixels to the right.
cy.panBy({
x: 100,
y: 0
});
Get or set whether panning is enabled.
Get whether panning is enabled.
Set whether panning is enabled.
- bool
A truthy value enables panning; a falsey value disables it.
Examples
Enable:
cy.panningEnabled( true );
Disable:
cy.panningEnabled( false );
Get or set whether panning by user events (e.g. dragging the graph background) is enabled.
Get whether user panning is enabled.
Set whether user panning is enabled.
- bool
A truthy value enables user panning; a falsey value disables it.
Examples
Enable:
cy.userPanningEnabled( true );
Disable:
cy.userPanningEnabled( false );
Get or set the zoom level of the graph.
Get the zoom level.
Set the zoom level.
- level
The zoom level to set.
Set the zoom level.
- options
The options for zooming.
- level
The zoom level to set.
- position
The position about which to zoom.
- renderedPosition
The rendered position about which to zoom.
- level
Details
The zoom level must be a positive number. Zoom levels that are not numbers are ignored; zoom levels that are numbers but outside of the range of valid zoom levels are considered to be the closest, valid zoom level.
When zooming about a point via cy.zoom( options )
, the options are defined as follows.
For zooming about a rendered position (i.e. a position on-screen):
cy.zoom({
level: 2.0, // the zoom level
renderedPosition: { x: 100, y: 100 }
});
For zooming about a model position:
cy.zoom({
level: 2.0, // the zoom level
position: { x: 0, y: 0 }
});
For obvious reasons, you can zoom about a position or a rendered position but not both. You should specify only one of options.position
or options.renderedPosition
.
Examples
Zoom in to factor 2
cy.zoom(2);
Zoom in to the minimum zoom factor
cy.zoom(0); // 0 is outside of the valid range and
// its closest valid level is the min
Zoom in to the maximum zoom factor
cy.zoom(1/0); // infinity is outside of the valid range and
// its closest valid level is the max
Zoom about a node
var pos = cy.nodes("#j").position();
cy.zoom({
level: 1.5,
position: pos
});
Get or set whether zooming is enabled.
Get whether zooming is enabled.
Set whether zooming is enabled.
- bool
A truthy value enables zooming; a falsey value disables it.
Examples
Enable:
cy.zoomingEnabled( true );
Disable:
cy.zoomingEnabled( false );
Get or set whether zooming by user events (e.g. mouse wheel, pinch-to-zoom) is enabled.
Get whether user zooming is enabled.
Set whether user zooming is enabled.
- bool
A truthy value enables user zooming; a falsey value disables it.
Examples
Enable:
cy.userZoomingEnabled( true );
Disable:
cy.userZoomingEnabled( false );
Get or set the minimum zoom level.
Get the minimum zoom level.
Set the minimum zoom level.
- zoom
The new minimum zoom level to use.
Get or set the maximum zoom level.
Get the maximum zoom level.
Set the maximum zoom level.
- zoom
The new maximum zoom level to use.
Set the viewport state (pan & zoom) in one call.
- zoom
The zoom level to set.
- pan
The pan to set (a rendered position).
Examples
cy.viewport({
zoom: 2,
pan: { x: 100, y: 100 }
});
Get or set whether box selection is enabled. If enabled along with panning, the user must hold one of shift, control, meta, or alt down to initiate box selection.
Get whether box selection is enabled.
Set whether box selection is enabled.
- bool
A truthy value enables box selection; a falsey value disables it.
Examples
Enable:
cy.boxSelectionEnabled( true );
Disable:
cy.boxSelectionEnabled( false );
Get the extent of the viewport, a bounding box in model coordinates that lets you know what model positions are visible in the viewport.
Details
This function returns a plain object bounding box with format { x1, y1, x2, y2, w, h }
.
Get or set whether nodes are automatically locked (i.e. if true
, nodes are locked despite their individual state).
Get whether autolocking is enabled.
Set whether autolocking is enabled.
- bool
A truthy value enables autolocking; a falsey value disables it.
Examples
Enable:
cy.autolock( true );
Disable:
cy.autolock( false );
Get or set whether nodes are automatically ungrabified (i.e. if true
, nodes are ungrabbale despite their individual state).
Get whether autoungrabifying is enabled.
Set whether autoungrabifying is enabled.
- bool
A truthy value enables autoungrabbifying; a falsey value disables it.
Examples
Enable:
cy.autoungrabify( true );
Disable:
cy.autoungrabify( false );
Get or set whether nodes are automatically unselectified (i.e. if true
, nodes are unselectable despite their individual state).
Get whether autounselectifying is enabled.
Set whether autounselectifying is enabled.
- bool
A truthy value enables autounselectifying; a falsey value disables it.
Examples
Enable:
cy.autounselectify( true );
Disable:
cy.autounselectify( false );
Force the renderer to redraw (i.e. draw a new frame).
Details
This function forces the renderer to draw a new frame. It is useful for very specific edgecases, such as in certain UI extensions, but it should not be needed for most developers.
cy.invalidateDimensions()
,Force the renderer to recalculate the viewport bounds.
Details
If your code resizes the graph’s dimensions or position (i.e. by changing the style of the HTML DOM element that holds the graph, or by changing the DOM element’s position in the DOM tree), you will want to call cy.resize()
to have the graph resize and redraw itself.
If tapping in the graph is offset rather than at the correct position, then a call to cy.resize()
is necessary. Tapping can also become offset if the container element is not empty; the container is expected to be empty so the visualisation can use it.
Cytoscape.js can not automatically monitor the bounding box of the viewport, as querying the DOM for those dimensions can be expensive. Although cy.resize()
is automatically called for you on the window
‘s resize
event, there is no resize
or style
event for arbitrary DOM elements.
Animation
Animate the viewport.
- options
An object containing the details of the animation.
- zoom
A zoom level (number) or a zoom configuration object to which the graph will be animated.
- level
The zoom level to use.
- position
The position about which zooming occurs. This automatically modifies the pan such that the specified model position remains at the same position in the viewport extent during zooming.
- renderedPosition
The rendered position about which zooming occurs, as an alternative to using the model position. This automatically modifies the pan such that the model position, corresponding to the rendered position at the start of the animation, remains at the same position in the viewport extent during zooming.
- pan
A panning position to which the graph will be animated.
- panBy
A relative panning position to which the graph will be animated.
- fit
An object containing fitting options from which the graph will be animated.
- eles
Elements or a selector to which the viewport will be fitted.
- padding
Padding to use with the fitting.
- center
An object containing centring options from which the graph will be animated.
- eles
Elements or a selector to which the viewport will be centred.
- duration
The duration of the animation in milliseconds.
- queue
A boolean indicating whether to queue the animation.
- complete
A function to call when the animation is done.
- step
A function to call each time the animation steps.
- easing
A
transition-timing-function
easing style string that shapes the animation progress curve.
- zoom
Examples
Manual pan and zoom:
cy.animate({
pan: { x: 100, y: 100 },
zoom: 2
}, {
duration: 1000
});
Fit to elements:
var j = cy.$('#j');
cy.animate({
fit: {
eles: j,
padding: 20
}
}, {
duration: 1000
});
Get an animation of the viewport.
- options
An object containing the details of the animation.
- zoom
A zoom level (number) or a zoom configuration object to which the graph will be animated.
- level
The zoom level to use.
- position
The position about which zooming occurs. This automatically modifies the pan such that the specified model position remains at the same position in the viewport extent during zooming.
- renderedPosition
The rendered position about which zooming occurs, as an alternative to using the model position. This automatically modifies the pan such that the model position, corresponding to the rendered position at the start of the animation, remains at the same position in the viewport extent during zooming.
- pan
A panning position to which the graph will be animated.
- panBy
A relative panning position to which the graph will be animated.
- fit
An object containing fitting options from which the graph will be animated.
- eles
Elements or a selector to which the viewport will be fitted.
- padding
Padding to use with the fitting.
- center
An object containing centring options from which the graph will be animated.
- eles
Elements or a selector to which the viewport will be centred.
- duration
The duration of the animation in milliseconds.
- easing
A
transition-timing-function
easing style string that shapes the animation progress curve.
- zoom
Add a delay between animations for the viewport.
- duration
How long the delay should be in milliseconds.
- complete
A function to call when the delay is complete.
Examples
cy
.animate({
fit: { eles: '#j' }
})
.delay(1000)
.animate({
fit: { eles: '#e' }
})
;
Get a delay animation of the viewport.
- duration
How long the delay should be in milliseconds.
Stop all viewport animations that are currently running.
- clearQueue
A boolean, indicating whether the queue of animations should be emptied.
- jumpToEnd
A boolean, indicating whether the currently-running animations should jump to their ends rather than just stopping midway.
Examples
cy.animate({
fit: { eles: '#j' }
}, { duration: 2000 });
// stop in the middle
setTimeout(function(){
cy.stop();
}, 1000);
Layout
cy.createLayout()
, cy.makeLayout()
,Get a new layout, which can be used to algorithmically position the nodes in the graph.
- options
The layout options.
You must specify options.name
with the name of the layout you wish to use.
This function creates and returns a layout object. You may want to keep a reference to the layout for more advanced usecases, such as running multiple layouts simultaneously.
Note that you must call layout.run()
in order for it to affect the graph.
An analogue to make a layout on a subset of the graph exists as eles.layout()
.
Examples
var layout = cy.layout({
name: 'random'
});
layout.run();
Style
Get the entry point to modify the visual style of the graph after initialisation.
Get the current style object.
Assign a new stylesheet to replace the existing one.
- stylesheet
Either a
cytoscape.stylesheet()
object, a string stylesheet, or a JSON stylesheet (the same formats accepted foroptions.style
at initialisation).
Details
You can use this function to gain access to the visual style (stylesheet) after initialisation. This is useful if you need to change the entire stylesheet at runtime.
Sets a new style by reference:
// here a string stylesheet is used, but you could also use json or a cytoscape.stylesheet() object
var stringStylesheet = 'node { background-color: cyan; }';
cy.style( stringStylesheet );
Set an entirely new style to the graph, specifying selectors and style properties via function calls:
cy.style()
.resetToDefault() // start a fresh default stylesheet
// and then define new styles
.selector('node')
.style('background-color', 'magenta')
// ...
.update() // update the elements in the graph with the new style
;
You can also add to the existing stylesheet:
cy.style()
.selector('node')
.style({
'background-color': 'yellow'
})
.update() // update the elements in the graph with the new style
;
You can also set the style from plain JSON:
cy.style()
.fromJson([
{
selector: 'node',
style: {
'background-color': 'red'
}
}
// , ...
])
.update() // update the elements in the graph with the new style
;
You can also set the style from a style string (that you would probably pull from a file on your server):
cy.style()
.fromString('node { background-color: blue; }')
.update() // update the elements in the graph with the new style
;
You can also get the current style as JSON:
var styleJson = cy.style().json();
var serializedJson = JSON.stringify( styleJson );
Export
Export the current graph view as a PNG image.
- options
The export options.
- output
Whether the output should be
'base64uri'
(default),'base64'
, or'blob'
. - bg
The background colour of the image (transparent by default).
- full
Whether to export the current viewport view (
false
, default) or the entire graph (true
). - scale
This value specifies a positive number that scales the size of the resultant image.
- maxWidth
Specifies the scale automatically in combination with
maxHeight
such that the resultant image is no wider thanmaxWidth
. - maxHeight
Specifies the scale automatically in combination with
maxWidth
such that the resultant image is no taller thanmaxHeight
.
- output
Details
By default, the export takes into account the current screen pixel density so that the image is of the same quality of the screen. If the maxWidth
or maxHeight
options are specified, then the screen pixel density is ignored so that the image can fit in the specified dimensions.
Examples
var png64 = cy.png();
// put the png data in an img tag
$('#png-eg').attr('src', png64);
Example image tag:
cy.jpeg()
,Export the current graph view as a JPG image.
- options
The export options.
- output
Whether the output should be
'base64uri'
(default),'base64'
, or'blob'
. - bg
The background colour of the image (white by default).
- full
Whether to export the current viewport view (
false
, default) or the entire graph (true
). - scale
This value specifies a positive number that scales the size of the resultant image.
- maxWidth
Specifies the scale automatically in combination with
maxHeight
such that the resultant image is no wider thanmaxWidth
. - maxHeight
Specifies the scale automatically in combination with
maxWidth
such that the resultant image is no taller thanmaxHeight
. - quality
Specifies the quality of the image from
0
(low quality, low filesize) to1
(high quality, high filesize). If not set, the browser's default quality value is used.
- output
Details
By default, the export takes into account the current screen pixel density so that the image is of the same quality of the screen. If the maxWidth
or maxHeight
options are specified, then the screen pixel density is ignored so that the image can fit in the specified dimensions.
The JPEG format is lossy, whereas PNG is not. This means that cy.jpg()
is useful for cases where filesize is more important than pixel-perfect images. JPEG compression will make your images (especially edge lines) blurry and distorted.
Examples
var jpg64 = cy.jpg();
// put the png data in an img tag
$('#jpg-eg').attr('src', jpg64);
Example image tag:
Import or export the graph in the same JSON format used at initialisation.
Export the graph as JSON.
Import the graph as JSON, updating only the fields specified.
- cyJson
The object with the fields corresponding to the states that should be changed.
Details
This function returns the same object that is used for initialisation. You will find this function useful if you would like to save the entire state of the graph, either for your own purposes or for future restoration of that graph state.
This function can also be used to set graph state as in cy.json( cyJson )
, where each field in cyJson
is to be mutated in the graph. For each field defined in cyJson
, cy
is updated to match with the corresponding events emitted. This allows for declarative changes on the graph to be made.
For cy.json( cyJson )
, all mutable initialisation options are supported.
When setting cy.json({ elements: ... })
- the included elements are mutated as specified (i.e. as they would be by
ele.json( eleJson )
), - the included elements not in the graph are added, and
- the not included elements are removed from the graph.
When setting cy.json({ style: ... })
- the entire stylesheet is replaced, and
- the style is recalculated for each element.
Updating the stylesheet is expensive. Similarly, it can potentially be expensive to update the existing elements for large graphs — as each element needs to be considered, and potentially each field per element. For elements, a much cheaper option is to selectively call ele.json(...)
with only the fields that need to be updated.
Examples
console.log( cy.json() );
cy.json({
zoom: 2
});
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
Remove the elements from the graph, and return all elements removed by this call.
Details
This function removes the calling elements from the graph. The elements are not deleted — they still exist in memory — but they are no longer in the graph.
A removed element just exists to be added back to its originating core instance or some other core instance. A removed element is not functional, because it is no longer a part of the graph: Nothing really makes sense for it anymore outside of the context of a graph. It merely exists in this limbo state so you can later add it back to some core instance.
Examples
Remove selected elements:
cy.$(':selected').remove();
Put removed elements back into the graph.
Details
This function puts back elements in the graph that have been removed. It will do nothing if the elements are already in the graph.
An element can not be restored if its ID is the same as an element already in the graph. You should specify an alternative ID for the element you want to add in that case.
Examples
// remove selected elements
var eles = cy.$(':selected').remove();
// ... then some time later put them back
eles.restore();
eles.copy()
,Get a new collection containing clones (i.e. copies) of the elements in the calling collection.
Effectively move edges to different nodes or move nodes to different parent node. The modified (actually new) elements are returned.
Move edges to different nodes.
- location
Where the edges are moved. You can specify a new source, a new target, or both.
- source
The ID of the new source node.
- target
The ID of the new target node.
- source
Move nodes to different parent node.
- location
Where the nodes are moved.
- parent
The ID of the new parent node (use
null
for no parent).
- parent
Details
Note that this function does not really move the elements. That’s not possible in the semantics of a graph. Instead, this function
- gets JSON copies of the elements,
- removes the original elements,
- modifies the JSON copies as specified, and
- adds new elements from the JSON copies and restores relationships (in the case of compound node descendants and connected edges).
This creates the same effect as though the elements have been moved while maintaining the correct semantics for a graph.
Examples
Move an edge:
cy.$('#ej').move({
target: 'g'
})
Events
eles.bind()
, eles.listen()
, eles.addListener()
,Bind to events that occur on the elements.
Examples
cy.$('#j').on('tap', function(evt){
console.log( 'tap ' + evt.target.id() );
});
eles.pon()
,Get a promise that is resolved with the first of any of the specified events emitted on any of the elements in the collection.
Examples
cy.$('#j').pon('tap').then(function( event ){
console.log('tap promise fulfilled');
});
Bind a callback function that is emitted once per event per element.
Details
For each event specified to this function, the handler function is triggered once per element. This is useful for one-off events that occur on each element in the calling collection once.
The semantics is a bit more complicated for compound nodes where a delegate selector has been specified: Note that the handler is called once per element in the calling collection, and the handler is triggered by matching descendant elements.
Examples
cy.$('node').one('tap', function(e){
var ele = e.target;
console.log('tapped ' + ele.id());
});
Bind a callback function that is emitted once per event per collection.
Details
For each event specified to this function, the handler function is triggered once. This is useful for one-off events that occur on just one element in the calling collection.
Examples
cy.$('node').once('click', function(e){
var ele = e.target;
console.log('clicked ' + ele.id());
});
eles.off()
, eles.unbind()
, eles.unlisten()
,Unbind one or more callback functions on the elements.
Examples
var j = cy.$('#j');
var handler = function(){ console.log('tap') };
// bind
j.on('tap', handler);
// bind some other handler
j.on('tap', function(){
console.log('some other handler');
});
j.emit('tap'); // 'tap' & 'some other handler'
// unbind the renferenced handler
j.removeListener('tap', handler);
j.emit('tap'); // some other handler
// unbind all tap handlers (including unnamed handler)
j.removeListener('tap');
eles.trigger()
,Emit events on the elements.
- events
A space separated list of event names to emit.
- extraParams [optional]
An array of additional parameters to pass to the handler.
Examples
var j = cy.$('#j');
j.on('tap', function(){
console.log('tap!!');
});
j.emit('tap'); // tap!!
Data
eles.attr()
,Read and write developer-defined data associated with the elements.
Get all data for the element.
Get a particular data field for the element.
- name
The name of the field to get.
Set a particular data field for the element.
- name
The name of the field to set.
- value
The value to set for the field.
Update multiple data fields at once via an object.
- obj
The object containing name-value pairs to update data fields.
Details
Only JSON-serialisable data may be put in ele.data()
. For temporary data or non-serialisable data, use ele.scratch()
.
The following fields are immutable:
id
: Theid
field is used to uniquely identify an element in the graph.source
&target
: These fields define an edge’s relationship to nodes, and this relationship can not be changed after creation.parent
: Theparent
field defines the parent (compound) node.
Examples
var j = cy.$('#j');
// set the weight field in data
j.data('weight', 60);
// set several fields at once
j.data({
name: 'Jerry Jerry Dingleberry',
height: 176
});
var weight = j.data('weight');
eles.removeAttr()
,Remove developer-defined data associated with the elements.
Removes all mutable data fields for the elements.
Removes the specified mutable data fields for the elements.
- names
A space-separated list of fields to delete.
Details
The following data fields are immutable, and so they can not be removed:
id
: Theid
field is used to uniquely identify an element in the graph.source
&target
: These fields define an edge’s relationship to nodes, and this relationship can not be changed after creation.parent
: Theparent
field defines the parent (compound) node.
Set or get scratchpad data, where temporary or non-JSON data can be stored. App-level scratchpad data should use namespaces prefixed with underscore, like '_foo'
.
Get the entire scratchpad object for the element.
Get the scratchpad at a particular namespace.
- namespace
A namespace string.
Set the scratchpad at a particular namespace.
- namespace
A namespace string.
- value
The value to set at the specified namespace.
Details
This function is useful for storing temporary, possibly non-JSON data. Extensions — like layouts, renderers, and so on — use ele.scratch()
namespaced on their registered name. For example, an extension named foo
would use the namespace 'foo'
.
If you want to use this function for your own app-level data, you can prefix the namespaces you use by underscore to avoid collisions with extensions. For example, using ele.scratch('_foo')
in your app will avoid collisions with an extension named foo
.
This function is useful for associating non-JSON data to an element. Whereas data stored via ele.data()
is included by ele.json()
, data stored by ele.scratch()
is not. This makes it easy to temporarily store unserialisable data.
Examples
var j = cy.$('#j');
// entire scratchpad:
// be careful, since you could clobber over someone else's namespace or forget to use one at all!
var fooScratch = j.scratch()._foo = {};
// ... now you can modify fooScratch all you want
// set namespaced scratchpad to ele:
// safer, recommended
var fooScratch = j.scratch('_foo', {});
// ... now you can modify fooScratch all you want
// get namespaced scratchpad from ele (assumes set before)
var fooScratch = j.scratch('_foo');
// ... now you can modify fooScratch all you want
Remove scratchpad data. You should remove scratchpad data only at your own namespaces.
Remove the scratchpad data at a particular namespace.
- namespace
A namespace string.
Get or mutate the element's plain JavaScript object representation.
Get the element's JSON.
Mutate the element's state as specified.
- eleJson
For each field in the object, the element's state is mutated as specified.
Details
This function returns the plain JSON representation of the element, the same format which is used at initialisation, in cy.add()
, etc.
This function can also be used to set the element’s state using the plain JSON representation of the element. Each field specified in ele.json( eleJson )
is diffed against the element’s current state, the element is mutated accordingly, and the appropriate events are emitted. This can be used to declaratively modify elements.
Note that it is much faster to simply specify the diff-patch objects to ele.json()
, e.g. ele.json({ data: { foo: 'bar' } })
only updates foo
in data
. This avoids the cost of diffs on unchanged fields, which is useful when making many calls to ele.json()
for larger graphs.
Examples
console.log( cy.$('#j').json() );
cy.$('#j').json({ selected: true });
Get an array of the plain JavaScript object representation of all elements in the collection.
Details
This function returns the plain JSON representation of all elements in the collection, the same format which is used at initialisation, in cy.add()
, etc.
Examples
console.log( cy.elements().jsons() );
Get the group string that defines the type of the element.
Details
The group strings are 'nodes'
for nodes and 'edges'
for edges. In general, you should be using ele.isEdge()
and ele.isNode()
instead of ele.group()
.
Metadata
Get the degree of a node.
- includeLoops
A boolean, indicating whether loops are to be included in degree calculations.
Get the indegree of a node.
- includeLoops
A boolean, indicating whether loops are to be included in degree calculations.
Get the outdegree of a node.
- includeLoops
A boolean, indicating whether loops are to be included in degree calculations.
Get the total degree of a collection of nodes.
- includeLoops
A boolean, indicating whether loops are to be included in degree calculations.
Get the minimum degree of the nodes in the collection.
- includeLoops
A boolean, indicating whether loops are to be included in degree calculations.
Get the maximum degree of the nodes in the collection.
- includeLoops
A boolean, indicating whether loops are to be included in degree calculations.
Get the minimum indegree of the nodes in the collection.
- includeLoops
A boolean, indicating whether loops are to be included in degree calculations.
Get the maximum indegree of the nodes in the collection.
- includeLoops
A boolean, indicating whether loops are to be included in degree calculations.
Get the minimum outdegree of the nodes in the collection.
- includeLoops
A boolean, indicating whether loops are to be included in degree calculations.
Get the maximum outdegree of the nodes in the collection.
- includeLoops
A boolean, indicating whether loops are to be included in degree calculations.
Details
Degree : For a node, the degree is the number of edge connections it has. Each time a node is referenced as source
or target
of an edge in the graph, that counts as an edge connection.
Indegree : For a node, the indegree is the number of incoming edge connections it has. Each time a node is referred to as target
of an edge in the graph, that counts as an incoming edge connection.
Outdegree : For a node, the outdegree is the number of outgoing edge connections it has. Each time a node is referred to as source
of an edge in the graph, that counts as an outgoing edge connection.
Total degree : For a set of nodes, the total degree is the total number of edge connections to nodes in the set.
Position & dimensions
node.modelPosition()
, node.point()
,Get or set the (model) position of a node.
Get the entire position object.
Get the value of a specified position dimension.
- dimension
The position dimension to get.
Set the value of a specified position dimension.
- dimension
The position dimension to set.
- value
The value to set to the dimension.
Set the position using name-value pairs in the specified object.
- pos
An object specifying name-value pairs representing dimensions to set.
Details
A position has two fields, x
and y
, that can take on numerical values.
Examples
// get x for j
var x = cy.$('#j').position('x');
// get the whole position for e
var pos = cy.$('#e').position();
// set y for j
cy.$('#j').position('y', 100);
// set multiple
cy.$('#e').position({
x: 123,
y: 200
});
Shift the positions of the nodes by a given model position vector.
Shift the nodes by one of 'x'
or 'y'
.
- dimension
The position dimension to shift.
- value
The value to shift the dimension.
Shift the nodes by a position vector.
- pos
An object specifying name-value pairs representing dimensions to shift.
nodes.modelPositions()
, nodes.points()
,Set the (model) positions of several nodes with a function.
Set the positions via a function.
- function(ele, i)
A callback function that returns the position to set for each element.
- ele
The element being iterated over for which the function should return a position to set.
- i
The index of the element when iterating over the elements in the collection.
- ele
Set positions for all nodes based on a single position object.
- pos
An object specifying name-value pairs representing dimensions to set.
Examples
cy.nodes().positions(function( node, i ){
return {
x: i * 100,
y: 100
};
});
node.renderedPoint()
,Get or set the rendered (on-screen) position of a node.
Get the entire rendered position object.
Get the value of a specified rendered position dimension.
- dimension
The position dimension to get.
Set the value of a specified rendered position dimension.
- dimension
The position dimension to set.
- value
The value to set to the dimension.
Set the rendered position using name-value pairs in the specified object.
- pos
An object specifying name-value pairs representing dimensions to set.
node.relativePoint()
,Get or set the position of a node, relative to its compound parent.
Get the entire relative position object.
Get the value of a specified relative position dimension.
- dimension
The position dimension to get.
Set the value of a specified relative position dimension.
- dimension
The position dimension to set.
- value
The value to set to the dimension.
Set the relative position using name-value pairs in the specified object.
- pos
An object specifying name-value pairs representing dimensions to set.
Get the width of the element.
Get the width of the element.
Get the outer width of the element (includes width, padding, & border).
Get the width of the element in rendered dimensions.
Get the outer width of the element (includes width, padding, & border) in rendered dimensions.
Get the height of the element.
Get the height of the element.
Get the outer height of the element (includes height, padding, & border).
Get the height of the element in rendered dimensions.
Get the outer height of the element (includes height, padding, & border) in rendered dimensions.
eles.boundingbox()
,Get the bounding box of the elements.
Get the bounding box of the elements in model coordinates.
- options
An object containing options for the function.
- includeNodes
A boolean indicating whether to include nodes in the bounding box (default
true
). - includeEdges
A boolean indicating whether to include edges in the bounding box (default
true
). - includeLabels
A boolean indicating whether to include labels in the bounding box (default
true
). - includeOverlays
A boolean indicating whether to include overlays (such as the one which appears when a node is clicked) in the bounding box (default
true
).
- includeNodes
Details
This function returns a plain object with the fields x1
, x2
, y1
, y2
, w
, and h
defined.
eles.renderedBoundingbox()
,Get the rendered bounding box of the elements.
Get the bounding box of the elements in rendered coordinates.
- options
An object containing options for the function.
- includeNodes
A boolean indicating whether to include nodes in the bounding box (default
true
). - includeEdges
A boolean indicating whether to include edges in the bounding box (default
true
). - includeLabels
A boolean indicating whether to include labels in the bounding box (default
true
). - includeOverlays
A boolean indicating whether to include overlays (such as the one which appears when a node is clicked) in the bounding box (default
true
).
- includeNodes
Details
This function returns a plain object with the fields x1
, x2
, y1
, y2
, w
, and h
defined.
Unlock the nodes such that their positions can be changed.
Examples
cy.$('#j').unlock();
Edge points
Get an array of control point model positions for a curve-style: bezier
or curve-style: unbundled-bezier
edge.
Details
While the control points may be specified relatively in the CSS, this function returns the absolute model positions of the control points. The points are specified in the order of source-to-target direction.
This function works for bundled beziers, but it is not applicable to the middle, straight-line edge in the bundle.
Get an array of segment point model positions (i.e. bend points) for a curve-style: segments
edge.
Details
While the segment points may be specified relatively in the stylesheet, this function returns the absolute model positions of the segment points. The points are specified in the order of source-to-target direction.
Get the model position of the midpoint of the edge.
Details
The midpoint is, by default, where the edge’s label is centred. It is also the position towards which mid arrows point.
For curve-style: unbundled-bezier
edges, the midpoint is the middle extremum if the number of control points is odd.
For an even number of control points, the midpoint is where the two middle-most control points meet. This is the middle inflection point for bilaterally symmetric or skew symmetric edges, for example.
For curve-style: segments
edges, the midpoint is the middle segment point if the number of segment points is odd. For an even number of segment points, the overall midpoint is the midpoint of the middle-most line segment (i.e. the mean of the middle two segment points).
Layout
eles.createLayout()
, eles.makeLayout()
,Get a new layout, which can be used to algorithmically position the nodes in the collection.
- options
The layout options.
This function is useful for running a layout on a subset of the elements in the graph, perhaps in parallel to other layouts.
You must specify options.name
with the name of the layout you wish to use.
This function creates and returns a layout object. You may want to keep a reference to the layout for more advanced usecases, such as running multiple layouts simultaneously.
Note that you must call layout.run()
in order for it to affect the graph.
Examples
var layout = cy.elements().layout({
name: 'random'
});
layout.run();
Position the nodes for a discrete/synchronous layout.
- layout
The layout.
- options
The layout options object.
- function(ele, i)
A function that returns the new position for the specified node.
- ele
The node being iterated over for which the function should return a position to set.
- i
The index of the current node while iterating over the nodes in the layout.
- ele
This function is called by discrete layouts to update the graph with new node positions.
A layout is only responsible for calculating new node positions; setting these positions and performing animations/ modifying viewport/ changing zoom/ etc. are handled by layoutPositions()
, which is called by each layout at the end of its run()
method.
The options
object is passed to layoutPositions()
when called by a layout extension and consists of many of the common properties shared between layouts.
var options = {
animate: false, // whether to animate changes to the layout
animationDuration: 500, // duration of animation in ms, if enabled
animationEasing: undefined, // easing of animation, if enabled
animateFilter: function ( node, i ){ return true; }, // a function that determines whether the node should be animated.
//All nodes animated by default on animate enabled. Non-animated nodes are positioned immediately when the layout starts
eles: someCollection, // collection of elements involved in the layout; set by cy.layout() or eles.layout()
fit: true, // whether to fit the viewport to the graph
padding: 30, // padding to leave between graph and viewport
pan: undefined, // pan the graph to the provided position, given as { x, y }
ready: undefined, // callback for the layoutready event
stop: undefined, // callback for the layoutstop event
spacingFactor: 1, // a positive value which adjusts spacing between nodes (>1 means greater than usual spacing)
transform: function (node, position ){ return position; } // transform a given node position. Useful for changing flow direction in discrete layouts
zoom: undefined // zoom level as a positive number to set after animation
}
Note that if fit
is true, it will override any values provided in pan
or zoom
.
Returns the node width and height. Meant for use in layout positioning to do overlap detection.
- options
The layout options object.
This function is used to retrieve the width and height of the bounding box of a node. The way the width and height are calculated is affected by the options object which is passed in.
It returns an object containing the width and height of the calculated bounding box under the w
and h
keys respectively. It can be used as a direct replacement for the boundingBox()
function assuming only w
and h
values are needed.
var options = {
nodeDimensionsIncludeLabels: true, // Boolean which changes whether label dimensions are included when calculating node dimensions, default true
};
var dims = cy.nodes().first().layoutDimensions( options );
Selection
Make the elements selected (NB other elements outside the collection are not affected).
Examples
cy.$('#j').select();
eles.deselect()
,Make the elements not selected (NB other elements outside the collection are not affected).
Examples
cy.$('#j').unselect();
Make the selection states of the elements mutable.
Examples
cy.$('#j').unselectify();
Make the selection states of the elements immutable.
Examples
cy.$('#j').unselectify();
Style
Add classes to elements.
- classes
A space-separated list of class names to add to the elements.
Examples
cy.$('#j, #e').addClass('foo');
Remove classes from elements.
- classes
A space-separated list of class names to remove from the elements.
Examples
cy.$('#j, #e').removeClass('foo');
Toggle whether the elements have the specified classes.
- classes
A space-separated list of class names to toggle on the elements.
- toggle [optional]
Instead of automatically toggling, adds the classes on truthy values or removes them on falsey values.
Examples
Toggle:
cy.$('#j, #e').toggleClass('foo');
Toggle on:
cy.$('#j, #e').toggleClass('foo', true);
Toggle off:
cy.$('#j, #e').toggleClass('foo', false);
Replace the current list of classes on the elements with the specified list.
- classes
A space-separated list of class names that replaces the current class list.
Examples
Remove all classes:
cy.nodes().classes(); // no classes
Replace classes:
cy.nodes().classes('foo');
Add classes to the elements, and then remove the classes after a specified duration.
- classes
A space-separated list of class names to flash on the elements.
- duration [optional]
The duration in milliseconds that the classes should be added on the elements. After the duration, the classes are removed.
Examples
cy.$('#j, #e').flashClass('foo', 1000);
Get whether an element has a particular class.
- className
The name of the class to test for.
Examples
console.log( 'j has class `foo` : ' + cy.$('#j').hasClass('foo') );
eles.css()
,Get or override the style of the element.
Get a name-value pair object containing visual style properties and their values for the element.
Get a particular style property value.
- name
The name of the visual style property to get.
Set a particular style property value.
- name
The name of the visual style property to set.
- value
The value of the visual style property to set.
Set several particular style property values.
- obj
An object of style property name-value pairs to set.
Remove all style overrides.
Remove specific style overrides.
- names
A space-separated list of property names to remove overrides.
Details
You should use this function very sparingly for setting, because it overrides the style of an element, despite the state and classes that it has. In general, it’s much better to specify a better stylesheet at initialisation that reflects your application state rather than programmatically modifying style.
Only defined visual style properties are supported.
If you would like to remove a particular overridden style property, set null
or ''
(the empty string) to it.
eles.renderedCss()
,Get the style of the element in rendered dimensions.
Get a name-value pair object containing rendered visual style properties and their values for the element.
Get a particular rendered style property value.
- name
The name of the visual style property to get.
Get the numeric value of a style property in preferred units that can be used for calculations.
- name
The name of the style property to get.
Details
- Sizes (e.g.
width
) are in pixels. - Times (e.g.
transition-duration
) are in milliseconds. - Angles (e.g.
text-rotation
) are in radians. - Plain numbers (e.g.
opacity
) are unitless. - Colours (e.g.
background-color
) are in[r, g, b]
arrays with values on [0, 255]. - Lists of numbers (e.g.
edge-distances
) are in arrays. - Percents range on [0, 1] so that they are useful for calculations.
- Some properties can not have preferred units defined, like
background-position-x
— it could be inpx
or%
, for instance. A property like this is returned in the units as specified in the element’s style (e.g. the stylesheet). In this case, the units can be returned explicitly viaele.numericStyleUnits()
. - Values that can not be expressed as numbers (e.g.
label
) are returned as a string.
Examples
node.numericStyle('width')
would return 30
for a 30px wide node, even if the node was specified as width: 3em
.
Get the units that ele.numericStyle()
is expressed in, for a particular property.
- name
The name of the style property to get.
Get whether the element is visible (i.e. display: element
and visibility: visible
).
Get whether the element is visible.
Get whether the element is hidden.
Get the effective opacity of the element (i.e. on-screen opacity), which takes into consideration parent node opacity.
Get whether the element's effective opacity is completely transparent, which takes into consideration parent node opacity.
Animation
Animate the elements.
- options
An object containing the details of the animation.
- position
A position to which the elements will be animated.
- renderedPosition
A rendered position to which the elements will be animated.
- style
An object containing name-value pairs of style properties to animate.
- duration
The duration of the animation in milliseconds.
- queue
A boolean indicating whether to queue the animation.
- complete
A function to call when the animation is done.
- step
A function to call each time the animation steps.
- easing
A
transition-timing-function
easing style string that shapes the animation progress curve.
- position
Details
Note that you can specify only one of position
and renderedPosition
: You can not animate to two positions at once.
Examples
cy.nodes().animate({
position: { x: 100, y: 100 },
style: { backgroundColor: 'red' }
}, {
duration: 1000
});
console.log('Animating nodes...');
Get an animation for the element.
- options
An object containing the details of the animation.
- position
A position to which the elements will be animated.
- renderedPosition
A rendered position to which the elements will be animated.
- style
An object containing name-value pairs of style properties to animate.
- duration
The duration of the animation in milliseconds.
- easing
A
transition-timing-function
easing style string that shapes the animation progress curve.
- position
Add a delay between animations for the elements.
- duration
How long the delay should be in milliseconds.
- complete
A function to call when the delay is complete.
Examples
cy.nodes()
.animate({
style: { 'background-color': 'blue' }
}, {
duration: 1000
})
.delay( 1000 )
.animate({
style: { 'background-color': 'yellow' }
})
;
console.log('Animating nodes...');
Get a delay animation for the element.
- duration
How long the delay should be in milliseconds.
Stop all animations that are currently running.
- clearQueue
A boolean, indicating whether the queue of animations should be emptied.
- jumpToEnd
A boolean, indicating whether the currently-running animations should jump to their ends rather than just stopping midway.
Examples
cy.nodes().animate({
style: { 'background-color': 'cyan' }
}, {
duration: 5000,
complete: function(){
console.log('Animation complete');
}
});
console.log('Animating nodes...');
setTimeout(function(){
console.log('Stopping nodes animation');
cy.nodes().stop();
}, 2500);
Comparison
Determine whether this collection contains exactly the same elements as another collection.
- eles
The other elements to compare to.
Examples
var heavies = cy.$('node[weight > 60]');
var guys = cy.$('#j, #g, #k');
console.log( 'same ? ' + heavies.same(guys) );
Determine whether this collection contains any of the same elements as another collection.
- eles
The other elements to compare to.
Examples
var j = cy.$('#j');
var guys = cy.$('#j, #g, #k');
console.log( 'any same ? ' + j.anySame(guys) );
eles.has()
,Determine whether this collection contains all of the elements of another collection.
- eles
The other elements to compare to.
Examples
cy.$('#j, #e').contains( cy.$('#j') ); // true
eles.allAreNeighbours()
,Determine whether all elements in the specified collection are in the neighbourhood of the calling collection.
- eles
The other elements to compare to.
Examples
var j = cy.$('#j');
var gAndK = cy.$('#g, #k');
console.log( 'all neighbours ? ' + j.allAreNeighbors(gAndK) );
Determine whether any element in this collection matches a selector.
- selector
The selector to match against.
Examples
var j = cy.$('#j');
console.log( 'j has weight > 50 ? ' + j.is('[weight > 50]') );
Determine whether all elements in the collection match a selector.
- selector
The selector to match against.
Examples
var jAndE = cy.$('#j, #e');
console.log( 'j and e all have weight > 50 ? ' + jAndE.allAre('[weight > 50]') );
Determine whether any element in this collection satisfies the specified test function.
- function(ele, i, eles)
The test function that returns truthy values for elements that satisfy the test and falsey values for elements that do not satisfy the test.
- thisArg [optional]
The value for
this
within the test function.
Examples
var jAndE = cy.$('#j, #e');
var someHeavierThan50 = jAndE.some(function( ele ){
return ele.data('weight') > 50;
});
console.log( 'some heavier than 50 ? ' + someHeavierThan50 );
Determine whether all elements in this collection satisfy the specified test function.
- function(ele, i, eles)
The test function that returns truthy values for elements that satisfy the test and falsey values for elements that do not satisfy the test.
- thisArg [optional]
The value for
this
within the test function.
Examples
var jAndE = cy.$('#j, #e');
var everyHeavierThan50 = jAndE.every(function( ele ){
return ele.data('weight') > 50;
});
console.log( 'every heavier than 50 ? ' + everyHeavierThan50 );
Iteration
Get the number of elements in the collection.
Details
Note that as an alternative, you may read eles.length
instead of eles.size()
. The two are interchangeable.
Get whether the collection is empty, meaning it has no elements.
Get whether the collection is empty.
Get whether the collection is nonempty.
eles.each()
,Iterate over the elements in the collection.
Details
This function behaves like Array.prototype.forEach()
with minor changes for convenience:
- You can exit the iteration early by returning
false
in the iterating function. TheArray.prototype.forEach()
implementation does not support this, but it is included anyway on account of its utility.
Examples
// print all the ids of the nodes in the graph
cy.nodes().forEach(function( ele ){
console.log( ele.id() );
});
Get an element at a particular index in the collection.
- index
The index of the element to get.
Get the first element in the collection.
Get the last element in the collection.
Details
You may use eles[i]
in place of eles.eq(i)
as a more performant alternative.
Get a subset of the elements in the collection based on specified indices.
- start [optional]
An integer that specifies where to start the selection. The first element has an index of 0. Use negative numbers to select from the end of an array.
- end [optional]
An integer that specifies where to end the selection. If omitted, all elements from the start position and to the end of the array will be selected. Use negative numbers to select from the end of an array.
Building & filtering
eles.$id()
,Get an element in the collection from its ID in a very performant way.
- id
The ID of the element to get.
eles.add()
, eles.or()
, eles['u']()
, eles['+']()
, eles['|']()
,Get a new collection, resulting from adding the collection with another one
- eles
The elements to add.
- selector
Elements in the graph matching this selector are added.
Examples
With a collection:
var j = cy.$('#j');
var e = cy.$('#e');
j.union(e);
With a selector:
cy.$('#j').union('#e');
eles.not()
, eles.subtract()
, eles.relativeComplement()
, eles['\\']()
, eles['!']()
, eles['-']()
,Get a new collection, resulting from the collection without some specified elements.
- eles
The elements that will not be in the resultant collection.
- selector
Elements from the calling collection matching this selector will not be in the resultant collection.
Examples
With a collection:
var j = cy.$('#j');
var nodes = cy.nodes();
nodes.difference(j);
With a selector:
cy.nodes().difference('#j');
eles.abscomp()
, eles.complement()
,Get all elements in the graph that are not in the calling collection.
Examples
cy.$('#j').absoluteComplement();
eles.intersect()
, eles.and()
, eles['n']()
, eles['&']()
, eles['.']()
,Get the elements in both this collection and another specified collection.
- eles
The elements to intersect with.
- selector
A selector representing the elements to intersect with. All elements in the graph matching the selector are used as the passed collection.
Examples
var jNhd = cy.$('#j').neighborhood();
var eNhd = cy.$('#e').neighborhood();
jNhd.intersection( eNhd );
eles.symdiff()
, eles.xor()
, eles['^']()
, eles['(+)']()
, eles['(-)']()
,Get the elements that are in the calling collection or the passed collection but not in both.
- eles
The elements to apply the symmetric difference with.
- selector
A selector representing the elements to apply the symmetric difference with. All elements in the graph matching the selector are used as the passed collection.
Examples
cy.$('#j, #e, #k').symdiff('#j, #g');
Perform a traditional left/right diff on the two collections.
- eles
The elements on the right side of the diff.
- selector
A selector representing the elements on the right side of the diff. All elements in the graph matching the selector are used as the passed collection.
Details
This function returns a plain object of the form { left, right, both }
where
left
is the set of elements only in the calling (i.e. left) collection,right
is the set of elements only in the passed (i.e. right) collection, andboth
is the set of elements in both collections.
Examples
var diff = cy.$('#j, #e, #k').diff('#j, #g');
var getNodeId = function( n ){ return n.id() };
console.log( 'left: ' + diff.left.map( getNodeId ).join(', ') );
console.log( 'right: ' + diff.right.map( getNodeId ).join(', ') );
console.log( 'both: ' + diff.both.map( getNodeId ).join(', ') );
Perform a in-place merge of the given elements into the calling collection.
- eles
The elements to merge in-place.
- selector
A selector representing the elements to merge. All elements in the graph matching the selector are used as the passed collection.
Details
This function modifies the calling collection instead of returning a new one. Use of this function should be considered for performance in some cases, but otherwise should be avoided. Consider using eles.union()
instead.
Use this function only on new collections that you create yourself, using cy.collection()
. This ensures that you do not unintentionally modify another collection.
Examples
With a collection:
var col = cy.collection(); // new, empty collection
var j = cy.$('#j');
var e = cy.$('#e');
col.merge( j ).merge( e );
With a selector:
var col = cy.collection(); // new, empty collection
col.merge('#j').merge('#e');
Perform an in-place operation on the calling collection to remove the given elements.
- eles
The elements to remove in-place.
- selector
A selector representing the elements to remove. All elements in the graph matching the selector are used as the passed collection.
Details
This function modifies the calling collection instead of returning a new one. Use of this function should be considered for performance in some cases, but otherwise should be avoided. Consider using eles.filter()
or eles.remove()
instead.
Use this function only on new collections that you create yourself, using cy.collection()
. This ensures that you do not unintentionally modify another collection.
Examples
With a collection:
var col = cy.collection(); // new, empty collection
var e = cy.$('#e');
col.merge( cy.nodes() );
col.unmerge( e );
With a selector:
var col = cy.collection(); // new, empty collection
col.merge( cy.nodes() );
col.unmerge('#e');
Get a new collection containing elements that are accepted by the specified filter function or selector.
- function(ele, i, eles)
The filter function that returns truthy values for elements to include and falsey values for elements to exclude.
- thisArg [optional]
The value for
this
within the iterating function.
Get the elements that match the specified selector.
- selector
The selector to match against.
Get the nodes that match the specified selector.
- selector
The selector to match against.
Get the edges that match the specified selector.
- selector
The selector to match against.
Examples
With a selector:
cy.nodes().filter('[weight > 50]');
With a function:
cy.nodes().filter(function( ele ){
return ele.data('weight') > 50;
});
Get a new collection containing the elements sorted by the specified comparison function.
- function(ele1, ele2)
The sorting comparison function that returns a negative number for
ele1
beforeele2
, 0 forele1
same asele2
, or a positive number forele1
afterele2
.
Examples
Get collection of nodes in order of increasing weight:
var nodes = cy.nodes().sort(function( a, b ){
return a.data('weight') - b.data('weight');
});
// show order via animations
var duration = 1000;
nodes.removeStyle().forEach(function( node, i ){
node.delay( i * duration ).animate({
style: {
'border-width': 4,
'border-color': 'green'
}
}, { duration: duration });
});
console.log('Animating nodes to show sorted order');
Get an array containing values mapped from the collection.
Examples
Get an array of node weights:
var weights = cy.nodes().map(function( ele ){
return ele.data('weight');
});
console.log(weights);
Reduce a single value by applying a function against an accumulator and each value of the collection.
Examples
Join the node IDs into a comma-separated string:
var initialValue = null;
var fn = function( prevVal, ele, i, eles ){
if( prevVal ){
return prevVal + ',' + ele.id();
} else {
return ele.id();
}
};
var ids = cy.nodes().reduce( fn, initialValue );
console.log( ids );
Find a minimum value in a collection.
Details
This function returns an object with the following fields:
value
: The minimum value found.ele
: The element that corresponds to the minimum value.
Examples
Find the node with the minimum weight:
var min = cy.nodes().min(function(){
return this.data('weight');
});
console.log( 'min val: ' + min.value + ' for element ' + min.ele.id() );
Find a maximum value and the corresponding element.
Details
This function returns an object with the following fields:
value
: The maximum value found.ele
: The element that corresponds to the maximum value.
Examples
Find the node with the maximum weight:
var max = cy.nodes().max(function(){
return this.data('weight');
});
console.log( 'max val: ' + max.value + ' for element ' + max.ele.id() );
Traversing
Get the neighbourhood of the elements.
Get the open neighbourhood of the elements.
- selector [optional]
An optional selector that is used to filter the resultant collection.
Get the open neighbourhood of the elements.
- selector [optional]
An optional selector that is used to filter the resultant collection.
Get the closed neighbourhood of the elements.
- selector [optional]
An optional selector that is used to filter the resultant collection.
Details
The neighbourhood returned by this function is a bit different than the traditional definition of a “neighbourhood”: This returned neighbourhood includes the edges connecting the collection to the neighbourhood. This gives you more flexibility.
An open neighbourhood is one that does not include the original set of elements. If unspecified, a neighbourhood is open by default.
A closed neighbourhood is one that does include the original set of elements.
Examples
cy.$('#j').neighborhood();
Get the connected components, considering only the elements in the calling collection. An array of collections is returned, with each collection representing a component.
Get the edges connecting the collection to another collection. Direction of the edges does not matter.
- eles
The other collection.
- selector
The other collection, specified as a selector which is matched against all elements in the graph.
Examples
var j = cy.$('#j');
var e = cy.$('#e');
j.edgesWith(e);
Get the edges coming from the collection (i.e. the source) going to another collection (i.e. the target).
- eles
The other collection.
- selector
The other collection, specified as a selector which is matched against all elements in the graph.
Examples
var j = cy.$('#j');
var e = cy.$('#e');
j.edgesTo(e);
Get the nodes connected to the edges in the collection.
- selector [optional]
An optional selector that is used to filter the resultant collection.
Examples
var je = cy.$('#je');
je.connectedNodes();
Get the edges connected to the nodes in the collection.
- selector [optional]
An optional selector that is used to filter the resultant collection.
Examples
var j = cy.$('#j');
j.connectedEdges();
Get source node of this edge.
- selector [optional]
An optional selector that is used to filter the resultant collection.
Examples
var je = cy.$('#je');
je.source();
Get source nodes connected to the edges in the collection.
- selector [optional]
An optional selector that is used to filter the resultant collection.
Examples
var edges = cy.$('#je, #kg');
edges.sources();
Get target node of this edge.
- selector [optional]
An optional selector that is used to filter the resultant collection.
Examples
var je = cy.$('#je');
je.target();
Get target nodes connected to the edges in the collection.
- selector [optional]
An optional selector that is used to filter the resultant collection.
Examples
var edges = cy.$('#je, #kg');
edges.targets();
Get edges parallel to those in the collection.
- selector [optional]
An optional selector that is used to filter the resultant collection.
Details
Two edges are said to be parallel if they connect the same two nodes. Any two parallel edges may connect nodes in the same direction, in which case the edges share the same source and target. They may alternatively connect nodes in the opposite direction, in which case the source and target are reversed in the second edge.
Examples
cy.$('#je').parallelEdges();
Get edges codirected to those in the collection.
- selector [optional]
An optional selector that is used to filter the resultant collection.
Details
Two edges are said to be codirected if they connect the same two nodes in the same direction: The edges have the same source and target.
Examples
cy.$('#je').codirectedEdges(); // only self in this case
From the set of calling nodes, get the nodes which are roots (i.e. no incoming edges, as in a directed acyclic graph).
- selector [optional]
An optional selector that is used to filter the resultant collection.
From the set of calling nodes, get the nodes which are leaves (i.e. no outgoing edges, as in a directed acyclic graph).
- selector [optional]
An optional selector that is used to filter the resultant collection.
Get edges (and their targets) coming out of the nodes in the collection.
- selector [optional]
An optional selector that is used to filter the resultant collection.
Examples
Get outgoers of j
:
cy.$('#j').outgoers();
Recursively get edges (and their targets) coming out of the nodes in the collection (i.e. the outgoers, the outgoers' outgoers, ...).
- selector [optional]
An optional selector that is used to filter the resultant collection.
Examples
Get successors of j
:
cy.$('#j').successors();
Get edges (and their sources) coming into the nodes in the collection.
- selector [optional]
An optional selector that is used to filter the resultant collection.
Examples
Get incomers of j
:
cy.$('#j').incomers();
Recursively get edges (and their sources) coming into the nodes in the collection (i.e. the incomers, the incomers' incomers, ...).
- selector [optional]
An optional selector that is used to filter the resultant collection.
Examples
Get predecessors of j
:
cy.$('#j').predecessors();
Algorithms
eles.bfs()
,Perform a breadth-first search within the elements in the collection.
- options
- root
The root nodes (selector or collection) to start the search from.
- visit: function(v, e, u, i, depth) [optional]
A handler function that is called when a node is visited in the search. The handler returns
true
when it finds the desired node, and it returnsfalse
to cancel the search. - v
The current node.
- e
The edge connecting the previous node to the current node.
- u
The previous node.
- i
The index indicating this node is the ith visited node.
- depth
How many edge hops away this node is from the root nodes.
- directed [optional]
A boolean indicating whether the algorithm should only go along edges from source to target (default
false
).
- root
Details
Note that this function performs a breadth-first search on only the subset of the graph in the calling collection.
This function returns an object that contains two collections ({ path: eles, found: node }
), the node found by the search and the path of the search:
- If no node was found, then
found
is empty. - If your handler function returns
false
, then the only the path up to that point is returned. - The path returned includes edges such that if
path[i]
is a node, thenpath[i - 1]
is the edge used to get to that node.
Examples
var bfs = cy.elements().bfs({
roots: '#e',
visit: function(v, e, u, i, depth){
console.log( 'visit ' + v.id() );
// example of finding desired node
if( v.data('weight') > 70 ){
return true;
}
// example of exiting search early
if( v.data('weight') < 0 ){
return false;
}
},
directed: false
});
var path = bfs.path; // path to found node
var found = bfs.found; // found node
// select the path
path.select();
eles.dfs()
,Perform a depth-first search within the elements in the collection.
- options
- root
The root nodes (selector or collection) to start the search from.
- visit: function(v, e, u, i, depth) [optional]
A handler function that is called when a node is visited in the search. The handler returns
true
when it finds the desired node, and it returnsfalse
to cancel the search. - v
The current node.
- e
The edge connecting the previous node to the current node.
- u
The previous node.
- i
The index indicating this node is the ith visited node.
- depth
How many edge hops away this node is from the root nodes.
- directed [optional]
A boolean indicating whether the algorithm should only go along edges from source to target (default
false
).
- root
Details
Note that this function performs a depth-first search on only the subset of the graph in the calling collection.
This function returns an object that contains two collections ({ path: eles, found: node }
), the node found by the search and the path of the search:
- If no node was found, then
found
is empty. - If your handler function returns
false
, then the only the path up to that point is returned. - The path returned includes edges such that if
path[i]
is a node, thenpath[i - 1]
is the edge used to get to that node.
Examples
var dfs = cy.elements().dfs({
roots: '#e',
visit: function(v, e, u, i, depth){
console.log( 'visit ' + v.id() );
// example of finding desired node
if( v.data('weight') > 70 ){
return true;
}
// example of exiting search early
if( v.data('weight') < 0 ){
return false;
}
},
directed: false
});
var path = dfs.path; // path to found node
var found = dfs.found; // found node
// select the path
path.select();
Perform Dijkstra's algorithm on the elements in the collection. This finds the shortest paths to all other nodes in the collection from the root node.
- options
- root
The root node (selector or collection) where the algorithm starts.
- weight: function(edge) [optional]
A function that returns the positive numeric weight for the edge.
- directed [optional]
A boolean indicating whether the algorithm should only go along edges from source to target (default
false
).
- root
Details
Note that this function performs Dijkstra’s algorithm on only the subset of the graph in the calling collection.
This function returns an object of the following form:
{
distanceTo: function( node ){ /* impl */ }
pathTo: function( node ){ /* impl */ }
}
distanceTo(node)
returns the distance from the source node to node
, and pathTo(node)
returns a collection containing the shortest path from the source node to node
. The path starts with the source node and includes the edges between the nodes in the path such that if pathTo(node)[i]
is an edge, then pathTo(node)[i-1]
is the previous node in the path and pathTo(node)[i+1]
is the next node in the path.
If no weight function is defined, a constant weight of 1 is used for each edge.
Examples
var dijkstra = cy.elements().dijkstra('#e', function(edge){
return edge.data('weight');
});
var pathToJ = dijkstra.pathTo( cy.$('#j') );
var distToJ = dijkstra.distanceTo( cy.$('#j') );
Perform the A* search algorithm on the elements in the collection. This finds the shortest path from the root node to the goal node.
- options
- root
The root node (selector or collection) where the search starts.
- goal
The goal node (selector or collection) where the search ends.
- weight: function(edge) [optional]
A function that returns the positive numeric weight for the edge.
- heuristic: function(node) [optional]
A function that returns an estimation (cannot be overestimation) on the shortest distance from the current node to the goal.
- directed [optional]
A boolean indicating whether the algorithm should only go along edges from source to target (default
false
).
- root
Details
Note that this function performs A* search on only the subset of the graph in the calling collection.
This function returns an object of the following form:
{
found, /* true or false */
distance, /* Distance of the shortest path, if found */
path /* Ordered collection of elements in the shortest path, if found */
}
Regarding optional options:
- If no weight function is defined, a constant weight of 1 is used for each edge.
- If no heuristic function is provided, a constant null function will be used, turning this into the same behaviour as Dijkstra’s algorithm. The heuristic should be monotonic (also called consistent) in addition to being ‘admissible’.
Examples
var aStar = cy.elements().aStar({ root: "#j", goal: "#e" });
aStar.path.select();
Perform the Floyd Warshall search algorithm on the elements in the collection. This finds the shortest path between all pairs of nodes.
- options
- weight: function(edge) [optional]
A function that returns the positive numeric weight for the edge.
- directed [optional]
A boolean indicating whether the algorithm should only go along edges from source to target (default
false
).
- weight: function(edge) [optional]
Details
This function returns an object of the following form:
{
/* function that computes the shortest path between 2 nodes
(either objects or selector strings) */
path: function( fromNode, toNode ){ /* impl */ },
/* function that computes the shortest distance between 2 nodes
(either objects or selector strings) */
distance: function( fromNode, toNode ){ /* impl */ }
}
If no weight function is defined, a constant weight of 1 is used for each edge.
Examples
var fw = cy.elements().floydWarshall();
fw.path('#k', '#g').select();
Perform the Bellman-Ford search algorithm on the elements in the collection. This finds the shortest path from the starting node to all other nodes in the collection.
- options
- root
The root node (selector or collection) where the search starts.
- weight: function(edge) [optional]
A function that returns the positive numeric weight for the edge.
- directed [optional]
A boolean indicating whether the algorithm should only go along edges from source to target (default
false
).
- root
Details
This function returns an object of the following form:
{
/* function that computes the shortest path from root node to the argument node
(either objects or selector string) */
pathTo: function(node){ /* impl */ },
/* function that computes the shortest distance from root node to argument node
(either objects or selector string) */
distanceTo: function(node){ /* impl */ },
/* true/false. If true, pathTo and distanceTo will be undefined */
hasNegativeWeightCycle
}
If no weight function is defined, a constant weight of 1 is used for each edge.
The Bellman-Ford algorithm is good at detecting negative weight cycles, but it can not return path or distance results if it finds them.
Examples
var bf = cy.elements().bellmanFord({ root: "#j" });
bf.pathTo('#g').select();
Perform Kruskal's algorithm on the elements in the collection, returning the minimum spanning tree, assuming undirected edges.
- function(edge) [optional]
A function that returns the positive numeric weight for the edge.
Details
Note that this function runs Kruskal’s algorithm on the subset of the graph in the calling collection.
Examples
cy.elements().kruskal();
Finds the minimum cut in a graph using the Karger-Stein algorithm. The optimal result is found with a high probability, but without guarantee.
Details
This function returns an object of the following form:
{
cut, /* Collection of edges that are in the cut */
partition1, /* Collection of nodes that are in the first partition */
partition2 /* Collection of nodes that are in the second partition */
}
Examples
var ks = cy.elements().kargerStein();
ks.cut.select();
Rank the nodes in the collection using the Page Rank algorithm.
- options
- dampingFactor [optional]
Numeric parameter for the algorithm.
- precision [optional]
Numeric parameter that represents the required precision.
- iterations [optional]
Maximum number of iterations to perform.
- dampingFactor [optional]
Details
This function returns an object of the following form:
{
/* function that computes the rank of a given node (either object or selector string) */
rank: function( node ){ /* impl */ }
}
Examples
var pr = cy.elements().pageRank();
console.log('g rank: ' + pr.rank('#g'));
eles.dc()
,Considering only the elements in the calling collection, calculate the degree centrality of the specified root node.
- options
- root
The root node (selector or collection) for which the centrality calculation is made.
- weight: function(edge) [optional]
A function that returns the weight for the edge.
- alpha [optional]
The alpha value for the centrality calculation, ranging on [0, 1]. With value 0 (default), disregards edge weights and solely uses number of edges in the centrality calculation. With value 1, disregards number of edges and solely uses the edge weights in the centrality calculation.
- directed [optional]
A boolean indicating whether the directed indegree and outdegree centrality is calculated (
true
) or whether the undirected centrality is calculated (false
, default).
- root
Details
For options.directed: false
, this function returns an object of the following form:
{
degree /* the degree centrality of the root node */
}
For options.directed: true
, this function returns an object of the following form:
{
indegree, /* the indegree centrality of the root node */
outdegree /* the outdegree centrality of the root node */
}
Examples
console.log( 'dc of j: ' + cy.$().dc({ root: '#j' }).degree );
eles.dcn()
, eles.degreeCentralityNormalised()
,Considering only the elements in the calling collection, calculate the normalised degree centrality of the nodes.
- options
- weight: function(edge) [optional]
A function that returns the weight for the edge.
- alpha [optional]
The alpha value for the centrality calculation, ranging on [0, 1]. With value 0 (default), disregards edge weights and solely uses number of edges in the centrality calculation. With value 1, disregards number of edges and solely uses the edge weights in the centrality calculation.
- directed [optional]
A boolean indicating whether the directed indegree and outdegree centrality is calculated (
true
) or whether the undirected centrality is calculated (false
, default).
- weight: function(edge) [optional]
Details
For options.directed: false
, this function returns an object of the following form:
{
/* the normalised degree centrality of the specified node */
degree: function( node ){ /* impl */ }
}
For options.directed: true
, this function returns an object of the following form:
{
/* the normalised indegree centrality of the specified node */
indegree: function( node ){ /* impl */ },
/* the normalised outdegree centrality of the specified node */
outdegree: function( node ){ /* impl */ }
}
Examples
var dcn = cy.$().dcn();
console.log( 'dcn of j: ' + dcn.degree('#j') );
eles.cc()
,Considering only the elements in the calling collection, calculate the closeness centrality of the specified root node.
- options
- root
The root node (selector or collection) for which the centrality calculation is made.
- weight: function(edge) [optional]
A function that returns the weight for the edge.
- directed [optional]
A boolean indicating whether the algorithm operates on edges in a directed manner from source to target (
true
) or whether the algorithm operates in an undirected manner (false
, default). - harmonic [optional]
A boolean indicating whether the algorithm calculates the harmonic mean (
true
, default) or the arithmetic mean (false
) of distances. The harmonic mean is very useful for graphs that are not strongly connected.
- root
Details
This function directly returns the numerical closeness centrality value for the specified root node.
Examples
console.log( 'cc of j: ' + cy.$().cc({ root: '#j' }) );
eles.ccn()
, eles.closenessCentralityNormalised()
,Considering only the elements in the calling collection, calculate the closeness centrality of the nodes.
- options
- weight: function(edge) [optional]
A function that returns the weight for the edge.
- directed [optional]
A boolean indicating whether the algorithm operates on edges in a directed manner from source to target (
true
) or whether the algorithm operates in an undirected manner (false
, default). - harmonic [optional]
A boolean indicating whether the algorithm calculates the harmonic mean (
true
, default) or the arithmetic mean (false
) of distances. The harmonic mean is very useful for graphs that are not strongly connected.
- weight: function(edge) [optional]
Details
This function returns an object of the form:
{
/* returns the normalised closeness centrality of the specified node */
closeness: function( node ){ /* impl */ }
}
Examples
var ccn = cy.$().ccn();
console.log( 'ccn of j: ' + ccn.closeness('#j') );
eles.bc()
,Considering only the elements in the calling collection, calculate the betweenness centrality of the nodes.
- options
- weight: function(edge) [optional]
A function that returns the weight for the edge.
- directed [optional]
A boolean indicating whether the algorithm operates on edges in a directed manner from source to target (
true
) or whether the algorithm operates in an undirected manner (false
, default).
- weight: function(edge) [optional]
Details
This function returns an object of the form:
{
/* returns the betweenness centrality of the specified node */
betweenness: function( node ){ /* impl */ },
/* returns the normalised betweenness centrality of the specified node */
betweennessNormalized: function( node ){ /* impl */ }
/* alias : betweennessNormalised() */
}
Examples
var bc = cy.$().bc();
console.log( 'bc of j: ' + bc.betweenness('#j') );
Compound nodes
These functions apply to compound graphs.
Get whether the node is a compound parent (i.e. a node containing one or more child nodes)
Get the compound parent node of each node in the collection.
- selector [optional]
A selector used to filter the resultant collection.
nodes.parents()
,Get all compound ancestor nodes (i.e. parents, parents' parents, etc.) of each node in the collection.
- selector [optional]
A selector used to filter the resultant collection.
Get all compound ancestors common to all the nodes in the collection, starting with the closest and getting progressively farther.
- selector [optional]
A selector used to filter the resultant collection.
Details
You can get the closest common ancestor via nodes.commonAncestors().first()
and the farthest via nodes.commonAncestors().last()
, because the common ancestors are in descending order of closeness.
Get all orphan (i.e. has no compound parent) nodes in the calling collection.
- selector [optional]
A selector used to filter the resultant collection.
Get all nonorphan (i.e. has a compound parent) nodes in the calling collection.
- selector [optional]
A selector used to filter the resultant collection.
Get all compound child (i.e. direct descendant) nodes of each node in the collection.
- selector [optional]
A selector used to filter the resultant collection.
Get all compound descendant (i.e. children, children's children, etc.) nodes of each node in the collection.
- selector [optional]
A selector used to filter the resultant collection.
Get all sibling (i.e. same compound parent) nodes of each node in the collection.
- selector [optional]
A selector used to filter the resultant collection.
Selectors
Notes & caveats
A selector functions similar to a CSS selector on DOM elements, but selectors in Cytoscape.js instead work on collections of graph elements. Note that wherever a selector may be specified as the argument to a function, a eles.filter()
-style filter function may be used in place of the selector. For example:
cy.$('#j').neighborhood(function( ele ){
return ele.isEdge();
});
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
Note that metacharacters ( ^ $ \ / ( ) | ? + * [ ] { } , . ) need to be escaped:
cy.filter('#some\\$funky\\@id');
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, i.e. 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 not defined, i.e. undefined
(e.g [^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 = 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']
)
!
(data attribute operator modifier)
Prepended to an operator so that it is negated (e.g. [foo !$= 'ar']
, [foo !>= 'a']
)
[[]]
(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
.
Edges
->
(directed edge selector) Matches edges for which the source and target subselectors match (e.g. .src -> .tgt
)
<->
(undirected edge selector) Matches edges for which the connected node subselectors match (e.g. .foo <-> .bar
)
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). A subject selector may not be used with an edge selector, because the edge ought to be the subject.
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.
Style
:visible
: Matches elements that are visible (i.e.display: element
andvisibility: visible
).:hidden
: Matches elements that are hidden (i.e.display: none
orvisibility: hidden
).:transparent
: Matches elements that are transparent (i.e.opacity: 0
for self or parents).:backgrounding
: Matches an element if its background image is currently loading.:nonbackgrounding
: Matches an element if its background image not currently loading; i.e. there is no image or the image is already loaded).
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).:childless
: Matches childless nodes (they have zero child nodes).:child
or:nonorphan
: Matches child nodes (they each have a parent).:orphan
: Matches orphan nodes (they each have no 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.
For simplicity and ease of use, specificity rules are completely ignored in stylesheets. For a given style property for a given element, the last matching selector wins.
Format
The style specified at initialisation can be in a function format, in a plain JSON format, or in a string format — the plain JSON format and string formats being more useful if you want to pull down the style from the server.
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:
cytoscape({
container: document.getElementById('cy'),
// ...
style: 'node { background-color: green; }' // probably previously loaded via ajax rather than hardcoded
// , ...
});
Plain JSON format
cytoscape({
container: document.getElementById('cy'),
// ...
style: [
{
selector: 'node',
style: {
'background-color': 'red'
}
}
// , ...
]
// , ...
});
Function format
cytoscape({
container: document.getElementById('cy'),
// ...
style: cytoscape.stylesheet()
.selector('node')
.style({
'background-color': 'blue'
})
// ...
// , ...
});
You may alternatively use css
in place of style
, e.g. .selector( ... ).css( ... )
or { selector: ..., css: ... }
.
Function values
In the JSON or function stylesheet formats, it is possible to specify a function as the value for a style property. In this manner, the style value can be specified via a function on a per-element basis.
Using a function as a style property value may be convenient in certain cases. However, it may not be a performant option. Thus, it may be worthwhile to use caching if possible, such as by using the lodash _.memoize()
function.
Note that if using functions as style values, it will not be possible to serialise and deserialise your stylesheet to JSON proper.
Example:
cytoscape({
container: document.getElementById('cy'),
// ...
style: cytoscape.stylesheet()
.selector('node')
.style({
'background-color': function( ele ){ return ele.data('bg') }
// which works the same as
// 'background-color': 'data(bg)'
})
// ...
// , ...
});
Property types
- 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
). Sizes are specified in model co-ordinates, so on-screen (rendered) sizes are as specified at zoom 1. - Opacity values are specified as numbers ranging on
0 <= opacity <= 1
. - Time is measured in units of ms or s.
- Angles are measured in radians (e.g.
3.14rad
) or degrees (e.g.180deg
).
Mappers
In addition to specifying the value of a property outright, the developer may also use a mapper to dynamically specify the property value.
If a mapping is defined, either define the mapped data for all elements or use selectors to limit the mapping to elements that have the mapped data defined. For example, the selector [foo]
will apply only to elements with the data field foo
defined.
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’sdescr
field in its data (i.e.ele.data("descr")
). This is useful for mapping to properties like label text content (thecontent
property).mapData()
specifies a linear mapping to an element’s data field. For example,mapData(weight, 0, 100, blue, red)
maps an element’s weight to gradients between blue and red for weights between 0 and 100. An element withele.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 withele.data("weight") === -1
would be mapped to blue.function( ele ){ ... }
A function may be passed as the value of a style property. The function has a singleele
argument which specifies the element for which the style property value is being calculated. The function must specify a valid value for the corresponding style property for all elements that its corresponding selector block applies. Note that while convenient, these functions ought to be inexpensive to execute, ideally cached with something like lodash’s_.memoize()
.
Node body
Shape:
width
: The width of the node’s body. This property can take on the special valuelabel
so the width is automatically based on the node’s label.height
: The height of the node’s body. This property can take on the special valuelabel
so the height is automatically based on the node’s label.shape
: The shape of the node’s body. Note that each shape fits within the specifiedwidth
andheight
, and so you may have to adjustwidth
andheight
if you desire an equilateral shape (i.e.width !== height
for several equilateral shapes). Only*rectangle
shapes are supported by compounds, because the dimensions of a compound are defined by the bounding box of the children. The following values are accepted:ellipse
triangle
rectangle
roundrectangle
bottomroundrectangle
cutrectangle
barrel
rhomboid
diamond
pentagon
hexagon
concavehexagon
heptagon
octagon
star
tag
vee
polygon
(custom polygon specified viashape-polygon-points
).
shape-polygon-points
: A space-separated list of numbers ranging on [-1, 1], representing alternating x and y values (i.e.x1 y1 x2 y2, x3 y3 ...
). This represents the points in the polygon for the node’s shape. The bounding box of the node is given by (-1, -1), (1, -1), (1, 1), (-1, 1).
Background:
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 background colour.
Border:
border-width
: The size of the node’s border.border-style
: The style of the node’s border; may besolid
,dotted
,dashed
, ordouble
.border-color
: The colour of the node’s border.border-opacity
: The opacity of the node’s border.
Padding:
A padding defines an addition to a node’s dimension. For example, padding
adds to a node’s outer (i.e. total) width and height. This can be used to add spacing around the label of width: label; height: label;
nodes, or it can be used to add spacing between a compound node parent and its children.
padding
: The amount of padding around all sides of the node. Either percentage or pixel value can be specified. For example, both50%
and50px
are acceptable values. By default, percentage padding is calculated as a percentage of node width.padding-relative-to
: Determines how padding is calculated if and only if the percentage unit is used. Accepts one of the keywords specified below.width
: calculate padding as a percentage the node width.height
: calculate padding as a percentage of the node height.average
: calculate padding as a percentage of the average of the node width and height.min
: calculate padding as a percentage of the minimum of the node width and height.max
: calculate padding as a percentage of the maximum of the node width and height.
Compound parent sizing:
compound-sizing-wrt-labels
: Whether to include labels of descendants in sizing a compound node; may beinclude
orexclude
.min-width
: Specifies the minimum (inner) width of the node’s body for a compound parent node (e.g.400px
). If the biases formin-width
do not add up to 100%, then the biases are normalised to a total of 100%.min-width-bias-left
: When a compound node is enlarged by itsmin-width
, this value specifies the percent of the extra width put on the left side of the node (e.g.50%
).min-width-bias-right
: When a compound node is enlarged by itsmin-width
, this value specifies the percent of the extra width put on the right side of the node (e.g.50%
).min-height
: Specifies the minimum (inner) height of the node’s body for a compound parent node (e.g.400px
). If the biases formin-height
do not add up to 100%, then the biases are normalised to a total of 100%.min-height-bias-top
: When a compound node is enlarged by itsmin-height
, this value specifies the percent of the extra width put on the top side of the node (e.g.50%
).min-height-bias-bottom
: When a compound node is enlarged by itsmin-height
, this value specifies the percent of the extra width put on the bottom side of the node (e.g.50%
).
Background image
A background image may be applied to a node’s body. The following properties support multiple values (space separated or array) with associated indices.
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.- You may use a data URI to use embedded images, thereby saving a HTTP request.
- Can specify multiple background images by separating each image with a space (space delimited format), but if using a non-string stylesheet, then using arrays are preferred.
- The images will be applied to the node’s body in the order given, layering one on top of each other.
- When specifying properties for multiple images, if the property for a given image is not provided, then the default value is used as fallback.
- SVG image considerations
- Using the
viewbox
attribute in SVG images may cause render problems in Firefox. - SVG images do not work consistently in Internet Explorer.
- Always include this XML header in each SVG image:
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE svg>
- Use encodeURIComponent to load SVG data.
var data = 'data:image/svg+xml;utf8,' + encodeURIComponent(svgFile);
- Using the
background-image-crossorigin
: All images are loaded with acrossorigin
attribute which may beanonymous
oruse-credentials
. The default is set toanonymous
.background-image-opacity
: The opacity of the background image.background-width
: Specifies the width of the image. A percent value (e.g.50%
) may be used to set the image width relative to the node width. If used in combination withbackground-fit
, then this value overrides the width of the image in calculating the fitting — thereby overriding the aspect ratio. Theauto
value is used by default, which uses the width of the image.background-height
: Specifies the height of the image. A percent value (e.g.50%
) may be used to set the image height relative to the node height. If used in combination withbackground-fit
, then this value overrides the height of the image in calculating the fitting — thereby overriding the aspect ratio. Theauto
value is used by default, which uses the height of the image.background-fit
: How the background image is fit to the node; may benone
for original size,contain
to fit inside node, orcover
to cover the node.background-repeat
: Whether to repeat the background image; may beno-repeat
,repeat-x
,repeat-y
, orrepeat
.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
).background-width-relative-to
: Changes whether the width is calculated relative to the width of the node or the width in addition to the padding; may beinner
orinclude-padding
. If not specified,include-padding
is used by default.background-height-relative-to
: Changes whether the height is calculated relative to the height of the node or the height in addition to the padding; may beinner
orinclude-padding
. If not specified,include-padding
is used by default.
The following properties apply to all images of a node:
background-clip
: How background image clipping is handled; may benode
for clipped to node shape ornone
for no clipping.
The following is an example of valid background image styling using JSON. The example images are taken from Wikimedia Commons with the Creative Commons license.
{
'background-image': [
'https://upload.wikimedia.org/wikipedia/commons/b/b4/High_above_the_Cloud_the_Sun_Stays_the_Same.jpg',
'https://upload.wikimedia.org/wikipedia/commons/thumb/f/fc/Pigeon_silhouette_4874.svg/1000px-Pigeon_silhouette_4874.svg.png'
],
'background-fit': 'cover cover',
`background-image-opacity`: 0.5
}
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%
or25
).pie-i-background-opacity
: The opacity of the node’s ith pie chart slice.
Edge line
These properties affect the styling of an edge’s line:
width
: The width of an edge’s line.curve-style
: The curving method used to separate two or more edges between two nodes; may behaystack
(default, very fast, bundled straight edges for which loops and compounds are unsupported),bezier
(bundled curved edges),unbundled-bezier
(curved edges for use with manual control points), orsegments
(a series of straight lines). Note thathaystack
edges work best withellipse
,rectangle
, or similar nodes. Smaller node shapes, liketriangle
, will not be as aesthetically pleasing. Also note that edge arrows are unsupported forhaystack
edges.line-color
: The colour of the edge’s line.line-style
: The style of the edge’s line; may besolid
,dotted
, ordashed
.
Bezier edges
For automatic, bundled bezier edges (curve-style: bezier
):
control-point-step-size
: From the line perpendicular from source to target, this value specifies the distance between successive bezier edges.control-point-distance
: A single value that overridescontrol-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
: A single value that weights control points along the line from source to target. The value usually ranges on [0, 1], with 0 towards the source node and 1 towards the target node — but larger or smaller values can also be used.edge-distances
: With valueintersection
(default), the line from source to target forcontrol-point-weight
is from the outside of the source node’s shape to the outside of the target node’s shape. With valuenode-position
, the line is from the source position to the target position. Thenode-position
option makes calculating edge points easier — but it should be used carefully because you can create invalid points thatintersection
would have automatically corrected.
Loop edges
For loops (i.e. same source and target):
loop-direction
: Determines the angle that loops extend from the node in cases when the source and target node of an edge is the same. The angle is specified from the 12 o’clock position and it progresses clockwise for increasing positive values. The default is-45deg
(extending to the upper left).loop-sweep
: Determines the angle between the leaving and returning edges in loops. Positive values result in clockwise looping and negative values result in counter-clockwise looping. Default is-90deg
.
Note that loops may only be bezier
or unbundled-bezier
for their curve-style
.
Unbundled bezier edges
For bezier edges with manual control points (curve-style: unbundled-bezier
):
control-point-distances
: A series of values that specify for each control point the distance perpendicular to a line formed from source to target, e.g.-20 20 -20
.control-point-weights
: A series of values that weights control points along a line from source to target, e.g.0.25 0.5 0.75
. A value usually ranges on [0, 1], with 0 towards the source node and 1 towards the target node — but larger or smaller values can also be used.edge-distances
: With valueintersection
(default), the line from source to target forcontrol-point-weights
is from the outside of the source node’s shape to the outside of the target node’s shape. With valuenode-position
, the line is from the source position to the target position. Thenode-position
option makes calculating edge points easier — but it should be used carefully because you can create invalid points thatintersection
would have automatically corrected.
Haystack edges
Loop edges and compound parent nodes are not supported by haystack edges. Haystack edges are a more performant replacement for plain, straight line edges.
For fast, straight line edges (curve-style: haystack
):
haystack-radius
: A value between 0 and 1 inclusive that indicates the relative radius used to position haystack edges on their connected nodes. The outside of the node is at 1, and the centre of the node is at 0.
Segments edges
For edges made of several straight lines (curve-style: segments
):
segment-distances
: A series of values that specify for each segment point the distance perpendicular to a line formed from source to target, e.g.-20 20 -20
.segment-weights
: A series of values that weights segment points along a line from source to target, e.g.0.25 0.5 0.75
. A value usually ranges on [0, 1], with 0 towards the source node and 1 towards the target node — but larger or smaller values can also be used.edge-distances
: With valueintersection
(default), the line from source to target forsegment-weights
is from the outside of the source node’s shape to the outside of the target node’s shape. With valuenode-position
, the line is from the source position to the target position. Thenode-position
option makes calculating edge points easier — but it should be used carefully because you can create invalid points thatintersection
would have automatically corrected.
Edge arrow
<pos>-arrow-color
: The colour of the edge’s source arrow.<pos>-arrow-shape
: The shape of the edge’s source arrow; may be one of:triangle
triangle-tee
triangle-cross
triangle-backcurve
vee
tee
square
circle
diamond
none
<pos>-arrow-fill
: The fill state of the edge’s source arrow; may befilled
orhollow
.arrow-scale
: Scaling for the arrow size; may be any number >= 0.
For each edge arrow property above, replace <pos>
with one of
source
: Pointing towards the source node, at the end of the edge.mid-source
: Pointing towards the source node, at the middle of the edge.target
: Pointing towards the target node, at the end of the edge.mid-target
: Pointing towards the target node, at the middle of the edge.
Only mid arrows are supported on haystack edges.
Edge endpoints
source-endpoint
& target-endpoint
: Specifies the endpoint of the source side of the edge and the target side of the edge, respectively. There are several options for how those properties can be set:
- A special, named value may be used.
outside-to-node
(default) indicates that the edge should be placed automatically to point towards the node’s position and be placed on the outside of the node’s shape.inside-to-node
indicates the edge should go all the way inside the node and point directly on the node’s position. This is the same as specifying0 0
.outside-to-line
indicates the edge endpoint should be placed outside the node’s shape where it would intersect the imaginary line from the source position to the target position. This value is useful for automatically avoiding invalid cases for bezier edges, especially with compound nodes.
- Two numbers may specify the endpoint. The numbers indicate a position relative to the source node’s position. The numbers can be specified as percent values (e.g.
50%
, which are relative to the node’s width and height respectively) or as absolute distances (e.g.100px
or2em
). - A single angle value (e.g.
90deg
or1.57rad
) may specify that the endpoint should be placed at where the line formed from the node’s position with the specified angle would intersect the node’s shape. The angle starts at 12 o’clock and progresses clockwise.
The endpoints for edges can be shifted away from the source and target node:
source-distance-from-node
: A value that shifts the edge away from the source node (default0px
).target-distance-from-node
: A value that shifts the edge away from the target node (default0px
).
Endpoint modification is not supported for curve-style: haystack
edges for performance reasons.
Visibility
display
: Whether to display the element; may beelement
for displayed ornone
for not displayed.- A
display: none
element does not take up space.- A
display: none
bundled bezier edge does not take up space in its bundle. - A
display: none
node hides its connected edges.
- A
- A
display: none
element is not interactive.
- A
visibility
: Whether the element is visible; may bevisible
orhidden
.- A
visibility: hidden
element does take up space.- A
visibility: hidden
bundled bezier edge does take up space in its bundle. - A
visibility: hidden
node does not hide its connected edges.
- A
- A
visibility: hidden
element is not interactive.
- A
opacity
: The opacity of the element, ranging from 0 to 1. Note that the opacity of a compound node parent affects the effective opacity of its children.- An
opacity: 0
element does take up space.- An
opacity: 0
bundled bezier edge does take up space in its bundle. - An
opacity: 0
node does not hide its connected edges.
- An
- An
opacity: 0
element is interactive.
- An
z-index
: An integer value that affects the relative draw order of elements. In general, an element with a higherz-index
will be drawn on top of an element with a lowerz-index
. Note that edges are under nodes despitez-index
, except when necessary for compound nodes.
Elements are drawn in a specific order based on compound depth (low to high), the element type (typically nodes above edges), and z-index (low to high). These styles affect the ordering:
z-compound-depth
: May bebottom
,orphan
,auto
(default), ortop
. The first drawn isbottom
, the second isorphan
, which is the same depth as the root of the compound graph, followed by the default ofauto
which draws in depth order from root to leaves of the compound graph. The last drawn istop
.z-index-compare
: May beauto
(default) ormanual
. Theauto
setting draws edges under nodes, whereasmanual
ignores this convention and draws solely based on thez-index
value.z-index
: An integer value that affects the relative draw order of elements. In general, an element with a higherz-index
will be drawn on top of an element with a lowerz-index
within the same depth.
Labels
Label text:
label
: The text to display for an element’s label.source-label
: The text to display for an edge’s source label.target-label
: The text to display for an edge’s target label.
Basic font styling:
color
: The colour of the element’s label.text-opacity
: The opacity of the label text, including its outline.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-transform
: A transformation to apply to the label text; may benone
,uppercase
, orlowercase
.
Wrapping text:
text-wrap
: A wrapping style to apply to the label text; may benone
for no wrapping (including manual newlines:\n
),wrap
for manual and/or autowrapping orellipsis
to truncate the string and append ‘…’ based ontext-max-width
.text-max-width
: The maximum width for wrapped text, applied whentext-wrap
is set towrap
orellipsis
. For only manual newlines (i.e.\n
), set a very large value like1000px
such that only your newline characters would apply.
Node label alignment:
text-halign
: The vertical alignment of a node’s label; may have valueleft
,center
, orright
.text-valign
: The vertical alignment of a node’s label; may have valuetop
,center
, orbottom
.
Edge label alignment:
source-text-offset
: For the source label of an edge, how far from the source node the label should be placed.target-text-offset
: For the target label of an edge, how far from the target node the label should be placed.
Margins:
text-margin-x
: A margin that shifts the label along the x-axis.text-margin-y
: A margin that shifts the label along the y-axis.source-text-margin-x
: (For the source label of an edge.)source-text-margin-y
: (For the source label of an edge.)target-text-margin-x
: (For the target label of an edge.)target-text-margin-y
: (For the target label of an edge.)
Rotating text:
text-rotation
: A rotation angle that is applied to the label.- For edges, the special value
autorotate
can be used to align the label to the edge. - For nodes, the label is rotated along its anchor point on the node, so a label margin may help for some usecases.
- The special value
none
can be used to denote0deg
. - Rotations works best with left-to-right text.
- For edges, the special value
source-text-rotation
: (For the source label of an edge.)target-text-rotation
: (For the target label of an edge.)
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.
Background:
text-background-color
: A colour to apply on the text background.text-background-opacity
: The opacity of the label background; the background is disabled for0
(default value).text-background-shape
: The shape to use for the label background, can berectangle
orroundrectangle
.text-background-padding
: A padding on the background of the label (e.g5px
); zero padding is used by default.
Border:
text-border-opacity
: The width of the border around the label; the border is disabled for0
(default value).text-border-width
: The width of the border around the label.text-border-style
: The style of the border around the label; may besolid
,dotted
,dashed
, ordouble
.text-border-color
: The colour of the border around the label.
Interactivity:
min-zoomed-font-size
: If zooming makes the effective font size of the label smaller than this, then no label is shown. Note that because of performance optimisations, the label may be shown at font sizes slightly smaller than this value. This effect is more pronounced at larger screen pixel ratios. However, it is guaranteed that the label will be shown at sizes equal to or greater than the value specified.text-events
: Whether events should occur on an element if the label receives an event; may beyes
orno
. You may want a style applied to the text on:active
so you know the text is activatable.
Events
events
: Whether events should occur on an element (e.g.tap
,mouseover
, etc.); may beyes
orno
. Forno
, the element receives no events and events simply pass through to the core/viewport. Theevents
property is per-element, so the value of a compound parent does not affect its children.text-events
: Whether events should occur on an element if the label receives an event; may beyes
orno
. You may want a style applied to the text on:active
so you know the text is activatable.
Overlay
These properties allow for the creation of overlays on top of nodes or edges, and are often used in the :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.
Ghost
The ghost properties allow for creating a ghosting effect, a semitransparent duplicate of the element drawn at an offset.
ghost
: Whether to use the ghost effect; may beyes
orno
.ghost-offset-x
: The horizontal offset used to position the ghost effect.ghost-offset-y
: The vertical offset used to position the ghost effect.ghost-opacity
: The opacity of the ghost effect.
Transition animation
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.250ms
).transition-timing-function
: An easing function that controls the animation progress curve; may be one of the following values. A visualisation of easings serves as a reference.linear
(default),spring( tension, friction )
(the demo has details for parameter values),cubic-bezier( x1, y1, x2, y2 )
(the demo has details for parameter values),ease
,ease-in
,ease-out
,ease-in-out
,ease-in-sine
,ease-out-sine
,ease-in-out-sine
,ease-in-quad
,ease-out-quad
,ease-in-out-quad
,ease-in-cubic
,ease-out-cubic
,ease-in-out-cubic
,ease-in-quart
,ease-out-quart
,ease-in-out-quart
,ease-in-quint
,ease-out-quint
,ease-in-out-quint
,ease-in-expo
,ease-out-expo
,ease-in-out-expo
,ease-in-circ
,ease-out-circ
,ease-in-out-circ
.
Core
These properties affect UI global to the graph, and apply only to the core. You can use the special core
selector string to set these properties.
Indicator:
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:
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.
Texture during viewport gestures:
outside-texture-bg-color
: The colour of the area outside the viewport texture wheninitOptions.textureOnViewport === true
.outside-texture-bg-opacity
: The opacity of the area outside the viewport texture.
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 instancetarget
: indicates the element or core that first caused the eventtype
: the event type string (e.g."tap"
)namespace
: the event namespace string (e.g."foo"
for"tap.foo"
)timeStamp
: Unix epoch time of event in milliseconds
Fields for only user input device events:
position
: indicates the model position of the eventrenderedPosition
: indicates the rendered position of the eventoriginalEvent
: the original user input device event object
Fields for only layout events:
layout
: indicates the corresponding layout that triggered the event (useful if running multiple layouts simultaneously)
Event bubbling
All events that occur on elements get bubbled up to compound parents and then 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.target
field, which indicates the originator of the event (i.e. eventObj.target === cy || eventObj.target === 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 pressedmouseup
: when the mouse button is releasedclick
: aftermousedown
thenmouseup
mouseover
: when the cursor is put on top of the targetmouseout
: when the cursor is moved off of the targetmousemove
: when the cursor is moved somewhere on top of the targettouchstart
: when one or more fingers starts to touch the screentouchmove
: when one or more fingers are moved on the screentouchend
: 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
orvmousedown
: normalised tap start event (eithermousedown
ortouchstart
)tapdrag
orvmousemove
: normalised move event (eithertouchmove
ormousemove
)tapdragover
: normalised over element event (eithertouchmove
ormousemove
/mouseover
)tapdragout
: normalised off of element event (eithertouchmove
ormousemove
/mouseout
)tapend
orvmouseup
: normalised tap end event (eithermouseup
ortouchend
)tap
orvclick
: normalised tap event (eitherclick
, ortouchstart
followed bytouchend
withouttouchmove
)taphold
: normalised tap hold eventcxttapstart
: normalised right-click mousedown or two-fingertapstart
cxttapend
: normalised right-clickmouseup
or two-fingertapend
cxttap
: normalised right-click or two-fingertap
cxtdrag
: normalised mousemove or two-finger drag aftercxttapstart
but beforecxttapend
cxtdragover
: when going over a node viacxtdrag
cxtdragout
: when going off a node viacxtdrag
boxstart
: when starting box selectionboxend
: when ending box selectionboxselect
: triggered on elements when selected by box selectionbox
: triggered on elements when inside the box onboxend
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 graphremove
: when an element is removed from the graphselect
: when an element is selectedunselect
: when an element is unselectedlock
: when an element is lockedunlock
: when an element is unlockedgrabon
: when an element is grabbed directly (including only the one node directly under the cursor or the user’s finger)grab
: when an element is grabbed (including all elements that would be dragged)drag
: when an element is grabbed and then movedfree
: when an element is freed (i.e. let go from being grabbed)position
: when an element changes positiondata
: when an element’s data is changedscratch
: when an element’s scratchpad data is changedstyle
: when an element’s style is changedbackground
: when a node’s background image is loaded
Graph events
These events are custom to Cytoscape.js, and they occur on the core.
layoutstart
: when a layout starts runninglayoutready
: when a layout has set initial positions for all the nodes (but perhaps not final positions)layoutstop
: when a layout has finished running completely or otherwise stopped runningready
: when a new instance of Cytoscape.js is ready to be interacted withdestroy
: when the instance of Cytoscape.js was explicitly destroyed by calling.destroy()
.render
: when the viewport is (re)renderedpan
: when the viewport is pannedzoom
: when the viewport is zoomedviewport
: when the viewport is changed (i.e. from apan
, azoom
, or from both when zooming about a point – e.g. pinch-to-zoom)resize
: when the viewport is resized (usually by callingcy.resize()
, awindow
resize, or toggling a class on the Cytoscape.js div)
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.
Each layout has its own algorithm for setting the position for each node. This algorithm influences the overall shape of the graph and the lengths of the edges. A layout’s algorithm can be customised by setting its options. Therefore, edge lengths can be controlled by setting the layout options appropriately.
For force-directed (physics) layouts, there is generally an option to set a weight to each edge to affect the relative edge lengths. Edge length can also be affected by options like spacing factors, angles, and overlap avoidance. Setting edge length depends on the particular layout, and some layouts will allow for more precise edge lengths than others.
null
The null
layout puts all nodes at (0, 0). It’s useful for debugging purposes.
Options
var 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
var options = {
name: 'random',
fit: true, // whether to fit to viewport
padding: 30, // fit padding
boundingBox: undefined, // constrain layout bounds; { x1, y1, x2, y2 } or { x1, y1, w, h }
animate: false, // whether to transition the node positions
animationDuration: 500, // duration of animation in ms if enabled
animationEasing: undefined, // easing of animation if enabled
animateFilter: function ( node, i ){ return true; }, // a function that determines whether the node should be animated. All nodes animated by default on animate enabled. Non-animated nodes are positioned immediately when the layout starts
ready: undefined, // callback on layoutready
stop: undefined, // callback on layoutstop
transform: function (node, position ){ return position; } // transform a given node position. Useful for changing flow direction in discrete layouts
};
cy.layout( options );
preset
The preset
layout puts nodes in the positions you specify manually.
Options
var options = {
name: 'preset',
positions: undefined, // map of (node id) => (position obj); or function(node){ return somPos; }
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)
fit: true, // whether to fit to viewport
padding: 30, // padding on fit
animate: false, // whether to transition the node positions
animationDuration: 500, // duration of animation in ms if enabled
animationEasing: undefined, // easing of animation if enabled
animateFilter: function ( node, i ){ return true; }, // a function that determines whether the node should be animated. All nodes animated by default on animate enabled. Non-animated nodes are positioned immediately when the layout starts
ready: undefined, // callback on layoutready
stop: undefined, // callback on layoutstop
transform: function (node, position ){ return position; } // transform a given node position. Useful for changing flow direction in discrete layouts
};
cy.layout( options );
grid
The grid
layout puts nodes in a well-spaced grid.
Options
var options = {
name: 'grid',
fit: true, // whether to fit the viewport to the graph
padding: 30, // padding used on fit
boundingBox: undefined, // constrain layout bounds; { x1, y1, x2, y2 } or { x1, y1, w, h }
avoidOverlap: true, // prevents node overlap, may overflow boundingBox if not enough space
avoidOverlapPadding: 10, // extra spacing around nodes when avoidOverlap: true
nodeDimensionsIncludeLabels: false, // Excludes the label when calculating node bounding boxes for the layout algorithm
spacingFactor: undefined, // Applies a multiplicative factor (>0) to expand or compress the overall area that the nodes take up
condense: false, // uses all available space on false, uses minimal space on true
rows: undefined, // force num of rows in the grid
cols: undefined, // force num of columns in the grid
position: function( node ){}, // returns { row, col } for element
sort: undefined, // a sorting function to order the nodes; e.g. function(a, b){ return a.data('weight') - b.data('weight') }
animate: false, // whether to transition the node positions
animationDuration: 500, // duration of animation in ms if enabled
animationEasing: undefined, // easing of animation if enabled
animateFilter: function ( node, i ){ return true; }, // a function that determines whether the node should be animated. All nodes animated by default on animate enabled. Non-animated nodes are positioned immediately when the layout starts
ready: undefined, // callback on layoutready
stop: undefined, // callback on layoutstop
transform: function (node, position ){ return position; } // transform a given node position. Useful for changing flow direction in discrete layouts
};
cy.layout( options );
circle
The circle
layout puts nodes in a circle.
Options
var options = {
name: 'circle',
fit: true, // whether to fit the viewport to the graph
padding: 30, // the padding on fit
boundingBox: undefined, // constrain layout bounds; { x1, y1, x2, y2 } or { x1, y1, w, h }
avoidOverlap: true, // prevents node overlap, may overflow boundingBox and radius if not enough space
nodeDimensionsIncludeLabels: false, // Excludes the label when calculating node bounding boxes for the layout algorithm
spacingFactor: undefined, // Applies a multiplicative factor (>0) to expand or compress the overall area that the nodes take up
radius: undefined, // the radius of the circle
startAngle: 3 / 2 * Math.PI, // where nodes start in radians
sweep: undefined, // how many radians should be between the first and last node (defaults to full circle)
clockwise: true, // whether the layout should go clockwise (true) or counterclockwise/anticlockwise (false)
sort: undefined, // a sorting function to order the nodes; e.g. function(a, b){ return a.data('weight') - b.data('weight') }
animate: false, // whether to transition the node positions
animationDuration: 500, // duration of animation in ms if enabled
animationEasing: undefined, // easing of animation if enabled
animateFilter: function ( node, i ){ return true; }, // a function that determines whether the node should be animated. All nodes animated by default on animate enabled. Non-animated nodes are positioned immediately when the layout starts
ready: undefined, // callback on layoutready
stop: undefined, // callback on layoutstop
transform: function (node, position ){ return position; } // transform a given node position. Useful for changing flow direction in discrete layouts
};
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
value in ele.scratch()
.
Options
var options = {
name: 'concentric',
fit: true, // whether to fit the viewport to the graph
padding: 30, // the padding on fit
startAngle: 3 / 2 * Math.PI, // where nodes start in radians
sweep: undefined, // how many radians should be between the first and last node (defaults to full circle)
clockwise: true, // whether the layout should go clockwise (true) or counterclockwise/anticlockwise (false)
equidistant: false, // whether levels have an equal radial distance betwen them, may cause bounding box overflow
minNodeSpacing: 10, // min spacing between outside of nodes (used for radius adjustment)
boundingBox: undefined, // constrain layout bounds; { x1, y1, x2, y2 } or { x1, y1, w, h }
avoidOverlap: true, // prevents node overlap, may overflow boundingBox if not enough space
nodeDimensionsIncludeLabels: false, // Excludes the label when calculating node bounding boxes for the layout algorithm
height: undefined, // height of layout area (overrides container height)
width: undefined, // width of layout area (overrides container width)
spacingFactor: undefined, // Applies a multiplicative factor (>0) to expand or compress the overall area that the nodes take up
concentric: function( node ){ // returns numeric value for each node, placing higher nodes in levels towards the centre
return node.degree();
},
levelWidth: function( nodes ){ // the letiation of concentric values in each level
return nodes.maxDegree() / 4;
},
animate: false, // whether to transition the node positions
animationDuration: 500, // duration of animation in ms if enabled
animationEasing: undefined, // easing of animation if enabled
animateFilter: function ( node, i ){ return true; }, // a function that determines whether the node should be animated. All nodes animated by default on animate enabled. Non-animated nodes are positioned immediately when the layout starts
ready: undefined, // callback on layoutready
stop: undefined, // callback on layoutstop
transform: function (node, position ){ return position; } // transform a given node position. Useful for changing flow direction in discrete layouts
};
cy.layout( options );
breadthfirst
The breadthfirst
layout puts nodes in a hierarchy, based on a breadthfirst traversal of the graph.
Options
var options = {
name: 'breadthfirst',
fit: true, // whether to fit the viewport to the graph
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
spacingFactor: 1.75, // positive spacing factor, larger => more space between nodes (N.B. n/a if causes overlap)
boundingBox: undefined, // constrain layout bounds; { x1, y1, x2, y2 } or { x1, y1, w, h }
avoidOverlap: true, // prevents node overlap, may overflow boundingBox if not enough space
nodeDimensionsIncludeLabels: false, // Excludes the label when calculating node bounding boxes for the layout algorithm
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)
animate: false, // whether to transition the node positions
animationDuration: 500, // duration of animation in ms if enabled
animationEasing: undefined, // easing of animation if enabled,
animateFilter: function ( node, i ){ return true; }, // a function that determines whether the node should be animated. All nodes animated by default on animate enabled. Non-animated nodes are positioned immediately when the layout starts
ready: undefined, // callback on layoutready
stop: undefined, // callback on layoutstop
transform: function (node, position ){ return position; } // transform a given node position. Useful for changing flow direction in discrete layouts
};
cy.layout( options );
cose
The cose
(Compound Spring Embedder) layout uses a physics simulation to lay out graphs. It works well with noncompound graphs and it has additional logic to support compound graphs well.
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.
The cose
layout is very fast and produces good results. The cose-bilkent
extension is an evolution of the algorithm that is more computationally expensive but produces near-perfect results.
Options
var options = {
name: 'cose',
// Called on `layoutready`
ready: function(){},
// Called on `layoutstop`
stop: function(){},
// Whether to animate while running the layout
// true : Animate continuously as the layout is running
// false : Just show the end result
// 'end' : Animate with the end result, from the initial positions to the end positions
animate: true,
// Easing of the animation for animate:'end'
animationEasing: undefined,
// The duration of the animation for animate:'end'
animationDuration: undefined,
// A function that determines whether the node should be animated
// All nodes animated by default on animate enabled
// Non-animated nodes are positioned immediately when the layout starts
animateFilter: function ( node, i ){ return true; },
// The layout animates only after this many milliseconds for animate:true
// (prevents flashing on fast runs)
animationThreshold: 250,
// Number of iterations between consecutive screen positions update
// (0 -> only updated on the end)
refresh: 20,
// Whether to fit the network view after when done
fit: true,
// Padding on fit
padding: 30,
// Constrain layout bounds; { x1, y1, x2, y2 } or { x1, y1, w, h }
boundingBox: undefined,
// Excludes the label when calculating node bounding boxes for the layout algorithm
nodeDimensionsIncludeLabels: false,
// Randomize the initial positions of the nodes (true) or use existing positions (false)
randomize: false,
// Extra spacing between components in non-compound graphs
componentSpacing: 40,
// Node repulsion (non overlapping) multiplier
nodeRepulsion: function( node ){ return 2048; },
// Node repulsion (overlapping) multiplier
nodeOverlap: 4,
// Ideal edge (non nested) length
idealEdgeLength: function( edge ){ return 32; },
// Divisor to compute edge forces
edgeElasticity: function( edge ){ return 32; },
// Nesting factor (multiplier) to compute ideal edge length for nested edges
nestingFactor: 1.2,
// Gravity force (constant)
gravity: 1,
// Maximum number of iterations to perform
numIter: 1000,
// Initial temperature (maximum node displacement)
initialTemp: 1000,
// Cooling factor (how the temperature is reduced between consecutive iterations
coolingFactor: 0.99,
// Lower temperature threshold (below this point the layout will end)
minTemp: 1.0,
// Pass a reference to weaver to use threads for calculations
weaver: false
};
cy.layout( options );
Layout manipulation
Layouts have a set of functions available to them, which allow for more complex behaviour than the primary run-one-layout-at-a-time usecase. A new, developer accessible layout can be made via cy.layout()
.
layout.start()
,Start running the layout.
Details
If the layout is asynchronous (i.e. continuous), then calling layout.run()
simply starts the layout. Synchronous (i.e. discrete) layouts finish before layout.run()
returns. Whenever the layout is started, the layoutstart
event is emitted.
The layout will emit the layoutstop
event when it has finished or has been otherwise stopped (e.g. by calling layout.stop()
). The developer can bind to layoutstop
using layout.on()
or setting the layout options appropriately with a callback.
Examples
var layout = cy.layout({ name: 'random' });
layout.run();
Stop running the (asynchronous/discrete) layout.
Details
Calling layout.stop()
stops an asynchronous (continuous) layout. It’s useful if you want to prematurely stop a running layout.
Examples
var layout = cy.layout({ name: 'cose' });
layout.run();
// some time later...
setTimeout(function(){
layout.stop();
}, 100);
Layout events
layout.bind()
, layout.listen()
, layout.addListener()
,Bind to events that are emitted by the layout.
layout.pon()
,Get a promise that is resolved with the first of any of the specified events emitted on the layout.
- events
A space separated list of event names.
Examples
var layout = cy.layout({ name: 'random' });
layout.pon('layoutstop').then(function( event ){
console.log('layoutstop promise fulfilled');
});
layout.run();
Bind to events that are emitted by the layout, and run the handler only once.
layout.off()
, layout.unbind()
, layout.unlisten()
,Remove event handlers on the layout.
- events
A space separated list of event names.
- handler [optional]
A reference to the handler function to remove.
layout.trigger()
,Emit one or more events on the layout.
- events
A space separated list of event names to emit.
- extraParams [optional]
An array of additional parameters to pass to the handler.
Animations
An animation represents a visible change in state over a duration of time for a single element. Animations can be generated via cy.animation()
(for animations on the viewport) and ele.animation()
(for animations on graph elements).
Animation manipulation
Requests that the animation be played, starting on the next frame. If the animation is complete, it restarts from the beginning.
Examples
var jAni = cy.$('#j').animation({
style: {
'background-color': 'red',
'width': 75
},
duration: 1000
});
jAni.play();
Get or set how far along the animation has progressed.
Get the progress of the animation in percent.
Set the progress of the animation in percent.
- progress
The progress in percent (i.e. between 0 and 1 inclusive) to set to the animation.
Get the progress of the animation in milliseconds.
Set the progress of the animation in milliseconds.
- time
The progress in milliseconds (i.e. between 0 and the duration inclusive) to set to the animation.
Rewind the animation to the beginning.
Fastforward the animation to the end.
Examples
var jAni = cy.$('#j').animation({
style: {
'background-color': 'red',
'width': 75
},
duration: 1000
});
// set animation to 50% and then play
jAni.progress(0.5).play();
Pause the animation, maintaining the current progress.
Examples
var j = cy.$('#j');
var jAni = j.animation({
style: {
'background-color': 'red',
'width': 75
},
duration: 1000
});
jAni.play();
// pause about midway
setTimeout(function(){
jAni.pause();
}, 500);
Stop the animation, maintaining the current progress and removing the animation from any associated queues.
Details
This function is useful in situations where you don’t want to run an animation any more. Calling ani.stop()
is analogous to calling ele.stop()
in that the animation is no longer queued.
Calling ani.stop()
makes animation frames faster by reducing the number of animations to check per element per frame. You should call ani.stop()
when you want to clean up an animation, especially in situations with many animations. You can still reuse a stopped animation, but an animation that has not been stopped can not be garbage collected unless its associated target (i.e. element or core instance) is garbage collected as well.
Examples
var j = cy.$('#j');
var jAni = j.animation({
style: {
'background-color': 'red',
'width': 75
},
duration: 1000
});
jAni.play();
// stop about midway
setTimeout(function(){
jAni.stop();
}, 500);
Apply the animation at its current progress.
Details
This function allows you to step directly to a particular progress of the animation while it’s paused.
Examples
var jAni = cy.$('#j').animation({
style: {
'background-color': 'red',
'width': 75
},
duration: 1000
});
jAni.progress(0.5).apply();
Reverse the animation such that its starting conditions and ending conditions are reversed.
Examples
var jAni = cy.$('#j').animation({
style: {
'background-color': 'red',
'width': 75
},
duration: 1000
});
jAni
.play() // start
.promise('completed').then(function(){ // on next completed
jAni
.reverse() // switch animation direction
.rewind() // optional but makes intent clear
.play() // start again
;
})
;
Get a promise that is fulfilled with the specified animation event.
Get a promise that is fulfilled with the next completed
event.
Get a promise that is fulfilled with the specified animation event.
- animationEvent
A string for the event name;
completed
orcomplete
for completing the animation orframe
for the next frame of the animation.
Examples
When ani.apply()
has updated the element style:
var jAni = cy.$('#j').animation({
style: {
'background-color': 'red',
'width': 75
},
duration: 1000
});
jAni.progress(0.5).apply().promise('frame').then(function(){
console.log('j has now has its style at 50% of the animation');
});
When ani.play()
is done:
var jAni = cy.$('#j').animation({
style: {
height: 60
},
duration: 1000
});
jAni.play().promise().then(function(){
console.log('animation done');
});
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 their own custom extension.
The following diagramme summarises the extensions of Cytoscape.js, which are discussed in further detail elsewhere in this documentation.
Extensions
You can use an extension (e.g. cy-ext
) as follows with cytoscape.use()
:
cytoscape.use( require('cy-ext') );
Using import
, the above example would be:
import ext from 'cy-ext';
cytoscape.use( ext );
The extensions below are a curated list. To add your extension, please submit a request that includes your extension’s URL and a one line description.
denotes a first-party extension, one that is maintained by groups associated with the Cytoscape Consortium.
denotes a third-party extension, one that is maintained by outside developers.
UI extensions
-
automove
: Automatically update node positions based on specified rules (e.g. synching node movements, constraining movements, etc.) -
autopan-on-drag
: Automatically pan the viewport when nodes are dragged outside of the viewport bounds. -
canvas
: An extension to create a canvas over or under a Cytoscape graph. Useful for customizing nodes/edges, drawing backgrounds, etc. -
cerebralweb
: Enable fast and interactive visualisation of molecular interaction networks stratified based on subcellular localisation or other custom annotation. -
context-menus
: A traditional right click menu -
cxtmenu
: A circular context menu that allows for one-swipe commands on the graph. -
edge-bend-editing
: UI for editing edge bends (segment edges and bezier edges) -
edge-editation
: Adds handles to nodes and allows creation of different types of edges -
edgehandles
: UI for connecting nodes with edges. -
expand-collapse
: Provides an API for expanding and collapsing compound parent nodes -
grid-guide
: Adds grid and snapping functionality to Cytoscape graphs -
navigator
: A bird’s eye view widget of the graph. -
node-html-label
: Allows HTML to be specified as the labels for nodes. -
node-resize
: A highly customisable node resizing extension with a traditional UI. -
noderesize
: A minimalistic node resize control. -
panzoom
: A panzoom UI widget. -
popper
: A wrapper for Popper.js that lets you position divs relative to Cytoscape elements (can be used with Tippy.js to create tooltips). -
qtip
: A wrapper that lets you use qTips on graph elements or the graph background. -
snap-to-grid
: Adds snap-to-grid and gridlines to Cytoscape.js graphs. -
supportimages
: Support images on Cytoscape.js. -
toolbar
: Allow a user to create a custom toolbar to add next to a Cytoscape core instance.
Layout extensions
-
arbor
: The Arbor physics simulation layout. It’s a basic physics layout. -
cola
: The Cola.js physics simulation layout. Cola makes beautiful layout results, it animates very smoothly, and it has great options for controlling the layout. -
cose-bilkent
: The CoSE layout by Bilkent with enhanced compound node placement. CoSE Bilkent gives near-perfect end results. However, it’s more expensive than the version of CoSE directly included with Cytoscape.js. -
dagre
: The Dagre layout for DAGs and trees. -
euler
: Euler is a fast, small file-size, high-quality force-directed (physics simulation) layout. It is excellent for non-compound graphs, and it has basic support for compound graphs. -
klay
: Klay is a layout that works well for most types of graphs. It gives good results for ordinary graphs, and it handles DAGs and compound graphs very nicely. -
ngraph.forcelayout
: A physics simulation layout that works particularly well on planar graphs. It is relatively fast. -
polywas
: A layout for GWAS (genome-wide association study) data illustrating inter-locus relationships. -
spread
: The speedy Spread physics simulation layout. It tries to use all the viewport space, but it can be configured to produce a tighter result. It uses Fruchterman-Reingold initially, and it uses Gansner and North for the spread phase. -
springy
: The Springy physics simulation layout. It’s a basic physics layout.
API extensions
-
clipboard
: Adds copy-paste utilities to Cytoscape.js -
graphml
: Adds GraphML import and export functionality to Cytoscape.js -
undo-redo
: Adds undo-redo APIs to Cytoscape.js -
view-utilities
: Adds search and highlight APIs to Cytoscape.js
API
To register an extension, make the following call: 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. For example, cytoscape( 'collection', 'fooBar', function(){ return 'baz'; } )
registers eles.fooBar()
.
Autoscaffolding
There is a Slush project for Cytoscape.js such that the full project scaffolding for a new extension is automatically generated for you. By following the included instructions, you can easily create Cytoscape.js extensions that are well organised, easily maintained, and published.
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 expensive. Only drawing circles and straight lines is cheap, but drawing complex graphs is less so.
- Edges are particularly expensive to render. Multigraphs become even more expensive with the need for bezier curve edges.
- The performance of rendering a (bitmap) canvas is a function of the area that it needs to render. As such, an increased pixel ratio (as in high density displays, like on the iPad) can decrease rendering performance.
Optimisations
You can get much better performance out of Cytoscape.js by tuning your options, in descending order of significance:
- Use
cy.getElementById()
: Thecy.getElementById('foo')
function is the fastest way to get an element by ID. You can usecy.$id('foo')
to type less. Searching by selector generally means you have to check each element in the collection, whereas getting by ID is much faster as a lookup table is used. The single ID selector (e.g.cy.$('#foo')
) is optimised to also use the lookup table, but it does have the added cost of parsing. - Batch element modifications : Use
cy.batch()
to modify many elements at once. - Animations : You will get better performance without animations. If using animations anyway:
eles.flashClass()
is a cheaper alternative than a smooth animation.- 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 havetransition-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.
- Function style property values : While convenient, function style property values can be expensive. Thus, it may be worthwhile to use caching if possible, such as by using the lodash
_.memoize()
function. If your style property value is a simple passthrough or linear mapping, consider usingdata()
ormapData()
instead. - 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. - Background and outlines increase the expense of rendering labels.
- Simplify edge style : Drawing edges can be expensive.
- Set your edges
curve-style
tohaystack
in your stylesheet. Haystack edges are straight lines, which are much less expensive to render thanbezier
edges. This is the default 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.
- Edge arrows are expensive to render, so consider not using them if they do not have any semantic meaning in your graph.
- Opaque edges with arrows are more than twice as fast as semitransparent edges with arrows.
- Set your edges
- Simplify node style : Certain styles for nodes can be expensive.
- Background images are very expensive in certain cases. The most performant background images are non-repeating (
background-repeat: no-repeat
) and non-clipped (background-clip: none
). For simple node shapes like squares or circles, you can usebackground-fit
for scaling and preclip your images to simulate software clipping (e.g. with Gulp so it’s automated). In lieu of preclipping, you could make clever use of PNGs with transparent backgrounds. - 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.
- Background images are very expensive in certain cases. The most performant background images are non-repeating (
- Set a lower pixel ratio : Because it is more expensive to render more pixels, you can set
pixelRatio
to1
in the initialisation options to increase performance for large graphs on high density displays. However, this makes the rendering less crisp. - Compound nodes : Compound nodes make style calculations and rendering more expensive. If your graph does not require compound nodes, you can improve performance by not using compound parent nodes.
- Hide edges during interactivity : Set
hideEdgesOnViewport
totrue
in your initialisation options. This can make interactivity less expensive for very large graphs by hiding edges during pan, mouse wheel zoom, pinch-to-zoom, and node drag actions. This option makes a difference on only very, very large graphs. - Recycle large instances : Large instances can use a lot of memory, mostly due to canvas use. Recyling an instance will help to keep your memory usage lower than calling
cy.destroy()
, because you won’t grow the heap as much and you won’t invoke the garbage collector as much. - Use textured zoom & pan : Set
textureOnViewport
totrue
in your initialisation options. Rather than rerendering the entire scene, this makes a texture cache of the viewport at the start of pan and zoom operations, and manipulates that instead. Makes panning and zooming smoother for very large graphs. This option makes a difference on only very, very large graphs. The renderer has support for more general texture caching, and sotextureOnViewport
is only useful if you really need the absolute cheapest option.