Skip to content

API reference

eles.data — Collection > Data and scratch. Cytoscape.js signatures, parameters and return contract.

eles.data — Collection › Data and scratch

Store data on nodes and edges: read the first element or update the collection.

Preview · Collection › Data and scratch

Read in the complete API reference · All API members

#ele.data()

// Get all data
ele.data(): IfTyped<NodeData, EdgeData, Data | undefined, unknown>

Read all application data from the first element. Returns undefined for an empty collection. To read a single key, use data(key); to update elements, use data(key, value) or data(object).

The returned object is a cached snapshot. Changing it does not update the graph. Use a data setter to emit events and update data-dependent styles.

id, source, target and parent can be read through data(), but identity and topology cannot be changed with a data setter. Use move() to change an edge's endpoints or a node's parent.

Typed instances check keys and values against the data shapes supplied to cytoscape<NodeData, EdgeData>(). Narrow a mixed collection with nodes() or edges() to access fields that are specific to one group.

Returns IfTyped<NodeData, EdgeData, Data | undefined, unknown>

the first element's data — the collection's shape when typed — or undefined when the collection is empty

Example

const node = cy.getElementById('a');
node.data('score', 9);
console.log(node.data().score); // 9

Example graph and handle setup

#ele.data(key)

// Get data by key — Built-in field
ele.data(key: FirstClassKey): IfTyped<NodeData, EdgeData, string | undefined, unknown>

// Get data by key — Application field
ele.data<K extends keyof Data & string>(key: K): IfTyped<NodeData, EdgeData, Data[K] | undefined, unknown>

Read a first-class field of the first element (see the whole-object form): 'id', 'source'/'target' on an edge, 'parent' on a child node.

Parameters
NameDescription
key: FirstClassKey

the first-class field to read

Returns IfTyped<NodeData, EdgeData, string | undefined, unknown>

the id it holds, or undefined when there is none or the collection is empty

Example

console.log(cy.getElementById('a').data('id')); // 'a'

Example graph and handle setup

Read one data key of the first element (see the whole-object form).

Parameters
NameDescription
key: K

the key to read; typed, one of the collection's fields (a mixed collection's common fields — narrow it with nodes() or edges() to read the rest)

Returns IfTyped<NodeData, EdgeData, Data[K] | undefined, unknown>

the value, or undefined when the key is unset or the collection is empty

Example

console.log(cy.getElementById('a').data('score')); // 1

Example graph and handle setup

#eles.data(key, value)

// Set data by key
eles.data<K extends keyof Data & string>(key: K, value: IfTyped<NodeData, EdgeData, Data[K], unknown>): this

Write one data key on every element. Writes emit a data event and update data-dependent styles and labels.

Parameters
NameDescription
key: K

the key to write

value: IfTyped<NodeData, EdgeData, Data[K], unknown>

the value; an explicit undefined clears the key

Returns this

this collection, for chaining

Example

const result = eles.data('score', 9);
console.log(result === eles); // true

Example graph and handle setup

Throws

when key is 'id', or 'source'/'target' on an edge — first-class fields are immutable (typed, not a key it accepts)

#eles.data(patch)

// Set several data fields
eles.data(patch: IfTyped<NodeData, EdgeData, Partial<Data>, Record<string, unknown>>): this

Set several application data fields on every element in this collection. Each supplied key replaces its value; other keys are unchanged. Writes emit a data event and update data-dependent styles and labels.

Parameters
NameDescription
patch: IfTyped<NodeData, EdgeData, Partial<Data>, Record<string, unknown>>

the keys to write

Returns this

this collection, for chaining

Example

eles.data({ score: 9 });
console.log(eles.first().data('score')); // 9

Example graph and handle setup

Throws

when the patch names 'id', or 'source'/'target' on an edge — first-class fields are immutable

Also spelled eles.attr.