value

The value to convert to a JSON string.

replacerOptional

A function that alters the behavior of the stringification process, or an array of strings and numbers that specifies properties ofvalue to be included in the output. Ifreplacer is an array, all elements in this array that are not strings or numbers (either primitives or wrapper objects), includingSymbol values, are completely ignored. Ifreplacer is anything other than a function or an array (e.g.,null or not provided), all string-keyed properties of the object are included in the resulting JSON string.

spaceOptional

A string or number that's used to insert white space (including indentation, line break characters, etc.) into the output JSON string for readability purposes.

If this is a number, it indicates the number of space characters to be used as indentation, clamped to 10 (that is, any number greater than10 is treated as if it were10). Values less than 1 indicate that no space should be used.

If this is a string, the string (or the first 10 characters of the string, if it's longer than that) is inserted before every nested object or array.

Ifspace is anything other than a string or number (can be either a primitive or a wrapper object) — for example, isnull or not provided — no white space is used.

A JSON string representing the given value, or undefined.

TypeError

Thrown in one of the following cases:

• value contains a circular reference.
• ABigInt value is encountered.

JSON.stringify() converts a value to the JSON notation that the value represents. Values are stringified in the following manner:

• Boolean,Number,String, andBigInt (obtainable viaObject()) objects are converted to the corresponding primitive values during stringification, in accordance with the traditional conversion semantics.Symbol objects (obtainable viaObject()) are treated as plain objects.
• Attempting to serializeBigInt values will throw. However, if the BigInt has atoJSON() method (through monkey patching:BigInt.prototype.toJSON = ...), that method can provide the serialization result. This constraint ensures that a proper serialization (and, very likely, its accompanying deserialization) behavior is always explicitly provided by the user.
• undefined,Function, andSymbol values are not valid JSON values. If any such values are encountered during conversion, they are either omitted (when found in an object) or changed tonull (when found in an array).JSON.stringify() can returnundefined when passing in "pure" values likeJSON.stringify(() => {}) orJSON.stringify(undefined).
• The numbersInfinity andNaN, as well as the valuenull, are all considerednull. (But unlike the values in the previous point, they would never be omitted.)
• Arrays are serialized as arrays (enclosed by square brackets). Only array indices between 0 andlength - 1 (inclusive) are serialized; other properties are ignored.
• The special raw JSON object created withJSON.rawJSON() is serialized as the raw JSON text it contains (by accessing itsrawJSON property).
• For other objects:

  • AllSymbol-keyed properties will be completely ignored, even when using thereplacer parameter.

  • If the value has atoJSON() method, it's responsible to define what data will be serialized. Instead of the object being serialized, the value returned by thetoJSON() method when called will be serialized.JSON.stringify() callstoJSON with one parameter, thekey, which has the same semantic as thekey parameter of thereplacer function:

    • if this object is a property value, the property name
    • if it is in an array, the index in the array, as a string
    • ifJSON.stringify() was directly called on this object, an empty string

    AllTemporal objects implement thetoJSON() method, which returns a string (the same as callingtoString()). Thus, they will be serialized as strings. Similarly,Date objects implementtoJSON(), which returns the same astoISOString().

  • Onlyenumerable own properties are visited. This meansMap,Set, etc. will become"{}". You can use thereplacer parameter to serialize them to something more useful.

    Properties are visited using the same algorithm asObject.keys(), which has a well-defined order and is stable across implementations. For example,JSON.stringify on the same object will always produce the same string, andJSON.parse(JSON.stringify(obj)) would produce an object with the same key ordering as the original (assuming the object is completely JSON-serializable).

Thereplacer parameter can be either a function or an array.

As an array, its elements indicate the names of the properties in the object that should be included in the resulting JSON string. Only string and number values are taken into account; symbol keys are ignored.

As a function, it takes two parameters: thekey and thevalue being stringified. The object in which the key was found is provided as thereplacer'sthis context.

Thereplacer function is called for the initial object being stringified as well, in which case thekey is an empty string (""). It is then called for each property on the object or array being stringified. Array indices will be provided in its string form askey. The current property value will be replaced with thereplacer's return value for stringification. This means:

• If you return a number, string, boolean, ornull, that value is directly serialized and used as the property's value. (Returning a BigInt will throw as well.)
• If you return aFunction,Symbol, orundefined, the property is not included in the output.
• If you return any other object, the object is recursively stringified, calling thereplacer function on each property.

Typically, array elements' index would never shift (even when the element is an invalid value like a function, it will becomenull instead of omitted). Using thereplacer function allows you to control the order of the array elements by returning a different array.

Thespace parameter may be used to control spacing in the final string.

• If it is a number, successive levels in the stringification will each be indented by this many space characters.
• If it is a string, successive levels will be indented by this string.

Each level of indentation will never be longer than 10. Number values ofspace are clamped to 10, and string values are truncated to 10 characters.

function replacer(key, value) {  // Filtering out properties  if (typeof value === "string") {    return undefined;  }  return value;}const foo = {  foundation: "Mozilla",  model: "box",  week: 45,  transport: "car",  month: 7,};JSON.stringify(foo, replacer);// '{"week":45,"month":7}'

If you wish thereplacer to distinguish an initial object from a key with an empty string property (since both would give the empty string as key and potentially an object as value), you will have to keep track of the iteration count (if it is beyond the first iteration, it is a genuine empty string key).

function makeReplacer() {  let isInitial = true;  return (key, value) => {    if (isInitial) {      isInitial = false;      return value;    }    if (key === "") {      // Omit all properties with name "" (except the initial object)      return undefined;    }    return value;  };}const replacer = makeReplacer();console.log(JSON.stringify({ "": 1, b: 2 }, replacer)); // "{"b":2}"

Indent the output with one space:

console.log(JSON.stringify({ a: 2 }, null, " "));/*{ "a": 2}*/

Using a tab character mimics standard pretty-print appearance:

console.log(JSON.stringify({ uno: 1, dos: 2 }, null, "\t"));/*{"uno": 1,"dos": 2}*/

DefiningtoJSON() for an object allows overriding its serialization behavior.

const obj = {  data: "data",  toJSON(key) {    return key ? `Now I am a nested object under key '${key}'` : this;  },};JSON.stringify(obj);// '{"data":"data"}'JSON.stringify({ obj });// '{"obj":"Now I am a nested object under key 'obj'"}'JSON.stringify([obj]);// '["Now I am a nested object under key '0'"]'

Since theJSON format doesn't support object references (although anIETF draft exists), aTypeError will be thrown if one attempts to encode an object with circular references.

const circularReference = {};circularReference.myself = circularReference;// Serializing circular references throws "TypeError: cyclic object value"JSON.stringify(circularReference);

To serialize circular references, you can use a library that supports them (e.g.,cycle.js by Douglas Crockford) or implement a solution yourself, which will require finding and replacing (or removing) the cyclic references by serializable values.

If you are usingJSON.stringify() to deep-copy an object, you may instead want to usestructuredClone(), which supports circular references. JavaScript engine APIs for binary serialization, such asv8.serialize(), also support circular references.

In a case where you want to store an object created by your user and allow it to be restored even after the browser has been closed, the following example is a model for the applicability ofJSON.stringify():

// Creating an example of JSONconst session = {  screens: [],  state: true,};session.screens.push({ name: "screenA", width: 450, height: 250 });session.screens.push({ name: "screenB", width: 650, height: 350 });session.screens.push({ name: "screenC", width: 750, height: 120 });session.screens.push({ name: "screenD", width: 250, height: 60 });session.screens.push({ name: "screenE", width: 390, height: 120 });session.screens.push({ name: "screenF", width: 1240, height: 650 });// Converting the JSON string with JSON.stringify()// then saving with localStorage in the name of sessionlocalStorage.setItem("session", JSON.stringify(session));// Example of how to transform the String generated through// JSON.stringify() and saved in localStorage in JSON object againconst restoredSession = JSON.parse(localStorage.getItem("session"));// Now restoredSession variable contains the object that was saved// in localStorageconsole.log(restoredSession);

Engines implementing thewell-formed JSON.stringify specification will stringify lone surrogates (any code point from U+D800 to U+DFFF) using Unicode escape sequences rather than literally (outputting lone surrogates). Before this change, such strings could not be encoded in valid UTF-8 or UTF-16:

JSON.stringify("\uD800"); // '"�"'

But with this changeJSON.stringify() represents lone surrogates using JSON escape sequences thatcan be encoded in valid UTF-8 or UTF-16:

JSON.stringify("\uD800"); // '"\\ud800"'

This change should be backwards-compatible as long as you pass the result ofJSON.stringify() to APIs such asJSON.parse() that will accept any valid JSON text, because they will treat Unicode escapes of lone surrogates as identical to the lone surrogates themselves.Only if you are directly interpreting the result ofJSON.stringify() do you need to carefully handleJSON.stringify()'s two possible encodings of these code points.

• Polyfill of modernJSON.stringify behavior (symbol, well-formed unicode, raw JSON) incore-js
• JSON.parse()
• JSON.rawJSON()