JSON.stringify() is a built-in JavaScript function that converts a JavaScript object or value into a JSON string. It's widely used for serialization in JavaScript, especially when you need to send data over HTTP (like in API requests) or store it in local storage.
Syntax of JSON.stringify():
javascript
JSON.stringify(value[, replacer[, space]])
value: The JavaScript object or value that you want to convert to a JSON string.
replacer (optional): A function or an array that can be used to selectively include or exclude properties during serialization.
space (optional): A string or number used to add indentation (for better readability of the output JSON).
Basic Example:
javascript
const person = {
name: "Alice",
age: 30,
city: "New York"
};
// Serialize the person object into a JSON string
const jsonString = JSON.stringify(person);
console.log(jsonString);
// Output: {"name":"Alice","age":30,"city":"New York"}
In this example:
JSON.stringify(person) converts the person object into a JSON string.
The resulting JSON string is {"name":"Alice","age":30,"city":"New York"}.
Example with replacer:
The replacer parameter allows you to modify the process of stringifying an object. It can be a function or an array:
1. Using a Function as a Replacer:
The function will be called for each key-value pair in the object, allowing you to customize the resulting JSON string.
javascript
const person = {
name: "Alice",
age: 30,
city: "New York"
};
// Use a replacer function to exclude the 'age' property
const jsonString = JSON.stringify(person, (key, value) => {
if (key === "age") {
return undefined; // Don't include the 'age' key in the JSON
}
return value;
});
console.log(jsonString);
// Output: {"name":"Alice","city":"New York"}
In this example:
The replacer function excludes the age property from the final JSON string.
The resulting string is {"name":"Alice","city":"New York"}.
2. Using an Array as a Replacer:
If you pass an array as the second argument, only the properties listed in the array will be included in the resulting JSON string.
javascript
const person = {
name: "Alice",
age: 30,
city: "New York"
};
// Use an array to include only specific properties
const jsonString = JSON.stringify(person, ["name", "city"]);
console.log(jsonString);
// Output: {"name":"Alice","city":"New York"}
In this example:
Only name and city are included in the JSON string, as specified in the replacer array.
Example with space:
The space parameter is used to add indentation, making the resulting JSON string more readable (for debugging, logging, or displaying).
javascript
const person = {
name: "Alice",
age: 30,
city: "New York"
};
// Add indentation for better readability
const jsonString = JSON.stringify(person, null, 2);
console.log(jsonString);
/* Output:
{
"name": "Alice",
"age": 30,
"city": "New York"
}
*/
In this example:
The third argument (2) adds two spaces of indentation to each level of the JSON structure, making it easier to read.
Example with Handling Circular References:
If an object has circular references (where a property references the object itself), JSON.stringify() will throw an error by default. You can handle this using a replacer function.
javascript
const person = {
name: "Alice"
};
person.self = person; // Circular reference
// Serialize the object, ignoring circular references
const jsonString = JSON.stringify(person, (key, value) => {
if (key === "self") {
return undefined; // Exclude the circular reference
}
return value;
});
console.log(jsonString);
// Output: {"name":"Alice"}
Here, the self property is a circular reference, but it's excluded by the replacer function, preventing an error from occurring.
Common Use Cases for JSON.stringify():
Sending Data in HTTP Requests (API Calls): When making API requests, you often need to send data in JSON format. JSON.stringify() is used to convert JavaScript objects into JSON strings that can be sent via HTTP.
javascript
const data = {
name: "Alice",
age: 30
};
fetch('https://api.example.com/user', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(data)
});
Storing Data in LocalStorage: Browsers provide a way to store data locally using localStorage. The localStorage API only accepts strings, so JSON.stringify() is used to store objects.
javascript
const user = { name: "Alice", age: 30 };
localStorage.setItem('user', JSON.stringify(user)); // Serialize before storing
Logging: For debugging purposes, you might want to log JSON data in a readable format with indentation.
javascript
const data = { name: "Alice", age: 30 };
console.log(JSON.stringify(data, null, 2)); // Pretty print JSON
Creating JSON Files: If you're generating a JSON file in a browser environment, you can serialize an object into JSON and then trigger a file download.
javascript
const jsonData = { name: "Alice", age: 30 };
const jsonString = JSON.stringify(jsonData);
const blob = new Blob([jsonString], { type: 'application/json' });
const link = document.createElement('a');
link.href = URL.createObjectURL(blob);
link.download = 'data.json';
link.click();
Summary:
JSON.stringify() converts a JavaScript object or value into a JSON string.
It is useful for transmitting data, saving to local storage, logging, and more.
The function has optional parameters, including replacer for customizing the properties to include and space for pretty-printing.
It's often used in web development to work with APIs, client-server communication, or persistent storage.