JavaScriptObjectsIntermediate

structuredClone()

Creates a deep copy of many built-in types using the structured clone algorithm.

Review the syntaxStudy the examplesOpen the coding app
const copy = structuredClone(value)
Open Coding Reference

This static page keeps the syntax and examples indexed for search, while the coding app handles interactive exploration and saved references.

What it does

Overview

Creates a deep copy of many built-in types using the structured clone algorithm.

structuredClone() creates a deep copy of a given value using the HTML structured clone algorithm. Unlike shallow copies created with the spread operator or Object.assign(), this method recursively copies nested properties, ensuring no shared references exist between the source and the clone. It is significantly more robust than the JSON.stringify() hack because it natively handles circular references and preserves complex built-in types such as Map, Set, Date, RegExp, and ArrayBuffer. However, it cannot clone functions, DOM nodes, or property descriptors like getters and setters. In terms of performance, it is highly optimized as a native runtime feature, making it preferable for large data structures, though it is slower than a shallow copy. It is available in modern browsers and Node.js 17+, but IE is not supported.

Quick reference

Syntax

const copy = structuredClone(value)

Inputs

Parameters

valueany · Value to deep-clone (must be clonable).

See it in practice

Examples

1

Deep Cloning Nested Objects

const original = { user: { id: 1, settings: { theme: 'dark' } } };
const copy = structuredClone(original);

copy.user.settings.theme = 'light';

console.log(original.user.settings.theme);
console.log(copy.user.settings.theme);
Output:
"dark" "light"

Modifying a deeply nested property in the clone does not affect the original object, proving a true deep copy was performed.

2

Cloning Maps and Sets

const originalMap = new Map([['key', { a: 1 }]]);
const copyMap = structuredClone(originalMap);

copyMap.get('key').a = 99;

console.log(originalMap.get('key').a);
console.log(copyMap.get('key').a);
Output:
1 99

Unlike JSON methods, structuredClone correctly clones Map and Set objects along with their contents.

3

Handling Circular References

const node = { name: 'root' };
node.self = node;

const copy = structuredClone(node);

console.log(copy !== node);
console.log(copy.self === copy);
Output:
true true

The algorithm tracks previously visited objects, allowing it to recreate circular references in the clone without entering an infinite loop.

Debug faster

Common Errors

1

DataCloneError

Cause: Attempting to clone a value that is not serializable, such as a function or a DOM element.

Fix: Ensure the object contains only data. If functions are needed, they must be assigned manually after cloning.

const obj = { method: function() { return 1; } };
const copy = structuredClone(obj); // Throws DataCloneError
2

LogicError

Cause: Cloning a class instance results in a plain object, losing the prototype chain and methods.

Fix: Manually re-instantiate the class or use a library that supports prototype preservation.

class User { constructor(n) { this.n = n; } }
const user = new User('Dev');
const copy = structuredClone(user);
console.log(copy instanceof User); // false

Runtime support

Compatibility

Node.js, BrowserAll modern browsers (no IE)Modern JS

Source: MDN Web Docs

Common questions

Frequently Asked Questions

Creates a deep copy of many built-in types using the structured clone algorithm.

value: Value to deep-clone (must be clonable).

DataCloneError: Ensure the object contains only data. If functions are needed, they must be assigned manually after cloning. LogicError: Manually re-instantiate the class or use a library that supports prototype preservation.