Codectionary / Developer documentation / JavaScript

structuredClone()

structuredClone() creates a true deep copy of a value, correctly handling nested objects, arrays, Maps, Sets, dates, and even circular references - something JSON.parse(JSON.stringify(obj)) cannot do reliably. It is a built-in global function, available without any import.

Syntax

const copy = structuredClone(original);

Examples

Deep Cloning Nested Data

A genuine deep copy, unlike a shallow spread or Object.assign().

const original = {
  name: "Alice",
  address: { city: "London", zip: "SW1A" },
  tags: ["admin", "verified"]
};

const clone = structuredClone(original);
clone.address.city = "Manchester";

console.log(original.address.city); // "London" - unaffected
console.log(clone.address.city);    // "Manchester"

Handling Types JSON Cannot

structuredClone() correctly clones Dates, Maps, and Sets, unlike JSON-based approaches.

const data = {
  createdAt: new Date(),
  tags: new Set(["a", "b"]),
  scores: new Map([["math", 90]])
};

const clone = structuredClone(data);
console.log(clone.createdAt instanceof Date); // true - stays a real Date
console.log(clone.tags instanceof Set);        // true - stays a real Set

// JSON.parse(JSON.stringify(data)) would turn createdAt into a string,
// and silently lose the Set and Map entirely

Best practices

  • Use structuredClone() instead of JSON.parse(JSON.stringify(obj)) for deep copies - it is faster, handles more types, and supports circular references
  • Remember it cannot clone functions, DOM nodes, or objects with prototype chains beyond plain data (like class instances lose their class)
  • Use it for genuinely deep copies - for shallow copies, spread syntax ({...obj}) is simpler and sufficient
  • Check runtime support if targeting very old browsers, though it is now broadly available in all modern environments

Runtime & versions

Browsers and JavaScript runtimes. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

ECMAScript specification

Specifications & further reading