---
hide_title: false
hide_table_of_contents: false
pagination_next: null
pagination_prev: null
---
# JSON.stringify()

The **`JSON.stringify()`** method converts a JavaScript value to a JSON string, optionally replacing values if a replacer function is specified or optionally including only the specified properties if a replacer array is specified.

## Syntax

```js
JSON.stringify(value)
JSON.stringify(value, replacer)
JSON.stringify(value, replacer, space)
```

### Parameters

- `value`
  - : The value to convert to a JSON string.
- `replacer` _**optional**_
  - : A function that alters the behavior of the stringification process, or an array of strings or numbers naming properties of `value` that should be included in the output. If `replacer` is an array, all elements that are not strings or numbers (can be either primitives or wrapper objects), including `Symbol` values, are completely ignored. If `replacer` is anything other than a function or an array (e.g. [`null`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/null) or not provided), all properties of the object are included in the resulting JSON string.
- `space` _**optional**_

  - : A string or number that's used to insert white space (including indentation, line break characters, etc.) into the output JSON string for readability purposes.

    If this is a number, it indicates the number of space characters to be used as indentation, clamped to 10 (that is, any number greater than `10` is treated as if it were `10`). Values less than 1 indicate that no space should be used.

    If this is a string, the string (or the first 10 characters of the string, if it's longer than that) is inserted before every nested object or array.

    If `space` is anything other than a string or number (can be either a primitive or a wrapper object) — for example, is [`null`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/null) or not provided — no white space is used.

### Return value

A JSON string representing the given value, or undefined.

### Exceptions

- [`TypeError`](../../globals/TypeError/TypeError.mdx)
  - : Thrown if one of the following is true:
    - `value` contains a circular reference.
    - A `BigInt` value is encountered.

## Description

`JSON.stringify()` converts a value to JSON notation representing it:

- `Boolean`, `Number`, `String`, and `BigInt` (obtainable via [`Object()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/Object)) objects are converted to the corresponding primitive values during stringification, in accordance with the traditional conversion semantics. `Symbol` objects (obtainable via [`Object()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/Object)) are treated as plain objects.
- Attempting to serialize `BigInt` values will throw. However, if the BigInt has a `toJSON()` method (through monkeypatching: `BigInt.prototype.toJSON = ...`), that method can provide the serialization result. This constraint ensures that a proper serialization (and, very likely, its accompanying deserialization) behavior is always explicitly provided by the user.
- [`undefined`](../../globals/undefined.mdx), `Function`, and `Symbol` values are not valid JSON values. If any such values are encountered during conversion, they are either omitted (when found in an object) or changed to [`null`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/null) (when found in an array). `JSON.stringify()` can return `undefined` when passing in "pure" values like `JSON.stringify(() => {})` or `JSON.stringify(undefined)`.
- The numbers [`Infinity`](../../globals/Infinity.mdx) and [`NaN`](../../globals/NaN.mdx), as well as the value [`null`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/null), are all considered `null`. (But unlike the values in the previous point, they would never be omitted.)
- Arrays are serialized as arrays (enclosed by square brackets). Only array indices between 0 and `length - 1` (inclusive) are serialized; other properties are ignored.
- For other objects:

  - All `Symbol`-keyed properties will be completely ignored, even when using the [`replacer`](#the-replacer-parameter) parameter.

  - If the value has a `toJSON()` method, it's responsible to define what data will be serialized. Instead of the object being serialized, the value returned by the `toJSON()` method when called will be serialized. `JSON.stringify()` calls `toJSON` with one parameter, the `key`, which has the same semantic as the `key` parameter of the [`replacer`](#the-replacer-parameter) function:

    - if this object is a property value, the property name
    - if it is in an array, the index in the array, as a string
    - if `JSON.stringify()` was directly called on this object, an empty string

    `Date` objects implement the [`toJSON()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date/toJSON) method which returns a string (the same as [`date.toISOString()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)). Thus, they will be stringified as strings.

  - Only [enumerable own properties](https://developer.mozilla.org/docs/Web/JavaScript/Enumerability_and_ownership_of_properties) are visited. This means [Map](../../globals/Map/Map.mdx), [Set](../../globals/Set/Set.mdx), etc. will become `"{}"`. You can use the [`replacer`](#the-replacer-parameter) parameter to serialize them to something more useful.

    Properties are visited using the same algorithm as [`Object.keys()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/keys), which has a well-defined order and is stable across implementations. For example, `JSON.stringify` on the same object will always produce the same string, and `JSON.parse(JSON.stringify(obj))` would produce an object with the same key ordering as the original (assuming the object is completely JSON-serializable).

### The replacer parameter

The `replacer` parameter can be either a function or an array.

As an array, its elements indicate the names of the properties in the object that should be included in the resulting JSON string. Only string and number values are taken into account; symbol keys are ignored.

As a function, it takes two parameters: the `key` and the `value` being stringified. The object in which the key was found is provided as the `replacer`'s `this` context.

The `replacer` function is called for the initial object being stringified as well, in which case the `key` is an empty string (`""`). It is then called for each property on the object or array being stringified. Array indices will be provided in its string form as `key`. The current property value will be replaced with the `replacer`'s return value for stringification. This means:

- If you return a number, string, boolean, or `null`, that value is directly serialized and used as the property's value. (Returning a BigInt will throw as well.)
- If you return a `Function`, `Symbol`, or [`undefined`](../../globals/undefined.mdx), the property is not included in the output.
- If you return any other object, the object is recursively stringified, calling the `replacer` function on each property.

> **Note:** When parsing JSON generated with `replacer` functions, you would likely want to use the [`reviver`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#using_the_reviver_parameter) parameter to perform the reverse operation.

Typically, array elements' index would never shift (even when the element is an invalid value like a function, it will become `null` instead of omitted). Using the `replacer` function allows you to control the order of the array elements by returning a different array.

### The space parameter

The `space` parameter may be used to control spacing in the final string.

- If it is a number, successive levels in the stringification will each be indented by this many space characters.
- If it is a string, successive levels will be indented by this string.

Each level of indentation will never be longer than 10. Number values of `space` are clamped to 10, and string values are truncated to 10 characters.
