typedArray.with(index, value) returns a new typed array that is a copy of the original with one element replaced. The original is not changed, which makes it the copying form of ta[index] = value. A negative index counts from the end. An index outside the array throws a RangeError. The value is converted to the element type, so a Uint8Array wraps 300 to 44. It was added in ES2023.
Remember
typedArray.with(index, value) → NEW typed array
const a = new Uint8Array([10, 20, 30]);
a.with(1, 99) → 10 99 30 (a is unchanged)
a.with(-1, 7) → 10 20 7
a.with(3, 1) → RangeError
ta[1] = 99 → changes the original instead
Syntax
Give the position and the new value. Both arguments are used.
JavaScript
typedArray.with(index, value)
Call
What it does
ta.with(1, 99)
Copy the array and put 99 at index 1.
ta.with(-1, 7)
A negative index counts from the end: -1 is the last element.
ta.with(ta.length, 1)
Throws a RangeError: the index is one past the end.
Added in ES2023 for all 11 typed array types. The new value must fit the type of the array: a BigInt array only takes BigInt values.
Library declarations
JavaScript
TypedArray.prototype.with(index, value) // returns a new typed array
// index: integer, negative counts from the end
// index < -length or index >= length -> RangeError
// value is converted to the element type (wrap, clamp, round)
Parameters
Parameter
Description
index
The position to replace. It is turned into an integer. A negative index counts back from the end. If it is smaller than -length or not smaller than length, a RangeError is thrown.
value
The new element. It is converted to the type of the array, for example by wrapping for Uint8Array or clamping for Uint8ClampedArray. BigInt arrays need a BigInt, or a TypeError is thrown.
Return Value
Return Value
Description
TypedArray
A new typed array of the same type and length, with the element at index replaced. It has its own ArrayBuffer.
JavaScript Examples
Example 1 — Replace One Element in a Copy
A Uint8Array holds three brightness levels. We make a changed copy and keep the first version.
Uint8 wraps around. 300 does not fit in one byte, so it wraps to 44 (300 minus 256). The value -1 wraps to 255.
Clamped and single precision. A Uint8ClampedArray stops at 255, and a Float32Array stores the nearest single-precision number to 0.1.
BigInt arrays refuse numbers. The plain number 1 is not a BigInt, so with() throws a TypeError instead of converting it.
Compatibility
Browser & Runtime Support
TypedArray.prototype.with() was added in ES2023, together with toSorted() and toReversed().
✓ Baseline · ES2023
TypedArray.prototype.with()
Supported in recent versions of Chrome, Edge, Firefox, Safari, and Node.js.
93%Recent browsers only
Google ChromeChrome 110 and newer
Full support
Mozilla FirefoxFirefox 115 and newer
Full support
Apple SafariSafari 16 and newer
Full support
Microsoft EdgeEdge 110 and newer
Full support
Node.jsNode.js 20 and newer
Supported
DenoRecent versions
Supported
Internet ExplorerNo support
Not supported
with()Recent browsers
Bottom line: Use it in recent browsers and Node.js 20 or newer. For older ones, copy with slice() and then assign copy[index] = value.
Frequently Asked Questions
A new typed array of the same type and length, with the element at the given index replaced. The original typed array is not changed.
Yes. -1 is the last element, -2 the one before it, and so on. The smallest allowed value is minus the length.
A RangeError, for an index that is below minus the length or equal to or above the length. Printing e.name gives RangeError in every browser.
No. Square brackets change the original and do nothing for a bad index. with() copies, leaves the original alone, and throws a RangeError for a bad index.
Copy with ta.slice() and assign into the copy: const copy = ta.slice(); copy[1] = 99. The result is the same typed array type.