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
JSON.stringify(value, replacer, space)
| Col 1 | Col 2 |
|---|---|
| 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
// Create a JavaScript object
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
// Create a JavaScript array
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.
| Col 1 | Col 2 |
|---|---|
| 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("John");
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
const person = {
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
const person = {
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
const person = {
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.
| Col 1 | Col 2 |
|---|---|
| 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
const person = {
name: "John",
greet: function() {},
age: undefined
};
let text = JSON.stringify(person);
Note: The resulting JSON syntax contains only the supported values.
Example
const person = {
name: "John",
greet: NAN,
age: Infinity
};
let text = JSON.stringify(person);
Example
// JavaScript Array
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
const person = {name:"John", today:date, city:"New York"};
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:
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 person = {name:"John"};
const text = JSON.stringify(person);
const textAgain = JSON.stringify(text);
JSON.stringify() cannot convert objects that contain circular references.
Example
const person = {};
person.self = person;
JSON.stringify(person);
Note: The example above throws a TypeError.
