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.
const copy = structuredClone({ tags: ["a", "b"], when: new Date(0) });
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
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,Errorobjects (with limits), and wrapper objects likenew Number(1). - Not supported: functions (including methods), DOM nodes,
Symbolvalues andWeakMap/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 length0. - 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 }) orArray.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.