Skip to content

Data and scratch

Keep serializable graph data separate from transient application scratch.

#Core data, viewport and events

cy.data() holds graph-level application data; cy.scratch() is transient application metadata. Graph data can be serialized, while scratch is not.

#cy.data()

// Get all data
cy.data(): Record<string, unknown>

Read all graph-level data. Graph data is separate from element data. Binary serialization includes it; constructor loading restores it, while cy.add(buffer) leaves the destination graph's data unchanged.

Returns Record<string, unknown>

the graph's data object

Example

cy.data('title', 'Example graph');
console.log(cy.data().title); // 'Example graph'

Example graph and handle setup

#cy.data(key)

// Get data by key
cy.data(key: string): unknown

Read one graph-level data value.

Parameters
NameDescription
key: string

the application field to read or write

Returns unknown

the value, or undefined when the key is unset

Example

cy.data('title', 'Example graph');
console.log(cy.data('title')); // 'Example graph'

Example graph and handle setup

#cy.data(key, value)

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

Write one graph-level data value. Writes emit a data event.

Parameters
NameDescription
key: string

the application field to read or write

value: unknown

the value to store

Returns this

this core, for chaining

Example

const result = cy.data('title', 'Example graph');
console.log(result === cy); // true

Example graph and handle setup

#cy.data(patch)

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

Merge several graph-level data fields. Writes emit a data event.

Parameters
NameDescription
patch: Record<string, unknown>

the fields to merge; other fields stay unchanged

Returns this

this core, for chaining

Example

cy.data({ title: 'Example graph' });
console.log(cy.data('title')); // 'Example graph'

Example graph and handle setup

Also spelled cy.attr.

#cy.removeData()

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

Delete graph-level data keys. Emits a data event when anything was removed.

Returns this

this core, for chaining

Example

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

Example graph and handle setup

#cy.removeData(names)

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

Delete graph-level data keys. Emits a data event when anything was removed.

Parameters
NameDescription
names: string

space-separated key names; omit to clear everything

Returns this

this core, for chaining

Example

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

Example graph and handle setup

Also spelled cy.removeAttr.

#cy.scratch()

// Get all scratch data
cy.scratch(): Record<string, unknown>

Read all graph-level scratch data. Namespace extension keys, for example '_myExtension'. Scratch is transient, never exported, and emits no events.

Returns Record<string, unknown>

the graph's scratch data object

Example

cy.scratch('title', 'Example graph');
console.log(cy.scratch().title); // 'Example graph'

Example graph and handle setup

#cy.scratch(key)

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

Read one graph-level scratch data value.

Parameters
NameDescription
key: string

the application field to read or write

Returns unknown

the value, or undefined when the key is unset

Example

cy.scratch('title', 'Example graph');
console.log(cy.scratch('title')); // 'Example graph'

Example graph and handle setup

#cy.scratch(key, value)

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

Write one graph-level scratch data value. Scratch writes do not emit events and are never exported.

Parameters
NameDescription
key: string

the application field to read or write

value: unknown

the value to store

Returns this

this core, for chaining

Example

const result = cy.scratch('title', 'Example graph');
console.log(result === cy); // true

Example graph and handle setup

#cy.scratch(patch)

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

Merge several graph-level scratch data fields. Scratch writes do not emit events and are never exported.

Parameters
NameDescription
patch: Record<string, unknown>

the fields to merge; other fields stay unchanged

Returns this

this core, for chaining

Example

cy.scratch({ title: 'Example graph' });
console.log(cy.scratch('title')); // 'Example graph'

Example graph and handle setup

#cy.removeScratch()

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

Delete graph-level scratch keys.

Returns this

this core, for chaining

Example

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

Example graph and handle setup

#cy.removeScratch(names)

// Remove the specified keys
cy.removeScratch(names: string): this

Delete graph-level scratch keys.

Parameters
NameDescription
names: string

space-separated key names; omit to clear everything

Returns this

this core, for chaining

Example

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

Example graph and handle setup

All guides · Alphabetical API index · Read continuously