Skip to content

Data and scratch

Read and update application data or transient scratch on elements.

#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.

#eles.removeData()

// Remove all keys
eles.removeData(): this

Remove application data keys.

Returns this

this collection, for chaining

Example

eles.data('temporary', 1);
eles.removeData();
console.log(eles.first().data('temporary')); // undefined

Example graph and handle setup

#eles.removeData(names)

// Remove the specified keys
eles.removeData(names: string): this

Remove application data keys.

Parameters
NameDescription
names: string

space-separated key names; omit to clear every key

Returns this

this collection, for chaining

Example

eles.data('temporary', 1);
eles.removeData('temporary');
console.log(eles.first().data('temporary')); // undefined

Example graph and handle setup

Also spelled eles.removeAttr.

#ele.scratch()

// Get all scratch data
ele.scratch(): Record<string, unknown> | undefined

Read all scratch data from the first element. Scratch is never exported and writes emit no events.

Returns Record<string, unknown> | undefined

the scratch object or value; undefined when empty or unset

Example

eles.scratch('ui', 1);
console.log(eles.first().scratch().ui); // 1

Example graph and handle setup

#ele.scratch(key)

// Get scratch data by key
ele.scratch(key: string): unknown

Read one scratch namespace from the first element. Scratch is never exported and writes emit no events.

Parameters
NameDescription
key: string

the namespace to read or write

Returns unknown

the scratch object or value; undefined when empty or unset

Example

eles.scratch('ui', 1);
console.log(eles.first().scratch('ui')); // 1

Example graph and handle setup

#eles.scratch(key, value)

// Set scratch data by key
eles.scratch(key: string, value: unknown): this

Write one scratch namespace on every element. Scratch is never exported and writes emit no events.

Parameters
NameDescription
key: string

the namespace to read or write

value: unknown

the transient value to store

Returns this

this collection, for chaining

Example

const result = eles.scratch('ui', 1);
console.log(result === eles); // true

Example graph and handle setup

#eles.scratch(patch)

// Set several scratch data fields
eles.scratch(patch: Record<string, unknown>): this

Merge scratch namespaces on every element. Scratch is never exported and writes emit no events.

Parameters
NameDescription
patch: Record<string, unknown>

the namespaces to merge

Returns this

this collection, for chaining

Example

eles.scratch({ ui: 1 });
console.log(eles.first().scratch('ui')); // 1

Example graph and handle setup

#eles.removeScratch()

// Remove all keys
eles.removeScratch(): this

Delete scratchpad keys from every element.

Returns this

this collection, for chaining

Example

eles.scratch('temporary', 1);
eles.removeScratch();
console.log(eles.first().scratch('temporary')); // undefined

Example graph and handle setup

#eles.removeScratch(namespace)

// Remove the specified keys
eles.removeScratch(namespace: string): this

Delete scratchpad keys from every element.

Parameters
NameDescription
namespace: string

the key to remove; omit to clear each element's whole scratchpad

Returns this

this collection, for chaining

Example

eles.scratch('temporary', 1);
eles.removeScratch('temporary');
console.log(eles.first().scratch('temporary')); // undefined

Example graph and handle setup

All guides · Alphabetical API index · Read continuously