Skip to content

cy.load(source, options?)

cy.load — Core > Graph manipulation > Progressive loading. Cytoscape.js signatures, parameters and return contract.

cy.load — Core › Graph manipulation › Progressive loading

Preview · Core › Graph manipulation › Progressive loading

Read in the complete API reference · All API members

// Progressive ingest: load the graph chunk by chunk from an async iterable — a streamed response, a server's pages — and show a correct partial graph before the last byte arrives
cy.load(source: | AsyncIterable<ElementsInput<NodeData, EdgeData>> | Iterable<ElementsInput<NodeData, EdgeData>>, options?: LoadOptions): LoadRun

Progressive ingest: load the graph chunk by chunk from an async iterable — a streamed response, a server's pages — and show a correct partial graph before the last byte arrives. Each chunk is any input form (definition, columnar or wire); a chunk may name nodes an earlier chunk loaded — by id in the definition form, and through node references (refs) in the columnar and wire forms, which is what keeps a chunk's cut edges as cheap as its own. A plain iterable (an array of chunks) works too.

Every chunk lands through the bulk load path — one bulk style pass, no per-element handle — and the renderer gets a turn between chunks, even when the source hands them over synchronously; the second chunk is not asked for until the first is drawn. Every element drawn is correct; completeness arrives — a frame may show some of the graph, never a wrong piece of it.

An initial load — one that starts on an instance holding no elements, the streamed counterpart of options.elements — holds cy.ready until its first chunk is drawn (headless: until it is in the model), fits the viewport once to that chunk and then holds it (never a re-fit per chunk; fit: false keeps the viewport as it is), and applies the graph-level data() a wire chunk carries. The load re-points cy.ready, so read it after calling load() — a reference taken before resolves on the renderer alone. A load into a populated graph is a streamed cy.add(): cy.ready, the viewport and data() are left alone. Positions are the payload's (the preset layout case); a layout cannot start while a load runs — run it once the promise resolves.

Events: loadstart; loadchunk after each chunk (with add per element while anyone listens for it, as the bulk path emits them); loadready once the first chunk is drawn; loadstop when the load ends — completed, failed or cancelled (event.cancelled). Each carries event.progress: { chunks, nodes, edges } so far.

Completion is the returned promise, resolving with the final progress; it carries cancel() (contract): cancelling stops pulling chunks, closes the source's iterator, keeps what has landed, and rejects with a CancelledError. cy.destroy() cancels a running load. A chunk that fails to ingest rejects the load; the chunks before it stay, and a node reference that names no node fails its chunk before anything of it is added.

Parameters
NameDescription
source: | AsyncIterable<ElementsInput<NodeData, EdgeData>> | Iterable<ElementsInput<NodeData, EdgeData>>

an async iterable (or iterable) of chunks, each a definition, columnar or wire payload

options: LoadOptions?

{ fit, padding }: fit once to the first chunk (default: on for an initial load), and that fit's padding

Fields of options
NameDescription
fit: boolean?

Fit the viewport once, to the first chunk, and then hold it — a load never re-fits per chunk, so the screen does not jump as the graph fills in. Default: true for an initial load (one that starts on an instance holding no elements), false for a load into a populated graph.

padding: number?

the rendered-space padding of that fit, in px (default 0, as cy.fit())

Returns LoadRun

the load's completion: a promise of the final { chunks, nodes, edges }, with cancel()

Example

await cy.load([[{ data: { id: 'd' } }]]);
console.log(cy.hasElementWithId('d')); // true

Example graph and handle setup

Throws

synchronously, when source is not an (async) iterable of chunks (a single payload is refused — pass [ payload ]), on an unknown option, while another load is running on this instance, or on a destroyed instance