The JavaScript Array.with() method creates a new array by replacing an element at a specified index with a new value, while keeping the original array unchanged. This method is useful when you need to update an element in an array immutably without modifying the original array.

For example, array.with(index, value) is handy when you need to replace an item in an array at a certain position and return a new modified array.

Syntax

The syntax for the Array.with() method is:

array.with(index, value)

Parameters

The Array.with() method accepts two parameters:

• index (Required): The index of the element to replace in the array. It can be a positive or negative integer. Negative values count from the end of the array.
• value (Required): The new value to replace the element at the specified index.

Return Value

The method returns a new array with the specified element replaced by the new value. The original array remains unchanged.

Examples of JavaScript Array.with() Method

Example 1: Replacing an Element in the Array

You can use with() to replace an element at a specific index in the array without altering the original array.

const numbers = [10, 20, 30, 40, 50];
const newNumbers = numbers.with(2, 35);
console.log(newNumbers);  // Output: [10, 20, 35, 40, 50]
console.log(numbers);     // Output: [10, 20, 30, 40, 50]

Explanation: The with() method creates a new array where the element at index 2 (30) is replaced with 35, leaving the original array unchanged.

Example 2: Using Negative Indexes

You can use negative indices with the with() method to replace elements counting from the end of the array.

const fruits = ['apple', 'banana', 'mango', 'grape'];
const newFruits = fruits.with(-1, 'orange');
console.log(newFruits);  // Output: ['apple', 'banana', 'mango', 'orange']
console.log(fruits);     // Output: ['apple', 'banana', 'mango', 'grape']

Explanation: The with(-1, 'orange') method replaces the last element ('grape') with 'orange'. The original fruits array remains unchanged.

Example 3: Attempting to Replace an Element Out of Bounds

If you try to use an index that is out of bounds, the with() method throws an error.

const numbers = [1, 2, 3];
try {
 const newNumbers = numbers.with(5, 10);
 console.log(newNumbers);
} catch (e) {
 console.error(e);  // Output: RangeError: Index out of range
}

Explanation: The with() method throws a RangeError because index 5 is out of range for the numbers array, which only has three elements.

Example 4: Replacing an Element in a Nested Array

You can use with() to replace elements inside a nested array.

const matrix = [[1, 2], [3, 4], [5, 6]];
const newMatrix = matrix.with(1, [7, 8]);
console.log(newMatrix);  // Output: [[1, 2], [7, 8], [5, 6]]
console.log(matrix);     // Output: [[1, 2], [3, 4], [5, 6]]

Explanation: The with() method replaces the second subarray ([3, 4]) with [7, 8], returning a new matrix without altering the original one.

Example 5: Replacing a Value in a Sparse Array

The with() method can be used to replace values in sparse arrays, leaving the rest of the array unchanged.

const sparseArray = [1, , 3];
const newArray = sparseArray.with(1, 2);
console.log(newArray);  // Output: [1, 2, 3]
console.log(sparseArray); // Output: [1, <1 empty slot>, 3]

Explanation: The with() method replaces the empty slot at index 1 with 2, creating a new array, while the original array still has the empty slot.