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
npminstall
npmrunbuild
npmrunbuild:types
Then install the local package in your application (replace the path):
Terminal window
npminstall/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.
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:
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:
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:
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.
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:
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.
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.
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.
// 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 flightcytoscape.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.
// A graph or algorithm input exceeds the GPU device's limitscytoscape.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.
ReturnsGpuUnfitError
Example
// Catch an algorithm or layout error before choosing a CPU fallback.