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
JSON.stringify(value, replacer, space)
| 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.
// 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);
Try it Yourself »
Converting an Array
Example
Converting a JavaScript Object into JSON text.
// Create a JavaScript array
const cars = ["Ford", "Volvo", "BMW"];
// Convert the array to a JSON text
const text = JSON.stringify(cars);
Try it Yourself »
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("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);
Try it Yourself »
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"]);
Try it Yourself »
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;
});
Try it Yourself »
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);
Try it Yourself »
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.
const person = {
name: "John",
greet: function() {},
age: undefined
};
let text = JSON.stringify(person);
Try it Yourself »
Note
The resulting JSON syntax contains only the supported values.
Example
NaN and Infinity is converted to null in objects.
const person = {
name: "John",
greet: NAN,
age: Infinity
};
let text = JSON.stringify(person);
Try it Yourself »
Example
Function, undefined, NaN, and Infinity are converted to null in arrays.
// JavaScript Array
const cars = ["Ford", "Volvo", function() {}, undefined, NaN, Infinity];
// Convert the array to JSON
let text = JSON.stringify(cars);
Try it Yourself »
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);
Try it Yourself »
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
// 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);
Try it Yourself »
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);
Try it Yourself »
JSON.stringify() cannot convert objects that contain circular references.
Example
const person = {};
person.self = person;
JSON.stringify(person);
The example above throws a TypeError.
