Suggest an edit

Improve this article

Refine the answer for “What does the toJSON() method 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)

`toJSON()` is a **special method** that JavaScript calls **automatically**
when an object is serialized via `JSON.stringify()`.

It lets you **control** exactly **what ends up** in the JSON string.

## In short

If an object has a `toJSON()` method,
then calling `JSON.stringify(obj)`
serializes the **result of calling that method** instead of the object itself.

## Example - basic

```javascript
const user = {
  name: 'Alex',
  age: 25,
  password: 'secret',
  toJSON() {
    // choose what ends up in the JSON
    return { name: this.name, age: this.age };
  }
};

console.log(JSON.stringify(user));
// '{"name":"Alex","age":25}'
```

`password` did not end up in the JSON,
because `toJSON()` returns only `name` and `age`.

## How it works under the hood

When you call:

```javascript
JSON.stringify(obj)
```

JavaScript does the following:

1. Checks: does `obj` have a `toJSON()` method?
→ if it **does** - calls it:

```javascript
  const value = obj.toJSON();
  ```
2. Serializes the **result** of the call, not the object itself.

## Example with nested objects

`toJSON()` works recursively for all nested objects.

```javascript
const user = {
  name: 'Alex',
  stats: {
    score: 42,
    toJSON() {
      return 'Top Secret'; // replace the object with a string
    }
  }
};

console.log(JSON.stringify(user));
// '{"name":"Alex","stats":"Top Secret"}'
```

The `toJSON()` method inside `stats` was called automatically
and replaced the nested object.

## Example with classes

You can use `toJSON()` in your own classes
to serialize instances nicely:

```javascript
class User {
  constructor(name, age) {
    this.name = name;
    this.age = age;
  }

toJSON() {
    return {
      user: this.name,
      age: this.age
    };
  }
}

const alex = new User('Alex', 25);
console.log(JSON.stringify(alex));
// '{"user":"Alex","age":25}'
```

This is convenient for defining a "clean" representation of data,
for example when sending it to a server.

## Example: built-in types have toJSON() too

| Type | What `toJSON()` does | Example |
|---|---|---|
| `Date` | Returns an ISO string | `new Date().toJSON()` → `"2025-10-14T17:00:00.000Z"` |
| `Map` / `Set` | Not serialized (by default) | `JSON.stringify(new Map())` → `{}` |
| `BigInt` | Not supported | Error: *TypeError: Do not know how to serialize a BigInt* |

## Example: when toJSON() returns something other than an object

You can return **any value** - a string, a number, even `null`.

```javascript
const product = {
  name: 'T-shirt',
  price: 1500,
  toJSON() {
    return `${this.name}: ${this.price}$`;
  }
};

console.log(JSON.stringify(product));
// "\"T-shirt: 1500$\""
```

The returned string becomes the serialization result.

## Interaction with replacer

If an object has both `toJSON()` and a `replacer`,
`toJSON()` is called first,
and then the result is passed to the `replacer`.

```javascript
const obj = {
  name: 'Alex',
  toJSON() {
    return { custom: true };
  }
};

console.log(JSON.stringify(obj, (key, value) => {
  if (key === 'custom') return 'done';
  return value;
}));
// '{"custom":"done"}'
```

## SUMMARY

| What it does | Determines **what gets serialized** by `JSON.stringify()` |
|---|---|
| Where it is called | Automatically during `JSON.stringify()` |
| What it returns | Any value (object, string, number, etc.) |
| Works recursively | Yes (for nested objects) |
| Usable in classes | Yes |
| Ignored by `JSON.parse()` | Yes (only affects serialization) |

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

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.