Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท Global Functions and Values

The structuredClone() function

Reference for structuredClone(): deep-copying objects, arrays, Maps, Sets and Dates, circular references, what cannot be cloned, and the transfer option.

structuredClone() makes a deep copy of a value. Nested objects and arrays are copied recursively, so changing the copy never affects the original. Unlike the old JSON.parse(JSON.stringify(x)) trick, it keeps Date, Map, Set, RegExp, typed arrays, BigInt and undefined values, and it handles circular references.

It cannot copy everything: functions and DOM nodes throw an error, and class instances lose their prototype.

JavaScript
const copy = structuredClone({ tags: ["a", "b"], when: new Date(0) });

Try it

JS A real deep copy

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Circular references and limits

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
structuredClone(value)
structuredClone(value, options)
Name Description
value The value to clone.
options Optional object. Its transfer property is an array of transferable objects (such as ArrayBuffer) that are moved to the copy instead of being duplicated.

Return value: a deep copy of value.

Exceptions: a DataCloneError (DOMException) if the value contains something that cannot be cloned, such as a function, a Symbol value, or a DOM node.

Usage notes

  • Supported: primitives, plain objects, arrays, Date, RegExp, Map, Set, ArrayBuffer, typed arrays, BigInt, Error objects (with limits), and wrapper objects like new Number(1).
  • Not supported: functions (including methods), DOM nodes, Symbol values and WeakMap/WeakSet. A property whose value is a function makes the whole call throw.
  • Prototypes are lost. A cloned class instance becomes a plain object: data properties remain, methods and the class identity do not. Getters are read and their values copied as plain data.
  • Own enumerable properties only. Non-enumerable properties, property descriptors and symbol-keyed properties are not copied.
  • Shared references stay shared inside the copy: if two properties pointed to one object, they point to one cloned object.
  • Transfer moves ownership: after structuredClone(buffer, { transfer: [buffer] }) the original buffer is detached with length 0.
  • Cost: deep copies of large structures take time and memory. If only one branch changes, copy that branch instead (spread syntax or immutable updates).
  • Shallow copies are made with spread ({ ...obj }) or Array.from(); see the copying lesson.

Browser support

Supported in current browsers, Node.js, Deno and Bun. Very old browsers lack it, so check a compatibility table if you support them.