freeCodeCamp/guide/english/javascript/standard-objects/json/json-stringify/index.md

---
title: JSON Stringify
---
## JSON Stringify

<!-- The article goes here, in GitHub-flavored Markdown. Feel free to add YouTube videos, images, and CodePen/JSBin embeds  -->

The `JSON.stringify()` method converts a *JSON-safe* JavaScript value to a JSON compliant string. 

What are JSON-safe values one may ask! Let's make a list of all JSON-unsafe values and anything that isn't on the list can be considered JSON-safe.

#### JSON-unsafe values:
- `undefined`
- `function(){}`
- (ES6+) `Symbol`
- An object with circular reference(s) in it

#### Syntax

```javascript
  JSON.stringify( value [, replacer [, space]])
```
In its simplest and most used form: 

```javascript
  JSON.stringify( value )
```

#### Parameters

  `value` : The JavaScript value to be 'stringified'.
  
  `replacer` : (Optional) A function or an array which serves as a filter for properties of the value object to be included in the JSON string.
  
  `space` : (Optional) A numeric or string value to provide indentation to the JSON string. If a numeric value is provided, that many spaces (upto 10) act as indentaion at each level. If a string value is provided, that string (upto first 10 chracters) acts as indentation at each level.

#### Return type

The return type of the method is: `string`.

## Description

The JSON-safe values are converted to their corresponding JSON string form. The JSON-unsafe values on the other hand return :
- `undefined` if they are passed as values to the method 
- `null` if they are passed as an array element
- nothing if passed as properties on an object
- throws an error if its an object with circular references(s) on it.

```javascript
  //JSON-safe values
  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(new Date(2006, 0, 2, 15, 4, 5))  // '"2006-01-02T15:04:05.000Z"'
  
  //JSON-unsafe values passed as values to the method
  JSON.stringify( undefined );					// undefined
  JSON.stringify( function(){} );					// undefined

  //JSON-unsafe values passed as array elements
  JSON.stringify({ x: [10, undefined, function(){}, Symbol('')] });  // '{"x":[10,null,null,null]}' 
 
 //JSON-unsafe values passed as properties on a object
  JSON.stringify({ x: undefined, y: Object, z: Symbol('') });  // '{}'
  
  //JSON-unsafe object with circular reference on it
  var o = { },
    a = {
      b: 42,
      c: o,
      d: function(){}
    };

  // create a circular reference inside `a`
  o.e = a;

  // would throw an error on the circular reference
  // JSON.stringify( a );

```
`JSON.stringify(...)` behaves differently if an object passed to it has a `toJSON()` method defined on it. The return value from the `toJSON()` method will be serialized instead of the object itself.

This comes in exceptionally handy when an object contains any illegal JSON value. 
```javascript
   //JSON-unsafe values passed as properties on a object
   var obj = { x: undefined, y: Object, z: Symbol('') };
   
   //JSON.stringify(obj);  logs '{}'
   obj.toJSON = function(){
    return {
      x:"undefined",
      y: "Function",
      z:"Symbol"
    }
   }
   JSON.stringify(obj);  //"{"x":"undefined","y":"Function","z":"Symbol"}"
    
  //JSON-unsafe object with circular reference on it
  var o = { },
    a = {
      b: 42,
      c: o,
      d: function(){}
    };

  // create a circular reference inside `a`
  o.e = a;

  // would throw an error on the circular reference
  // JSON.stringify( a );
  
  // define a custom JSON value serialization
  a.toJSON = function() {
    // only include the `b` property for serialization
    return { b: this.b };
  };

  JSON.stringify( a ); // "{"b":42}"
```

#### The `replacer`
The `replacer`, as mentioned earlier, is a filter which indicates which properties are to be included in the JSON string. It can either be an array or a function.
When an array, the replacer contains the string representations of only those properties which are to be included in the JSON string.
```javascript
  var foo = {foundation: 'Mozilla', model: 'box', week: 45, transport: 'car', month: 7};
  JSON.stringify(foo, ['week', 'month']);    // '{"week":45,"month":7}', only keep "week" and "month" properties
```

If `replacer` is a function, it will be called once for the object itself, and then once for each property in the object, and each time is passed two arguments, *key* and *value*. To skip a *key* in the serialization, `undefined` should be returned. Otherwise, the *value* provided should be returned. If any of these *values* are objects themselves, the `replacer` function serializes them recursively as well.
```javascript
  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}'
```
If an array is passed to `JSON.stringify()` and `replacer` returns `undefined` for any of its elements, the element's value is replaced with `null`. `replacer` functions cannot remove values from an array.
```javascript
  function replacer(key, value) {
    // Filtering out properties
    if (typeof value === 'string') {
      return undefined;
    }
    return value;
  }

  var foo = ['Mozilla', 'box', 45, 'car', 7];
  JSON.stringify(foo, replacer);  // "[null,null,45,null,7]"
```

#### The `space`
The `space` parameter used for indentation makes the result of `JSON.stringify()` prettier.
```javascript
  var a = {
    b: 42,
    c: "42",
    d: [1,2,3]
  };

  JSON.stringify( a, null, 3 );
  // "{
  //    "b": 42,
  //    "c": "42",
  //    "d": [
  //       1,
  //       2,
  //       3
  //    ]
  // }"

  JSON.stringify( a, null, "-----" );
  // "{
  // -----"b": 42,
  // -----"c": "42",
  // -----"d": [
  // ----------1,
  // ----------2,
  // ----------3
  // -----]
  // }"
```
#### More Information:
<!-- Please add any articles you think might be helpful to read before writing the article -->
Refer to [MDN docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).