Skip to content

cytoscape(options?)

cytoscape — Core > Initialisation and lifecycle. Cytoscape.js signatures, parameters and return contract.

cytoscape — Core › Initialisation and lifecycle

Preview · Core › Initialisation and lifecycle

Read in the complete API reference · All API members

// 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