structuredClone()
Creates a deep copy of a value, including nested objects, dates, Maps, and Sets.
- Returns
- A deep copy of the given value.
- Changes the original
- No
Example
#const original = {
name: 'Emma',
progress: { html: 80, css: 40 },
badges: ['Start']
}
const copy = structuredClone(original)
copy.progress.html = 100
copy.badges.push('7-day streak')
console.log(original.progress.html, original.badges)
console.log(copy.progress.html, copy.badges)Definition and usage
#The structuredClone() function creates a full, deep copy of the given value. Unlike the { ...obj } syntax or Object.assign(), which copy only the first level, it also copies every nested object and array. So changing the copy doesn’t affect the original.
It supports more types than the JSON.parse(JSON.stringify(obj)) trick: it keeps dates as Date objects, and copies Map, Set, regular expressions, typed arrays, and undefined values. It also correctly handles objects that reference themselves.
It also has limits. You can’t clone functions or DOM elements (that throws a DataCloneError), and class instances lose their prototype and become plain objects with just the data.
Syntax
#structuredClone(value)
structuredClone(value, { transfer })Parameters
#value
any value
The value to copy: an object, array, date,Map,Set, and more.options
optional object
An object with atransferfield, a list of objects (e.g.ArrayBuffer) to move instead of copy.
More examples
#const course = { title: 'JS', stats: { students: 120 } }
const shallow = { ...course }
const deep = structuredClone(course)
shallow.stats.students = 200
console.log(course.stats.students)
console.log(deep.stats.students)const session = {
startedAt: new Date(Date.UTC(2026, 8, 28, 10, 30)),
answers: new Map([['q1', 'B']])
}
const viaJson = JSON.parse(JSON.stringify(session))
const cloned = structuredClone(session)
console.log(typeof viaJson.startedAt, viaJson.answers)
console.log(cloned.startedAt.getUTCHours(), cloned.answers.get('q1'))try {
structuredClone({ name: 'Quiz', start() {} })
} catch (error) {
console.log(error.name)
}Browser support
#Widely available · since 2022
Works in all modern browsers, phones included. You can use it without worry.
- Chrome
- Edge
- Firefox
- Safari
Good practices
#- Use
structuredClone()instead ofJSON.parse(JSON.stringify())to copy data with nested objects. - If an object contains methods or is a class instance, clone just the data, or write your own copying method.
- When a first-level copy is enough, the
{ ...obj }syntax is simpler and faster.
Related entries
#- Object.assign()Copies properties from one or more objects into a target object.
- Spread (...)The spread syntax spreads an array, string, or object out into individual elements: for copying, merging, and passing arguments.
- JSON.stringify()Converts a JavaScript value, such as an object or array, into a string in JSON format.
- JSON.parse()Converts a string in JSON format into a JavaScript value, such as an object or array.
- MapA collection of key-value pairs where the key can be any value and insertion order is preserved.
Spotted a mistake or missing an example? Write to us.