JavaScript TypedArray with() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
ES2023

Definition

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)
CallWhat 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

ParameterDescription
indexThe 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.
valueThe 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 ValueDescription
TypedArrayA 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.

JavaScript
const levels = new Uint8Array([10, 20, 30]);
const brighter = levels.with(1, 99);

console.log(levels.join(' '));            // 10 20 30
console.log(brighter.join(' '));          // 10 99 30
console.log(brighter instanceof Uint8Array);   // true
Try It Yourself

How It Works

  1. One value is swapped. levels.with(1, 99) copies all three elements and puts 99 at index 1, so the 20 is replaced.
  2. The first version survives. levels still prints 10 20 30, because with() never writes into the original.
  3. A Uint8Array again, length 3. The copy is a Uint8Array too, and it has the same length as the original.

Example 2 — Negative Index and RangeError

Counting from the end is handy for the last element. An index that does not exist is an error you can catch.

JavaScript
const stock = new Uint8Array([10, 20, 30]);

console.log(stock.with(-1, 7).join(' '));   // 10 20 7
console.log(stock.with(-3, 1).join(' '));   // 1 20 30

try {
  stock.with(3, 1);
} catch (e) {
  console.log(e.name);                      // RangeError
}

try {
  stock.with(-4, 1);
} catch (e) {
  console.log(e.name);                      // RangeError
}
Try It Yourself

How It Works

  1. -1 is the last element. A negative index is added to the length, so -1 means index 2 and -3 means index 0 of three elements.
  2. Index 3 does not exist. The length is 3, so the last valid index is 2. Index 3 throws a RangeError, which catch prints as a name.
  3. -4 is too far back. The smallest allowed negative index is -length, here -3. So -4 also throws a RangeError.

Example 3 — The Value Is Converted to the Element Type

The value you pass is not stored as it is. It is changed to fit the type, just like when you assign with square brackets.

JavaScript
console.log(new Uint8Array([1, 2]).with(0, 300).join(' '));          // 44 2
console.log(new Uint8Array([1, 2]).with(0, -1).join(' '));           // 255 2
console.log(new Uint8ClampedArray([1, 2]).with(0, 300).join(' '));   // 255 2
console.log(new Float32Array([1, 2]).with(0, 0.1).join(' '));        // 0.10000000149011612 2

try {
  new BigInt64Array(2).with(0, 1);
} catch (e) {
  console.log(e.name);                                               // TypeError
}
Try It Yourself

How It Works

  1. Uint8 wraps around. 300 does not fit in one byte, so it wraps to 44 (300 minus 256). The value -1 wraps to 255.
  2. Clamped and single precision. A Uint8ClampedArray stops at 255, and a Float32Array stores the nearest single-precision number to 0.1.
  3. BigInt arrays refuse numbers. The plain number 1 is not a BigInt, so with() throws a TypeError instead of converting it.

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 Chrome Chrome 110 and newer
Full support
Mozilla Firefox Firefox 115 and newer
Full support
Apple Safari Safari 16 and newer
Full support
Microsoft Edge Edge 110 and newer
Full support
Node.js Node.js 20 and newer
Supported
Deno Recent versions
Supported
Internet Explorer No 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.

Next: [Symbol.iterator]()

Get an iterator that visits every element, using the built-in iteration symbol.

[Symbol.iterator]() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

11 people found this page helpful