HTML: The Living Standard

Edition for Web Developers — Last Updated 21 November 2024

1. 1. 2.6 Safe passing of structured data
      1. 2.6.1 Serializable objects
      2. 2.6.2 Transferable objects
      3. 2.6.3 Structured cloning API

2.6 Safe passing of structured data

To support passing JavaScript objects, including platform objects, across realm boundaries, this specification defines infrastructure for serializing and deserializing objects, including in some cases transferring the underlying data instead of copying it. Collectively this serialization/deserialization process is known as "structured cloning", although most APIs perform separate serialization and deserialization steps. (With the notable exception being the structuredClone() method.)

2.6.1 Serializable objects

Serializable objects support being serialized, and later deserialized, in a way that is independent of any given realm. This allows them to be stored on disk and later restored, or cloned across agent and even agent cluster boundaries.

Not all objects are serializable objects, and not all aspects of objects that are serializable objects are necessarily preserved when they are serialized.

2.6.2 Transferable objects

Transferable objects support being transferred across agents. Transferring is effectively recreating the object while sharing a reference to the underlying data and then detaching the object being transferred. This is useful to transfer ownership of expensive resources. Not all objects are transferable objects and not all aspects of objects that are transferable objects are necessarily preserved when transferred.

Transferring is an irreversible and non-idempotent operation. Once an object has been transferred, it cannot be transferred, or indeed used, again.

2.6.3 Structured cloning API

result = self.structuredClone(value[, { transfer }])

✔MDN

structuredClone

Support in all current engines.

Firefox94+Safari15.4+Chrome98+

---

Opera?Edge98+

---

Edge (Legacy)?Internet ExplorerNo

---

Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?

Takes the input value and returns a deep copy by performing the structured clone algorithm. Transferable objects listed in the transfer array are transferred, not just cloned, meaning that they are no longer usable in the input value.

Throws a "DataCloneError" DOMException if any part of the input value is not serializable.