JSON.stringify() Explained: A Complete Guide

Mar 1, 20265 min read

JSON.stringify() is one of the most used functions in JavaScript, yet most developers only know its simplest form. Understanding all three parameters unlocks powerful capabilities: filtering sensitive fields, type transformation, controlled indentation, and custom serialisation. Use our JSON Stringify tool to interactively test any of these patterns.

The Three Parameters

Signature
JSON.stringify(value, replacer, space)

Parameter	Type	Purpose
value	any	The value to serialise
replacer	Function \| Array \| null	Filter or transform keys/values
space	number \| string	Indent by N spaces or a custom string

The space Parameter

JavaScript
const user = { id: 1, name: 'Alice', roles: ['admin'] };

JSON.stringify(user, null, 2);   // 2-space indent
JSON.stringify(user, null, 4);   // 4-space indent
JSON.stringify(user, null, '\t'); // tab indent

// Compact (default)
JSON.stringify(user);            // {"id":1,"name":"Alice","roles":["admin"]}

The replacer Parameter

The replacer lets you control exactly which properties are serialised and what values they carry.

Array replacer — allowlist

JavaScript
const user = { id: 1, name: 'Alice', password: 'secret', token: 'abc123' };

// Only include 'id' and 'name' — strips sensitive fields
JSON.stringify(user, ['id', 'name'], 2);
// { "id": 1, "name": "Alice" }

Function replacer — transform

JavaScript
const data = { price: 9.99, qty: 3, secret: 'hidden' };

const result = JSON.stringify(data, (key, value) => {
  if (key === 'secret') return undefined;  // omit key
  if (typeof value === 'number') return value * 100; // transform numbers to cents
  return value;
}, 2);
// { "price": 999, "qty": 300 }

Custom toJSON() Method

If an object has a toJSON() method, JSON.stringify() calls it and serialises the returned value instead of the object itself. This is useful for Date objects and custom classes:

JavaScript
class Money {
  constructor(amount, currency) {
    this.amount = amount;
    this.currency = currency;
  }
  toJSON() {
    return `${this.amount} ${this.currency}`;
  }
}

JSON.stringify({ price: new Money(9.99, 'USD') });
// {"price":"9.99 USD"}

Handling Circular References

JSON.stringify() throws a TypeError if the object contains a circular reference (object A references object B which references object A). Use a safe-stringify library or a custom replacer:

JavaScript
function safeStringify(obj) {
  const seen = new WeakSet();
  return JSON.stringify(obj, (key, value) => {
    if (typeof value === 'object' && value !== null) {
      if (seen.has(value)) return '[Circular]';
      seen.add(value);
    }
    return value;
  }, 2);
}

Values That Get Dropped

Not everything survives stringification. These types are silently omitted or converted:

undefined — object properties are omitted; in arrays, becomes null
Function — always omitted
Symbol — always omitted
NaN and Infinity — become null
Date — converted to an ISO string via toJSON()

Test Stringify Output Interactively

Use our JSON Stringify tool to paste any value and see the exact stringified output, including how replacer and space options affect the result.

Stringify JSON Interactively

Paste any value, pick your indent level, and copy the stringified result directly into your code.

JSON Stringify Tool JSON Minifier JSON Pretty Print