# How Does the JSON.stringify Replacer Function Work: Array vs Function Guide

> Learn how JSON.stringify replacer functions work with arrays and callback functions. Filter and transform data for precise JSON output. Master JavaScript serialization.

- Repository: [Lydia Hallie/javascript-questions](https://github.com/lydiahallie/javascript-questions)
- Tags: deep-dive
- Published: 2026-03-04

---

**The `JSON.stringify` replacer function acts as a selective filter or value transformer during serialization, accepting either an array of allowed property names or a callback function that processes each key-value pair to determine what appears in the final JSON string.**

The `JSON.stringify` method converts JavaScript values to JSON strings, but its second argument—the replacer—provides fine-grained control over this process. According to the `lydiahallie/javascript-questions` repository, understanding how the JSON.stringify replacer function works is critical for security-sensitive applications where you must exclude passwords or transform data before API transmission. The replacer operates in one of two modes: an **array-based whitelist** or a **function-based processor**.

## Array Replacer: Whitelisting Specific Properties

When you pass an **array of strings** as the replacer, `JSON.stringify` treats it as a property whitelist. Only the keys explicitly listed in the array are included in the output; all other properties are omitted regardless of their values.

As documented in [[`README.md`](https://github.com/lydiahallie/javascript-questions/blob/main/README.md)](https://github.com/lydiahallie/javascript-questions/blob/master/README.md#L1942-L1948) of the `lydiahallie/javascript-questions` repository, this approach is ideal for quickly filtering large objects to include only necessary fields like `level` and `health` while discarding sensitive metadata.

```javascript
// Array replacer – only 'level' and 'health' survive serialization
const settings = { username: 'lydiahallie', level: 19, health: 90 };
const json = JSON.stringify(settings, ['level', 'health']);

console.log(json);
// {"level":19,"health":90}

```

## Function Replacer: Dynamic Transformation and Filtering

A **function replacer** offers programmatic control, executing depth-first against every property in the object hierarchy. The function receives three arguments: the current `key` (string), the `value`, and the `holder` object (the parent containing the property). For the root object itself, the key is an empty string.

According to the implementation details in [[`README.md`](https://github.com/lydiahallie/javascript-questions/blob/main/README.md)](https://github.com/lydiahallie/javascript-questions/blob/master/README.md#L1942-L1960), whatever value the function returns becomes the serialized output for that property. Returning `undefined` explicitly removes the property from the JSON string entirely.

```javascript
// Function replacer – remove properties conditionally
function censor(key, value) {
  return key.toLowerCase().includes('password') ? undefined : value;
}

const user = { name: 'Lydia', password: 'secret', age: 21 };
const json = JSON.stringify(user, censor);

console.log(json);
// {"name":"Lydia","age":21}

```

You can also use the replacer to transform values during serialization, such as converting strings to uppercase or formatting numbers.

```javascript
// Transform values during stringification
function toUpperCase(key, value) {
  return typeof value === 'string' ? value.toUpperCase() : value;
}

const data = { title: 'hello', count: 5 };
console.log(JSON.stringify(data, toUpperCase));
// {"title":"HELLO","count":5}

```

## Combining Array and Function Patterns

While less common, you can implement complex logic by combining whitelist filtering with transformation logic. The array first constrains which keys are processed, then the function transforms the values of those allowed keys.

```javascript
// Array selects keys, function masks string values
const arrReplacer = ['name', 'age'];

function mask(value) {
  return typeof value === 'string' ? '***' : value;
}

const person = { name: 'Lydia', age: 30, city: 'NY' };
console.log(JSON.stringify(person, arrReplacer, mask));
// {"name":"***","age":30}

```

## Summary

- The **replacer parameter** is the second argument to `JSON.stringify`, supporting either an array or function approach.
- **Array replacers** act as whitelists, serializing only the property names explicitly included in the array.
- **Function replacers** traverse the object depth-first, receiving `(key, value, holder)` and allowing dynamic filtering by returning `undefined` or transformation by returning modified values.
- The canonical examples and behavior specifications reside in the `lydiahallie/javascript-questions` repository at [[`README.md`](https://github.com/lydiahallie/javascript-questions/blob/main/README.md)](https://github.com/lydiahallie/javascript-questions/blob/master/README.md#L1942-L1960).

## Frequently Asked Questions

### What arguments does the JSON.stringify replacer function receive?

The replacer function receives three arguments: the property key as a string, the current value, and the holder object (the parent containing the property). For the root object being stringified, the key parameter is an empty string.

### How do I exclude a property from JSON.stringify output using a replacer?

Return `undefined` from the replacer function for that specific key. When the function returns undefined, `JSON.stringify` omits that property entirely from the resulting JSON string, effectively filtering it out.

### Does the replacer function process nested objects recursively?

Yes, the replacer executes using a **depth-first** algorithm. It first processes the root object, then recursively traverses each nested property, allowing you to filter or transform values at any depth within the object hierarchy.

### Can I use an array and function replacer at the same time?

While `JSON.stringify` accepts only one replacer argument, you can achieve combined behavior by using an array to whitelist properties and then applying transformation logic within a function, or by passing an array that contains filtering logic. The repository demonstrates patterns where arrays select keys and subsequent functions handle value masking.