Skip to content

Initialisation and lifecycle

Construct, mount, inspect readiness and dispose of a core.

#Construction and readiness

The factory reads options.elements through the bulk path and runs options.layout if supplied. It returns a usable core synchronously. With a container, it also installs the renderer and pointer handler and requires WebGPU. Missing navigator.gpu is a synchronous constructor error; adapter acquisition is asynchronous and settles through cy.ready. In headless mode, there is no renderer readiness wait and no GPU requirement.

Unknown options are ignored at runtime. TypeScript catches excess option keys at compile time; runtime option validation does not try to recreate that type check. Style sheets and structured queries are stricter: their unknown keys throw because a typo there could otherwise silently alter rendering or match the whole graph.

#cytoscape(options?)

// Create a graph instance for queries, analysis, layouts and optional interactive rendering — Full entry
cytoscape<NodeData = Untyped, EdgeData = DefaultEdgeData<NodeData>>(options?: CytoscapeOptions<NoInfer<NodeData>, NoInfer<EdgeData>>): Core<NodeData, EdgeData>

// Create a graph instance for queries, analysis, layouts and optional interactive rendering — Headless entry
cytoscape<NodeData = Untyped, EdgeData = DefaultEdgeData<NodeData>>(options?: HeadlessOptions<NoInfer<NodeData>, NoInfer<EdgeData>>): Core<NodeData, EdgeData>

// Create a graph instance for queries, analysis, layouts and optional interactive rendering — Headless GPU entry
cytoscape<NodeData = Untyped, EdgeData = DefaultEdgeData<NodeData>>(options?: HeadlessOptions<NoInfer<NodeData>, NoInfer<EdgeData>>): Core<NodeData, EdgeData>

Create a graph instance for queries, analysis, layouts and optional interactive rendering. Supply container to display the graph, or omit it for headless use. Initial elements and the requested layout are applied during construction.

Rendering requires WebGPU. Construction throws when navigator.gpu is missing; cy.ready rejects if adapter acquisition fails later.

Use cytoscape/headless for CPU graph work without rendering, or cytoscape/headless-gpu for headless GPU algorithms and force layouts.

For typed application data, call cytoscape<NodeData, EdgeData>(options). Those shapes check element data, queries, mapper fields and event targets. Without type arguments, keys remain unrestricted and reads return unknown. Unknown constructor options are ignored at runtime; use TypeScript's CytoscapeOptions to catch misspelled names.

Parameters
NameDescription
options: CytoscapeOptions<NoInfer<NodeData>, NoInfer<EdgeData>>?Default: {}

the instance options; every field is optional, and an omitted container is what selects headless mode

Fields of options
NameDescription
container: HTMLElement | null?

Where to render. When given, WebGPU is required: the factory throws synchronously if navigator.gpu is missing. When omitted, the instance is headless (works in Node, never throws for missing GPU).

elements: ElementsInput<NodeData, EdgeData>?

the initial elements — typed by the instance's shapes

style: Stylesheet<NodeData, EdgeData>?

the stylesheet — its field references typed likewise

layout: LayoutOptions?
zoom: number?
pan: Position?
minZoom: number?
maxZoom: number?
autolock: boolean?

disable node dragging globally (default false)

autoungrabify: boolean?

make all nodes ungrabbable globally (default false)

autounselectify: boolean?

disable selection globally (default false)

panningEnabled: boolean?

allow panning at all — programmatic and user (default true)

userPanningEnabled: boolean?

allow user (pointer) panning (default true)

zoomingEnabled: boolean?

allow zooming at all — programmatic and user (default true)

userZoomingEnabled: boolean?

allow user (wheel/pinch) zooming (default true)

boxSelectionEnabled: boolean?

allow box selection (default true)

boxSelectionIncludesLabels: boolean?

box selection considers label boxes too (default false). Its sense follows boxSelectionMode: it narrows a 'contain' selection and widens an 'overlap' one.

boxSelectionMode: BoxSelectionMode?

what the box-selection gesture counts as selected: 'contain' (default) takes only elements wholly inside the band; 'overlap' takes anything the band touches.

selectionType: 'single' | 'additive'?

'single' (tap/box replaces the selection) or 'additive' (taps toggle, boxes add); default 'single'

multiClickDebounceTime: number?

the dbltap/onetap debounce window in ms (default 250)

wheelSensitivity: number?

wheel-zoom rate multiplier (default 1; custom values warn once — a sensitivity tuned to one mouse/OS zooms unnaturally on others).

wheelBehavior: WheelBehavior?

what a wheel does: 'zoom' (default), 'pan' (ctrl/meta — the pinch — still zooms) or 'modifier-zoom' (only a ctrl/meta wheel zooms; a plain wheel scrolls the page).

desktopTapThreshold: number?

css px a mouse/pen press may move and still count as a tap (default 4).

touchTapThreshold: number?

css px a touch press may move and still count as a tap (default 8).

tapholdDuration: number?

unmoved-press duration before 'taphold' fires, in ms (default 500).

pointerCursors: boolean | Partial<CursorMap>?

whether the canvas writes CSS cursors for the gesture affordances — grab/grabbing around dragging, pointer over an element, crosshair while boxing (default true).

false means the interaction layer never touches style.cursor, for an app that sets its own; an object overrides individual entries ({ pan: 'move' }), where '' means inherit.

headlessWidth: number?

rendered dimensions used when headless

headlessHeight: number?
pixelRatio: number | 'auto'?

device pixel ratio override; defaults to the window's

renderer: RendererOptions?
Returns Core<NodeData, EdgeData>

the new core, usable synchronously — reads and writes do not wait on the device, and a rendered instance additionally resolves cy.ready

Example

const graph = cytoscape({ headless: true, elements: [{ data: { id: 'start' } }] });
console.log(graph.nodes().length); // 1
graph.destroy();

Example graph and handle setup

Throws

when container is given and navigator.gpu is missing

Create a graph for queries, CPU algorithms and layouts without rendering. Use this entry on a server or whenever your application does not need a canvas. Worker execution is available where the environment supports it.

Initial elements and the requested layout are applied during construction. Use cytoscape<NodeData, EdgeData>(options) to check application data shapes with TypeScript. Unknown constructor options are ignored at runtime.

Parameters
NameDescription
options: HeadlessOptions<NoInfer<NodeData>, NoInfer<EdgeData>>?Default: {}

the instance options, without the renderer- and pointer-only fields (HeadlessOptions)

Fields of options
NameDescription
zoom: number?
pan: Position?
elements: ElementsInput<NodeData, EdgeData>?

the initial elements — typed by the instance's shapes

style: Stylesheet<NodeData, EdgeData>?

the stylesheet — its field references typed likewise

layout: LayoutOptions?
minZoom: number?
maxZoom: number?
autolock: boolean?

disable node dragging globally (default false)

autoungrabify: boolean?

make all nodes ungrabbable globally (default false)

autounselectify: boolean?

disable selection globally (default false)

panningEnabled: boolean?

allow panning at all — programmatic and user (default true)

zoomingEnabled: boolean?

allow zooming at all — programmatic and user (default true)

selectionType: 'single' | 'additive'?

'single' (tap/box replaces the selection) or 'additive' (taps toggle, boxes add); default 'single'

headlessWidth: number?

rendered dimensions used when headless

headlessHeight: number?
Returns Core<NodeData, EdgeData>

the new core

Throws

when a container is given — this build has no renderer

Create a headless graph that can also run GPU algorithms and GPU force layouts. This entry includes the CPU graph features of cytoscape/headless, but no canvas, pointer gestures or image export.

Initial elements and the requested layout are applied during construction. An explicit GPU executor requires a usable WebGPU adapter. Use cytoscape<NodeData, EdgeData>(options) to check application data shapes with TypeScript. Unknown constructor options are ignored at runtime.

Parameters
NameDescription
options: HeadlessOptions<NoInfer<NodeData>, NoInfer<EdgeData>>?Default: {}

the instance options, without the renderer- and pointer-only fields (HeadlessOptions)

Fields of options
NameDescription
zoom: number?
pan: Position?
elements: ElementsInput<NodeData, EdgeData>?

the initial elements — typed by the instance's shapes

style: Stylesheet<NodeData, EdgeData>?

the stylesheet — its field references typed likewise

layout: LayoutOptions?
minZoom: number?
maxZoom: number?
autolock: boolean?

disable node dragging globally (default false)

autoungrabify: boolean?

make all nodes ungrabbable globally (default false)

autounselectify: boolean?

disable selection globally (default false)

panningEnabled: boolean?

allow panning at all — programmatic and user (default true)

zoomingEnabled: boolean?

allow zooming at all — programmatic and user (default true)

selectionType: 'single' | 'additive'?

'single' (tap/box replaces the selection) or 'additive' (taps toggle, boxes add); default 'single'

headlessWidth: number?

rendered dimensions used when headless

headlessHeight: number?
Returns Core<NodeData, EdgeData>

the new core

Throws

when a container is given — this build has no renderer

#cy.ready

// Resolves once the render pipeline is usable (immediately when headless) — and, under an initial cy.load(), once its first chunk is drawn (headless, once it is in the model)
cy.ready: Promise<Core<NodeData, EdgeData>>

Resolves once the render pipeline is usable (immediately when headless) — and, under an initial cy.load(), once its first chunk is drawn (headless, once it is in the model). Rejects when no adapter can be had.

Returns Promise<Core<NodeData, EdgeData>>

Example

await cy.ready;
console.log(cy.isReady()); // true

Example graph and handle setup

#cy.isReady()

// Whether the render pipeline is usable yet
cy.isReady(): boolean

Whether the render pipeline is usable yet. Always true on a headless instance; on a rendered one this flips when cy.ready resolves.

Returns boolean

true once rendering can proceed

Example

console.log(cy.isReady()); // true

Example graph and handle setup

#cy.unmount()

// Detach the renderer: the instance becomes headless (the model is CPU-canonical, so nothing is lost)
cy.unmount(): this

Detach the renderer: the instance becomes headless (the model is CPU-canonical, so nothing is lost). No-op when already headless.

Returns this

Example

// Detach a rendered core without removing its graph data.
cy.unmount();
console.log(cy.nodes().length); // 3

Example graph and handle setup

#cy.mount(container)

// (Re)attach a renderer to a container
cy.mount(container: HTMLElement): this

(Re)attach a renderer to a container. Re-mounting to a different container unmounts first; the fresh renderer re-uploads every column from the CPU-canonical model and rebuilds all glyph runs.

Parameters
NameDescription
container: HTMLElement

the element to render into

Returns this

this

Example

// container is an existing, sized HTML element.
cy.mount(document.getElementById('graph'));
await cy.ready;

Example graph and handle setup

Throws

if no container is given, if the instance was built directly rather than through the cytoscape factory (there is no renderer to attach), if it was built by cytoscape/headless or cytoscape/headless-gpu (a build with no renderer), or if WebGPU is unavailable — mounting is the one way a headless instance can demand a GPU after construction

#cy.container()

// The DOM element this instance renders into, or null when headless or unmounted
cy.container(): HTMLElement | null

The DOM element this instance renders into, or null when headless or unmounted.

Returns HTMLElement | null

the container element, or null

Example

console.log(cy.container()); // null

Example graph and handle setup

#cy.destroy()

// Tear the instance down: emit destroy, drop every listener, and release the pointer handler and the renderer (with its GPU resources)
cy.destroy(): this

Tear the instance down: emit a destroy event, drop every listener, and release the pointer handler and the renderer (with its GPU resources). Idempotent. The store is left intact but the instance must not be used afterwards.

Returns this

this core

Example

cy.destroy();
console.log(cy.destroyed()); // true

Example graph and handle setup

#cy.destroyed()

// Whether destroy() has run
cy.destroyed(): boolean

Whether destroy() has run.

Returns boolean

true once destroyed

Example

console.log(cy.destroyed()); // false
cy.destroy();
console.log(cy.destroyed()); // true

Example graph and handle setup

All guides · Alphabetical API index · Read continuously