Suggest an edit

Improve this article

Refine the answer for “structuredClone”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

**`structuredClone()` is a built-in JavaScript function that makes a deep copy of any value, including complex objects, arrays, maps and even dates.** It is the most modern and safest way to clone data in JS without third-party libraries.

## Theory

### TL;DR

- `structuredClone(value)` returns a **fully independent deep copy** of the value.
- Every nested object and array is recreated, so nothing is shared with the original.
- It supports `Date`, `Map`, `Set`, `RegExp`, `ArrayBuffer`, `TypedArray`, `Blob`, `File`.
- It handles **circular references** correctly, where `JSON.parse(JSON.stringify())` throws.
- It **does not copy** functions, DOM elements, class prototypes or symbols.
- Available in modern browsers, in Node.js 17+ and in Deno.

### Quick example

```javascript
const clone = structuredClone(value);
```

The function creates a **fully independent copy** of the object, including every nested structure, and returns a new object with no shared references to the original.

```javascript
const user = {
  name: 'Alice',
  address: { city: 'Kyiv' },
  hobbies: ['sport', 'music']
};

const clone = structuredClone(user);

clone.address.city = 'Lviv';
clone.hobbies.push('coding');

console.log(user.address.city); // 'Kyiv'
console.log(user.hobbies);      // ['sport', 'music']
```

The copy is **deep**: all nested objects and arrays are created anew, and the original stays unchanged.

### What structuredClone can copy

Supported:

- objects (`{}`) and arrays (`[]`);
- nested structures of any depth;
- `Date`;
- `Map`, `Set`;
- `Blob`, `File`, `ArrayBuffer`, `TypedArray`;
- `RegExp` (the pattern and the flags are preserved);
- even **circular references**, unlike `JSON.stringify()`.

An example with `Map` and `Date`:

```javascript
const data = {
  date: new Date(),
  map: new Map([['a', 1], ['b', 2]])
};

const copy = structuredClone(data);

console.log(copy.date === data.date); // false, it is a new object
console.log(copy.map.get('a'));       // 1
```

An example with a circular reference that actually works:

```javascript
const obj = {};
obj.self = obj;

const clone = structuredClone(obj);
console.log(clone.self === clone); // true
```

`structuredClone()` copes even with self-references, where `JSON.parse(JSON.stringify())` simply throws.

### What is not copied

Not supported:

- **functions**;
- **DOM elements**;
- **classes and prototypes** (the object is cloned as a plain object and the prototype is lost);
- **Symbol**;
- anything the structured clone algorithm cannot serialise.

```javascript
const obj = {
  fn: () => {},
  el: document.body
};

structuredClone(obj);
// DataCloneError: function or DOM node cannot be cloned
```

### Comparison with other approaches

| Method | Copy type | Copies nested data | Copies functions | Copies Date / Map / Set |
| --- | --- | --- | --- | --- |
| `{ ...obj }` | shallow | no | yes | no |
| `Object.assign()` | shallow | no | yes | no |
| `JSON.parse(JSON.stringify())` | deep | yes | no | no |
| `structuredClone()` | deep | yes | no | yes |
| `_.cloneDeep()` (Lodash) | deep | yes | no | yes |

### Environment support

It works:

- in all modern browsers (Chrome 98+, Firefox 94+, Edge 98+, Safari 15.4+);
- in Node.js 17+;
- in Deno.

For older environments you can add a polyfill, for example `core-js`:

```bash
npm install core-js
```

A summary of its properties:

| Property | `structuredClone()` |
| --- | --- |
| Copy type | deep |
| Mutates the original | no |
| Copies objects, arrays, Map, Set, Date | yes |
| Works with circular references | yes |
| Copies functions and DOM elements | no |
| Built-in and safe | yes |

### Common mistakes

- **Expecting the clone to keep its class.** A class instance is cloned as a plain object: the data survives, the prototype and methods do not, so `clone instanceof User` is `false`.
- **Passing an object that carries a method or a callback.** A single function anywhere in the structure fails the whole call with `DataCloneError` instead of being skipped silently.
- **Confusing it with shallow copying.** `{ ...obj }` and `Object.assign()` clone only the top level, so nested objects stay shared.
- **Treating `JSON.parse(JSON.stringify())` as an equivalent replacement.** It loses `undefined` and functions, turns `Date` into a string, breaks `Map` and `Set`, and throws on cycles.
- **Forgetting about older environments.** In Node.js 16 and below, and in older browsers, the function simply does not exist, so you need a polyfill or a feature check.

Markdown · drag & drop images · ⌘B / ⌘I shortcuts711 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.