Skip to content

cytoscape.serializeElements(elements)

cytoscape.serializeElements — Core > Export and snapshots > Graph data and wire format. Cytoscape.js signatures, parameters and return contract.

cytoscape.serializeElements — Core › Export and snapshots › Graph data and wire format

Preview · Core › Export and snapshots › Graph data and wire format

Read in the complete API reference · All API members

// Serialize elements (definition form or columnar form) into one transferable/fetchable ArrayBuffer
cytoscape.serializeElements(elements: ElementsDefinition | ElementDefinition | ColumnarElements): ArrayBuffer

Serialize elements (definition form or columnar form) into one transferable/fetchable ArrayBuffer. deserializeElements (or passing the buffer straight to options.elements/cy.add()) reverses it.

Parameters
NameDescription
elements: ElementsDefinition | ElementDefinition | ColumnarElements

the elements to serialize, in either accepted form; a definition-form payload is converted to columnar first. A columnar payload's optional graph-level data rides along; the definition form has nowhere to put it, so it carries none. Its node references (refs) ride too — convert definitions with toColumnarElements( defs, { refs: true }) first to carry cut edges

Fields of elements
NameDescription
columnar: true

discriminant so the loader can tell the forms apart

nodes: ElementDefinition<NodeData>[]?
edges: ElementDefinition<EdgeData>[]?
refs: string[] | PackedIds?

Node references (experimental with the wire format until 4.x): the ids of nodes this payload does not carry but indexes — an edge endpoint or a node parent nodes.count + i names refs[i]. Each must name a node already in the graph when the payload loads (an earlier chunk of a cy.load(), or anything cy.add() put there); one that does not throws before anything is added. Each id resolves once however many edges index it, which is what makes a chunk's cut edges as cheap as its own. The factory's options.elements loads into an empty graph, so a payload with refs cannot load there; cy.patch() refuses one. Build it from definitions with toColumnarElements( defs, { refs: true }).

data: DefinitionData<Data>?
group: GroupName?

inferred from data.source/data.target when omitted

position: Position?

nodes only

collapsed: boolean?

nodes only: persisted miniature-compound state

appliedCollapseScale: number?

nodes only: current applied factor when collapsed; omitted uses the configured collapse-scale

selected: boolean?
selectable: boolean?
grabbable: boolean?
locked: boolean?
pannable: boolean?

dragging this element pans the graph instead (default: true for edges, false for nodes)

Returns ArrayBuffer

one little-endian ArrayBuffer holding the whole payload — fixed header, columns, and ids as a UTF-8 blob with prefix offsets. Every section starts at an offset aligned to its element width (8 for f64 columns), and that alignment is the encoder's contract: deserializeElements returns views over the buffer rather than copies because of it (census measured the decode at zero copies), so a reader may rely on it and a future encoder must keep it

Example

const buffer = cytoscape.serializeElements([{ data: { id: 'new' } }]);
console.log(cy.add(buffer).length); // 1

Example graph and handle setup

Throws

if the platform is big-endian, or if a definition-form payload names an edge endpoint that is not a node in the same payload