JavaScript JSON Stringify
The JSON.stringify() Method
The JSON.stringify() method converts a JavaScript value into JSON text.
JavaScript variables must be converted to plain text before they can be:
- Sent to a server over HTTP
- Transmitted between applications
- Stored in a text file
Note
The JSON.stringify() method returns a text string.
Syntax
| Parameter | Description |
|---|---|
| value | The JavaScript value to convert. |
| replacer | An optional function or array that selects or transforms values. |
| space | An optional number or string used to indent the JSON text. |
Converting an Object
Example
Converting a JavaScript Object into JSON text.
const person = {
name: "John",
age: 30,
city: "New York"
};
// Convert the object to a JSON text
const text = JSON.stringify(person);
Converting an Array
Example
Converting a JavaScript Object into JSON text.
const cars = ["Ford", "Volvo", "BMW"];
// Convert the array to a JSON text
const text = JSON.stringify(cars);
Converting Other Values
JSON.stringify() can convert all JavaScript values that JSON supports.
| JavaScript Value | JSON Text |
|---|---|
| String | "John" |
| Number | 42 |
| Boolean | true |
| null | null |
| Object | {"name":"John","age":30,"city":"New York"} |
| Array | ["Ford","Volvo","BMW"] |
Example
JSON.stringify(42);
JSON.stringify(false);
JSON.stringify(Boolean(0));
JSON.stringify(true);
JSON.stringify(Boolean(1));
JSON.stringify(undefined);
// These returns null
JSON.stringify(null);
JSON.stringify(NaN);
JSON.stringify(Infinity);
Selecting Properties
A replacer array can choose which properties to include.
Example
name: "John",
age: 30,
city: "New York"
};
let text = JSON.stringify(person, ["name", "city"]);
The resulting JSON contains only the selected properties.
Transforming Values
A replacer function can modify values before they are converted.
Example
name: "John",
age: 30
};
const text = JSON.stringify(person, function(key, value) {
if (key == "age") {
return value + 1;
}
return value;
});
Formatting JSON
The optional space parameter makes JSON easier to read.
Example
name: "John",
age: 30,
city: "New York"
};
let text = JSON.stringify(person, null, 1);
The value null selects NO replacer.
The value 1 indents each level with one space.
Unsupported Values
Some JavaScript values cannot be represented in JSON.
| Value | Result |
|---|---|
| BigInt | Throws a TypeError. |
| Infinity | Converted to null in objects and in arrays. |
| NaN | Converted to null in objects and in arrays. |
| undefined | Omitted from objects. Converted to null in arrays. |
| Functions | Omitted from objects. Converted to null in arrays. |
| Symbol | Omitted from objects. Converted to null in arrays. |
Example
Functions and undefined values are omitted from objects.
name: "John",
greet: function() {},
age: undefined
};
let text = JSON.stringify(person);
Note
The resulting JSON syntax contains only the supported values.
Example
NaN and Infinity is converted to null in objects.
name: "John",
greet: NAN,
age: Infinity
};
let text = JSON.stringify(person);
Example
Function, undefined, NaN, and Infinity are converted to null in arrays.
const cars = ["Ford", "Volvo", function() {}, undefined, NaN, Infinity];
// Convert the array to JSON
let text = JSON.stringify(cars);
Stringifying Dates
The JSON.stringify() function will convert Date objects into strings.
Example
let text = JSON.stringify(person);
You can convert the string back into a date object at the receiver.
Storing Data
When storing data, the data has to be a certain format, and regardless of where you choose to store it, text is always one of the legal formats.
JSON makes it possible to store JavaScript objects as text.
Example
Store data in local storage
const myObj = {name: "John", age: 31, city: "New York"};
const myJSON = JSON.stringify(myObj);
localStorage.setItem("testJSON", myJSON);
// Retrieve data:
let text = localStorage.getItem("testJSON");
let obj = JSON.parse(text);
Common Stringify Mistakes
Calling JSON.stringify() twice, adds escaped quotation marks.
Wrong
const text = JSON.stringify(person);
const textAgain = JSON.stringify(text);
JSON.stringify() cannot convert objects that contain circular references.
Example
person.self = person;
JSON.stringify(person);
The example above throws a TypeError.