JavaScript Array.with() method (with examples)

This concise, straightforward article is dedicated to the Array.with() method in modern JavaScript.

Overview

The Array.with() method was added to the programming language in ECMAScript 2021, which is the 12th edition of the ECMAScript Language Specification (ES 12).

The purpose of the Array.with() method is to change the value of a given index in an array, returning a new array with the element at the given index replaced with the given value. The original array is not modified. This allows you to chain array methods while doing manipulations. The Array.with() method never produces a sparse array (in case you aren’t familiar with sparse arrays, see the More about sparse arrays section in this article).

Syntax & Parameters

At the time of writing, the Array.with() method is compatible with most modern browsers on both desktop and mobile.

Syntax:

arrayObject.with(index, value)

Parameters:

• index: Zero-based index at which to change the array, converted to an integer. Negative index counts back from the end of the array (if index < 0, index + array.length is used). If the index after normalization is out of bounds, a RangeError is thrown.
• value: Any value to be assigned to the given index.

Return value: A new array with the element at index replaced with value.

More about sparse arrays

A sparse array in JavaScript is an array that has gaps or holes where some indices have no values. For example, if you create an array like this:

let arr = [1, , 3, 4, , 6];

You have created a sparse array with two holes at index 1 and 4. The length of this array is 6, but it only has 4 elements. The holes are treated as undefined values.

The Array.with() method never produces a sparse array means that even if you use this method on a sparse array, the result will always be a dense array. A dense array is an array that has no gaps or holes and has values at every index from 0 to length – 1. For example, if you use the Array.with() method on the sparse array above, like so:

let arr = [1, , 3, 4, , 6];
let newArr = arr.with(0, 2);
console.log(newArr);

The result will be a dense array like this:

[2, undefined, 3, 4, undefined, 6]

Examples

Let’s get a better understanding of the Array.with() method by writing some code.

Creating a new array with a single element changed

const arr = [1, 2, 3, 4, 5];

const newArr = arr.with(2, 6);
console.log(newArr); // [1, 2, 6, 4, 5]

// The original array is not mutated
console.log(arr); // [1, 2, 3, 4, 5]

This example shows how to use the Array.with() method to create a new array with the element at index 2 (the third element) changed from 3 to 6. The original array arr is not modified.

Chaining array methods

const arr = [1, 2, 3, 4, 5];
console.log(arr.with(2, 6).map((x) => x ** 2)); 
// Output: [1, 4, 36, 16, 25]

This example demonstrates how to use the Array.with() method and then apply another array method (map()) on the result. The map() method takes a function that squares each element of the array and returns a new array with the squared values.

Calling Array.with() on non-array objects

// Declare an object with length and integer-keyed properties
const arrayLike = { length: 3, unrelated: "foo", 0: 5, 2: 4, 3: 3 };

// Log a new array with the element at index 0 changed to 1
console.log(Array.prototype.with.call(arrayLike, 0, 1));
// Result: [1, undefined, 4]

The code snippet above uses the Array.with() method on a non-array object that has a length property and integer-keyed properties. The Array.with() method creates and returns a new array by reading and copying the properties of the object that match the criteria of an array index (a nonnegative integer less than length). The property at index 0 is changed from 5 to 1 in the new array.

The result has only 3 elements because the length property of the array-like object determines how many elements are in the new array returned by the Array.with() method. In this case, the length property is 3, so the new array has 3 elements. The Array.with() method ignores any properties that are out of bounds according to the length property. For instance, the property named 3 is ignored because it is beyond the length of 3.