Suggest an edit

Improve this article

Refine the answer for “What does structuredClone() do?”. 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)

## What structuredClone() does

`structuredClone()` is a **built-in JavaScript function**
that **creates a deep clone** of any value,
including **objects, arrays, maps, sets, dates, RegExp, Blob, File, ArrayBuffer and even circular references**.

---

### Syntax:

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

- `value` is what needs to be cloned;
- it returns **a new, independent object**, fully copied.

---

## Example of basic usage

```javascript
const user = {
  name: "Tim",
  age: 25,
  skills: ["JS", "React"],
  meta: { active: true },
};

const copy = structuredClone(user);

copy.meta.active = false;
console.log(user.meta.active); // true - the original did not change
```

Here `structuredClone()` created **a new copy**, not a reference to the same object
(unlike shallow copying with `{...user}`).

---

## The main difference from JSON.parse(JSON.stringify(...))

Deep copying used to often rely on:

```javascript
const copy = JSON.parse(JSON.stringify(obj));
```

But this approach has **many limitations**:

| Data type | JSON method | structuredClone |
|---|---|---|
| `Date` | turns into a string | preserved as `Date` |
| `Map`, `Set` | lost | copied |
| `undefined` | disappears | preserved |
| `RegExp`, `Error` | lost | preserved |
| `NaN`, `Infinity` | turn into `null` | preserved |
| Circular references | error | supported |

So `structuredClone()` is **a reliable, safe deep-clone alternative** that supports every type.

---

## Example with circular references

```javascript
const obj = {};
obj.self = obj; // circular reference

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

This kind of cloning used to simply throw a `TypeError`.

---

## Cloning with transferring binary data (optional)

`structuredClone` has **a second argument** - options
that let you **transfer (instead of copy)** certain objects (for example, `ArrayBuffer`).

```javascript
const buffer = new ArrayBuffer(8);
const clone = structuredClone(buffer, { transfer: [buffer] });

console.log(buffer.byteLength); // 0 - the original was "transferred" (detached)
console.log(clone.byteLength);  // 8 - the data is now on the clone
```

This works similarly to **Transferable objects** in `postMessage`.

---

## Where it works

Supported in all modern browsers and in Node.js (starting from v17+):

```javascript
structuredClone({ test: true }); // works in Node 17+
```

---

## Summary

| Point | Description |
|---|---|
| What it does | Deeply clones a value of any type |
| Returns | A full, independent copy |
| Supports | `Date`, `Map`, `Set`, `RegExp`, `ArrayBuffer`, circular references |
| Does not support | Functions, DOM elements |
| Compatibility | Modern browsers and Node.js 17+ |
| Alternative to | A safe replacement for `JSON.parse(JSON.stringify())` |

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

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.