JSON.stringify

The JSON.stringify() method converts a JavaScript object or value to a JSON string, optionally replacing values if a replacer function is specified or optionally including only the specified properties if a replacer array is specified.

Syntax

JSON.stringify(value[, replacer[, space]])

Parameters

value

The value to convert to a JSON string.

replacerOptional

A function that alters the behavior of the stringification process, or an array of String and Number objects that serve as a whitelist for selecting/filtering the properties of the value object to be included in the JSON string. If this value is null or not provided, all properties of the object are included in the resulting JSON string.

spaceOptional

A String or Number object that's used to insert white space into the output JSON string for readability purposes.

If this is a Number, it indicates the number of space characters to use as white space; this number is capped at 10 (if it is greater, the value is just 10). 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 used as white space. If this parameter is not provided (or is null), no white space is used.

Return value

A JSON string representing the given value.

Exceptions

Throws a TypeError ("cyclic object value") exception when a circular reference is found.

Description

JSON.stringify() converts a value to JSON notation representing it:

• If the value has a toJSON() method, it's responsible to define what data will be serialized.
• Boolean, Number, and String objects are converted to the corresponding primitive values during stringification, in accord with the traditional conversion semantics.
• If undefined, a Function, or a Symbol is encountered during conversion it is either omitted (when it is found in an object) or censored to null (when it is found in an array). JSON.stringify() can also just return undefined when passing in "pure" values like JSON.stringify(function(){}) or JSON.stringify(undefined).
• All Symbol-keyed properties will be completely ignored, even when using the replacer function.
• The instances of Date implement the toJSON() function by returning a string (the same as date.toISOString()). Thus, they are treated as strings.
• The numbers Infinity and NaN, as well as the value null, are all considered null.
• All the other Object instances (including Map, Set, WeakMap, and WeakSet) will have only their enumerable properties serialized.

JSON.stringify({});                    // '{}'
JSON.stringify(true);                  // 'true'
JSON.stringify('foo');                 // '"foo"'
JSON.stringify([1, 'false', false]);   // '[1,"false",false]'
JSON.stringify([NaN, null, Infinity]); // '[null,null,null]'
JSON.stringify({ x: 5 });              // '{"x":5}'

JSON.stringify(new Date(2006, 0, 2, 15, 4, 5)) 
// '"2006-01-02T15:04:05.000Z"'

JSON.stringify({ x: 5, y: 6 });
// '{"x":5,"y":6}'
JSON.stringify([new Number(3), new String('false'), new Boolean(false)]);
// '[3,"false",false]'

// String-keyed array elements are not enumerable and make no sense in JSON
let a = ['foo', 'bar'];
a['baz'] = 'quux';      // a: [ 0: 'foo', 1: 'bar', baz: 'quux' ]
JSON.stringify(a); 
// '["foo","bar"]'

JSON.stringify({ x: [10, undefined, function(){}, Symbol('')] }); 
// '{"x":[10,null,null,null]}' 

// Standard data structures
JSON.stringify([new Set([1]), new Map([[1, 2]]), new WeakSet([{a: 1}]), new WeakMap([[{a: 1}, 2]])]);
// '[{},{},{},{}]'

// TypedArray
JSON.stringify([new Int8Array([1]), new Int16Array([1]), new Int32Array([1])]);
// '[{"0":1},{"0":1},{"0":1}]'
JSON.stringify([new Uint8Array([1]), new Uint8ClampedArray([1]), new Uint16Array([1]), new Uint32Array([1])]);
// '[{"0":1},{"0":1},{"0":1},{"0":1}]'
JSON.stringify([new Float32Array([1]), new Float64Array([1])]);
// '[{"0":1},{"0":1}]'
 
// toJSON()
JSON.stringify({ x: 5, y: 6, toJSON(){ return this.x + this.y; } });
// '11'

// Symbols:
JSON.stringify({ x: undefined, y: Object, z: Symbol('') });
// '{}'
JSON.stringify({ [Symbol('foo')]: 'foo' });
// '{}'
JSON.stringify({ [Symbol.for('foo')]: 'foo' }, [Symbol.for('foo')]);
// '{}'
JSON.stringify({ [Symbol.for('foo')]: 'foo' }, function(k, v) {
  if (typeof k === 'symbol') {
    return 'a symbol';
  }
});
// undefined

// Non-enumerable properties:
JSON.stringify( Object.create(null, { x: { value: 'x', enumerable: false }, y: { value: 'y', enumerable: true } }) );
// '{"y":"y"}'

The replacer parameter

The replacer parameter can be either a function or an array.

As a function, it takes two parameters: the key and the value being stringified. The object in which the key was found is provided as the replacer's this parameter.

Initially, the replacer function is called with an empty string as key representing the object being stringified. It is then called for each property on the object or array being stringified.

It should return the value that should be added to the JSON string, as follows:

• If you return a Number, the string corresponding to that number is used as the value for the property when added to the JSON string.
• If you return a String, that string is used as the property's value when adding it to the JSON string.
• If you return a Boolean, "true" or "false" is used as the property's value, as appropriate, when adding it to the JSON string.
• If you return null, null will be added to the JSON string.
• If you return any other object, the object is recursively stringified into the JSON string, calling the replacer function on each property, unless the object is a function, in which case nothing is added to the JSON string.
• If you return undefined, the property is not included (i.e., filtered out) in the output JSON string.

Example replacer, as a function

function replacer(key, value) {
  // Filtering out properties
  if (typeof value === 'string') {
    return undefined;
  }
  return value;
}

var foo = {foundation: 'Mozilla', model: 'box', week: 45, transport: 'car', month: 7};
JSON.stringify(foo, replacer);
// '{"week":45,"month":7}'

Example replacer, as an array

If replacer is an array, the array's values indicate the names of the properties in the object that should be included in the resulting JSON string.

JSON.stringify(foo, ['week', 'month']);  
// '{"week":45,"month":7}', only keep "week" and "month" properties

The space argument

The space argument 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 (up to 10).
• If it is a string, successive levels will be indented by this string (or the first ten characters of it).

JSON.stringify({ a: 2 }, null, ' ');
// '{
//  "a": 2
// }'

Using a tab character mimics standard pretty-print appearance:

JSON.stringify({ uno: 1, dos: 2 }, null, '\t');
// returns the string:
// '{
//     "uno": 1,
//     "dos": 2
// }'

toJSON() behavior

If an object being stringified has a property named toJSON whose value is a function, then the toJSON() method customizes JSON stringification behavior: instead of the object being serialized, the value returned by the toJSON() method when called will be serialized. JSON.stringify() calls toJSON with one parameter:

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

For example:

var obj = {
    data: 'data',
    
    toJSON(key){
        if(key)
            return `Now I am a nested object under key '${key}'`;
        
        else
            return 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'"]'

Issue with JSON.stringify() when serializing circular references

Note that since the JSON format doesn't support object references (although an IETF draft exists), a TypeError 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 by yourself, which will require finding and replacing (or removing) the cyclic references by serializable values.

Issue with plain JSON.stringify for use as JavaScript

Note that JSON is not a completely strict subset of JavaScript, with two line terminators (Line separator and Paragraph separator) which do not require escaping in JSON, but do require escaping in JavaScript.

Therefore, if the JSON is meant to be evaluated or directly utilized within JSONP, the following utility can be used:

function jsFriendlyJSONStringify (s) {
    return JSON.stringify(s).
        replace(/\u2028/g, '\\u2028').
        replace(/\u2029/g, '\\u2029');
}

var s = {
    a: String.fromCharCode(0x2028),
    b: String.fromCharCode(0x2029)
};
try {
    eval('(' + JSON.stringify(s) + ')');
} catch (e) {
    console.log(e); // "SyntaxError: unterminated string literal"
}

// No need for a catch
eval('(' + jsFriendlyJSONStringify(s) + ')');

// console.log in Firefox unescapes the Unicode if
//   logged to console, so we use alert
alert(jsFriendlyJSONStringify(s)); // {"a":"\u2028","b":"\u2029"}

var a = JSON.stringify({ foo: "bar", baz: "quux" })
//'{"foo":"bar","baz":"quux"}'
var b = JSON.stringify({ baz: "quux", foo: "bar" })
//'{"baz":"quux","foo":"bar"}'
console.log(a !== b) // true

// some memoization function use the JSON.stringify to serialize arguments,
// which may missing the cache when encountering the same object like above

Example of using JSON.stringify() with localStorage

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

// Creating an example of JSON
var 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 session
localStorage.setItem('session', JSON.stringify(session));

// Example of how to transform the String generated through 
// JSON.stringify() and saved in localStorage in JSON object again
var restoredSession = JSON.parse(localStorage.getItem('session'));

// Now restoredSession variable contains the object that was saved
// in localStorage
console.log(restoredSession);

Well-formed JSON.stringify()

Engines implementing the well-formed JSON.stringify specfication, prevent returning ill-formed Unicode strings. Previously, JSON.stringify would output lone surrogates if the input contained any lone surrogates, which is invalid UTF-8:

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

With this change, rather than return unpaired surrogate code points as single UTF-16 code units, JSON.stringify represents them with JSON escape sequences:

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

Unicode escape sequences are valid JSON and are well-formed in both UTF-16 and UTF-8.

Specifications

Browser compatibilityUpdate compatibility data on GitHub

See also

• JSON.parse()
• cycle.js – Introduces two functions: JSON.decycle and JSON.retrocycle. These allow encoding and decoding of cyclical structures and DAGs into an extended and retrocompatible JSON format.