mozilla
Your Search Results

    JSON.stringify()

    Summary

    The JSON.stringify() method converts a JavaScript 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.
    replacer Optional
    If a function, transforms values and properties encountered while stringifying; if an array, specifies the set of properties included in objects in the final string.
    A detailed description of the replacer function is provided in the JavaScript guide article Using native JSON.
    space Optional
    Causes the resulting string to be pretty-printed.

    Description

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

    • Properties of non-array objects are not guaranteed to be stringified in any particular order. Do not rely on ordering of properties within the same object within the stringification.
    • 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).
    • All symbol-keyed properties will be completely ignored, even when using the replacer function.
    JSON.stringify({});                  // '{}'
    JSON.stringify(true);                // 'true'
    JSON.stringify('foo');               // '"foo"'
    JSON.stringify([1, 'false', false]); // '[1,"false",false]'
    JSON.stringify({ x: 5 });            // '{"x":5}'
    
    JSON.stringify({ x: 5, y: 6 });
    // '{"x":5,"y":6}' or '{"y":6,"x":5}'
    JSON.stringify([new Number(1), new String('false'), new Boolean(false)]);
    // '[1,"false",false]'
    
    // 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';
      }
    });
    // '{}'
    

    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 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. For example:

    var obj = {
      foo: 'foo',
      toJSON: function() {
        return 'bar';
      }
    };
    JSON.stringify(obj);        // '"bar"'
    JSON.stringify({ x: obj }); // '{"x":"bar"}'
    

    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():

    Functions are not a valid JSON data type so they will not work. Also some objects like Date will be a string after JSON.parse().

    // 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);
    

    Example of using replacer parameter

    var foo = { foundation: 'Mozilla', model: 'box', week: 45, transport: 'car', month: 7 };
    
    JSON.stringify(foo, function(key, value) {
      if (typeof value === 'string') {
        return undefined; // remove all properties whose value is a string.
      }
      return value;
    });  // '{"week":45,"month":7}'
    
    JSON.stringify(foo, ['week', 'month']);  
    // '{"week":45,"month":7}', only keep "week" and "month" properties
    

    Specifications

    Specification Status Comment
    ECMAScript 5.1 (ECMA-262)
    The definition of 'JSON.stringify' in that specification.
    Standard Initial definition. Implemented in JavaScript 1.7.
    ECMAScript 6 (ECMA-262)
    The definition of 'JSON.stringify' in that specification.
    Draft  

    Browser compatibility

    Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
    Basic support (Yes) 3.5 (1.9.1) 8.0 10.5 4.0
    Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
    Basic support (Yes) (Yes) 1.0 (1.0) (Yes) (Yes) (Yes)

    Based on Kangax's compat table.

    See also

    Document Tags and Contributors

    Last updated by: Mingun,