JavaScript Array with() Method

What You’ll Learn

The with() method returns a new array with one element replaced at a given index. The original stays unchanged. This tutorial covers syntax, negative indexes, comparison with bracket assignment, the ES2023 immutable methods family, and five examples.

Introduction

Updating one slot in an array usually means arr[2] = "new", which mutates the original. In React and other immutable workflows, you need a copy with one change instead. with(index, value) does exactly that in one readable call.

It is part of the ES2023 “change by copy” family alongside toReversed(), toSorted(), and toSpliced().

Understanding the with() Method

array.with(index, value) shallow-copies the array, sets the resolved index to value, and returns the new array. Length stays the same; no elements are added or removed.

If the index is out of range after resolving negatives, a RangeError is thrown. Unlike at(), which returns undefined for bad reads, with() refuses invalid writes.

📝 Syntax

General form of Array.prototype.with:

array.with(index, value)

Parameters

• index — position to replace (negative counts from end).
• value — new element at that index.

Return value

• A new array with one element replaced.

Common patterns

• arr.with(0, "first") — replace start.
• arr.with(-1, "last") — replace end.
• setState(arr.with(i, val)) — React immutable update.
• [...arr.slice(0,i), val, ...arr.slice(i+1)] — classic fallback.

Examples Gallery

Open DevTools Console (F12) or use Try-it labs. Example N maps to ?tryit=N. Requires a browser with ES2023 with() support.

const fruits = ["apple", "orange", "banana", "grape"];

const updated = fruits.with(2, "pineapple");

console.log(updated);
// ["apple", "orange", "pineapple", "grape"]

console.log(fruits[2]);
// "banana"

["apple", "orange", "pineapple", "grape"]
banana

const original = [1, 2, 3, 4, 5];
const modified = original.with(2, 999);

console.log(original);
// [1, 2, 3, 4, 5]

console.log(modified);
// [1, 2, 999, 4, 5]

console.log(original === modified);
// false

[1, 2, 3, 4, 5]
[1, 2, 999, 4, 5]
false

const items = ["a", "b", "c"];

const updated = items.with(-1, "z");

console.log(updated);
// ["a", "b", "z"]

["a", "b", "z"]

const immutable = [10, 20, 30];
const mutable = [10, 20, 30];

const next = immutable.with(1, 99);
mutable[1] = 99;

console.log("immutable original:", immutable);
// [10, 20, 30]

console.log("with result:", next);
// [10, 99, 30]

console.log("mutable after [1]=:", mutable);
// [10, 99, 30]

immutable original: [10, 20, 30]
with result: [10, 99, 30]
mutable after [1]=: [10, 99, 30]

const nums = [1, 2, 3, 4];

try {
  nums.with(10, 0);
} catch (err) {
  console.log(err.name);
  // "RangeError"
}

RangeError

🚀 Common Use Cases

• React state — setItems(items.with(i, newVal)).
• Undo stacks — keep prior array version intact.
• Immutable configs — tweak one setting in a list.
• Game boards — update one cell in a grid array.
• Form rows — replace one field value in an array of inputs.
• Functional style — chain with other non-mutating methods.

📝 Notes

• Does not mutate the original array.
• Returns a new array (assign the result).
• Shallow copy—nested objects are shared.
• Invalid index throws RangeError.
• Does not change array length.
• ES2023—use spread/slice fallback for older browsers.
• Not the same as JavaScript’s deprecated with statement.

💡 Best Practices