Skip to content

Getting started

Choose a runtime entry, create a graph and handle readiness.

#Package and runtime

The preview is currently 4.0.0-unstable and has not been published to npm. Use a local build of this repository to try it. The import examples below assume your project resolves cytoscape to that local package.

To build locally, use Node 24 or later in the repository root:

Terminal window
npm install
npm run build
npm run build:types

Then install the local package in your application (replace the path):

Terminal window
npm install /absolute/path/to/cytoscape.js

Choose the full entry for an interactive browser graph, or the headless entry for analysis on a server. Node 24 or later and Bun 1.4.0 or later support headless work. See Supported environments for details.

#First graph and readiness

In a browser application with a module bundler and WebGPU, put the container, its size and the script together. You will see two labelled nodes, Alpha and Beta, joined by an edge:

<div id="graph" style="width: 800px; max-width: 100%; height: 600px"></div>
<script type="module">
import cytoscape from 'cytoscape';
try {
const cy = cytoscape({
container: document.getElementById('graph'),
elements: [
{ data: { id: 'a', label: 'Alpha' } },
{ data: { id: 'b', label: 'Beta' } },
{ data: { id: 'ab', source: 'a', target: 'b' } },
],
style: { nodes: { label: 'data(label)' } },
layout: { name: 'grid' },
});
await cy.ready;
} catch (error) {
document.getElementById('graph').textContent = error.message;
}
</script>

The rendered build needs a non-zero-size container and WebGPU. The factory throws immediately if the browser has no navigator.gpu; a browser can still expose WebGPU while failing to acquire a usable adapter, in which case cy.ready rejects. Keep both stages in the error path of an application. The factory creates the model synchronously, ingests initial elements through a bulk path and starts the requested layout; ready reports renderer readiness, not a general promise that makes graph reads asynchronous.

For CPU-only work, omit the container or import the explicit headless entry:

import cytoscape from 'cytoscape/headless';
const cy = cytoscape({
elements: [
{ data: { id: 'a' } },
{ data: { id: 'b' } },
{ data: { id: 'ab', source: 'a', target: 'b', weight: 2 } },
],
});
const path = cy.elements().dijkstra({
root: cy.getElementById('a'),
weight: edge => edge.data('weight'),
}).pathTo(cy.getElementById('b'));

cytoscape/headless has no renderer or WebGPU code. It includes the CPU algorithm path and all layouts, with a worker pool where available. If a headless process needs an explicit GPU algorithm executor or GPU force host, use cytoscape/headless-gpu; it does not provide png(), jpg(), pointer gestures or a canvas. An explicit GPU executor rejects when the required device is not available. An auto executor can choose a supported CPU or worker lane according to that algorithm's documented policy.

In a browser without a module bundler, the full package also builds UMD files. Serve the locally built UMD bundle from your application and use the global cytoscape factory:

<div id="graph" style="width: 800px; max-width: 100%; height: 600px"></div>
<script src="/vendor/cytoscape.min.js"></script>
<script>
const cy = cytoscape({
container: document.getElementById('graph'),
elements: [{ data: { id: 'a' } }],
});
</script>

Serve the bundle from your application, replacing /vendor/cytoscape.min.js with its actual path. A container-backed instance has the same WebGPU requirement regardless of how its JavaScript was loaded.

#Layout and size

The first-graph examples set the container's width and height inline. You can move these rules into your stylesheet; keep a non-zero width and height.

After construction, query cy.ready, then read or mutate the core and its collections synchronously. For a later layout, create a handle, call run(), and await promise() when completion matters:

const layout = cy.layout({ name: 'circle', fit: true });
layout.run();
await layout.promise();

Layout lifecycle events are emitted on the core (layoutstart, layoutready, layoutstop). Layout objects are handles, not event emitters.

The API reference describes the contract for constructor options, built-in layouts, algorithms and their failure modes. See notation for the graph data forms, styles for sheet values and layouts for layout scope and extension behavior.

Choose an entry according to the environment and the work it needs to do. The headless entry supports graph data, queries, CPU algorithms and layouts. Rendering requires a browser page with a usable WebGPU adapter.

#Requirements and support

Capability Entry Requirements
Headless graph operations cytoscape/headless ES2022, typed arrays, TextEncoder with encodeInto, TextDecoder and queueMicrotask.
Worker algorithms and force simulation Any entry Node/Bun worker_threads, or a browser page with Worker, Blob and URL.createObjectURL.
GPU algorithms and force simulation cytoscape/headless-gpu or cytoscape navigator.gpu and a usable adapter. No canvas is needed for compute.
Interactive rendering and image export cytoscape A browser page with WebGPU and a container with a non-zero size. No Canvas 2D fallback.

Browser and GPU capabilities depend on the operating system, drivers and browser settings. Limited support applies to the listed versions; check the required APIs when using another version or host.

Environment Headless graph work Workers Rendering / GPU compute Support
Node 24 or later Yes Yes Unavailable without navigator.gpu. Supported.
Bun 1.4.0 or later Yes Yes, using worker_threads No WebGPU in tested Bun 1.4.0 and 1.4.3. Supported.
Cloudflare Workers (workerd) Yes, using cytoscape/headless No worker pool; auto runs on the current thread. No. Supported.
Other V8 isolate environments Expected where the required APIs are present. No worker pool. No. Compatibility must be checked in the target host.
Chromium and WebKit pages Yes Yes Available where WebGPU and an adapter are available. Supported; GPU features require a usable adapter.
Chromium and WebKit dedicated, shared and service workers Yes No pool; work runs on the hosting worker's thread. Rendering unavailable; GPU compute unmeasured. Headless supported.
Firefox pages and workers Tested on Firefox 151. In pages; no pool in worker contexts. Depends on WebGPU availability; Linux WebGPU was unavailable in testing. Limited support: Firefox 151.
Electron Main process supports headless operations and workers. Yes in the main process. Renderer process needs WebGPU; Linux may require explicit flags. Limited support: Electron 44.4.5.
Tauri with a Node sidecar The sidecar follows Node requirements. The sidecar's workers. Depends on the system webview. Sidecar only; webview compatibility varies.
React Native / Hermes Requires a TextDecoder polyfill and compatible modern Hermes. No. No. Experimental; not supported.
QuickJS-ng and GraalJS Requires UTF-8 codec shims; GraalJS also needs queueMicrotask. No. No. Experimental; not supported.
Deno Not evaluated. Not evaluated. Not evaluated. Not supported.
Audio worklets Required APIs are missing in tested engines. No. No. Not supported.

#Choosing a runtime

A headless instance does not become rendered when it runs in a browser. Supply a container with the full entry to display a graph. When WebGPU is absent, construction with a container throws. When adapter acquisition fails later, cy.ready rejects. Handle both failures in your application.

A graph hosted inside a worker already runs off the page's main thread. Its algorithms can execute on that thread without creating a nested pool. The page's renderer: { worker: true } option is a separate feature: it hosts rendering through an OffscreenCanvas belonging to the page.

Edge runtimes often impose CPU limits. Ingest, algorithms and layouts all consume that budget, even when the library itself fits in the deployment. Measure your actual graph and operation mix against the host's current limits.

Electron applications on Linux may need to configure WebGPU before the app's ready event. Testing with X11 and --use-angle=vulkan --enable-features=Vulkan reached a hardware adapter; --enable-unsafe-webgpu alone used a software adapter. A web page cannot set these application flags.

#Error types

#cytoscape.CancelledError

// Thrown (as a rejection) by a cancelled run: an async algorithm whose handle's cancel() was called, a layout's promise() after layout.cancel(), or either when cy.destroy() ran while the run was in flight
cytoscape.CancelledError: CancelledError

Thrown (as a rejection) by a cancelled run: an async algorithm whose handle's cancel() was called, a layout's promise() after layout.cancel(), or either when cy.destroy() ran while the run was in flight. error.name is 'CancelledError', so a .catch can tell a cancellation from a defect without importing the class.

Returns CancelledError

Example

const error = new cytoscape.CancelledError();
console.log(error instanceof cytoscape.CancelledError); // true

Example graph and handle setup

#cytoscape.GpuUnfitError

// A graph or algorithm input exceeds the GPU device's limits
cytoscape.GpuUnfitError: GpuUnfitError

A graph or algorithm input exceeds the GPU device's limits.

Adding, loading or patching elements on a rendered core can throw this error before changing the graph. Mounting a graph that does not fit rejects cy.ready.

An explicit GPU algorithm rejects with this error when its input does not fit. With executor: 'auto', that algorithm falls back to the CPU instead. Other GPU errors still propagate.

Test error instanceof cytoscape.GpuUnfitError, or check error.name === 'GpuUnfitError', to distinguish this failure.

Returns GpuUnfitError

Example

// Catch an algorithm or layout error before choosing a CPU fallback.
const isDeviceLimit = error => error instanceof cytoscape.GpuUnfitError;
console.log(isDeviceLimit(new Error('application error'))); // false

Example graph and handle setup

All guides · Alphabetical API index · Read continuously