JavaScript TypedArray copyWithin() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
ES2015

Definition

typedArray.copyWithin(target, start, end) copies the elements from start up to, but not including, end to the position target inside the same typed array. The length never changes, and anything that would run past the end is dropped. The copy is overlap-safe, and the method returns the same typed array, so it is handy for shifting data inside a fixed buffer.

Remember
ta.copyWithin(target, start)
ta.copyWithin(target, start, end)

[1,2,3,4,5,6].copyWithin(0, 3)     → 4 5 6 4 5 6
[1,2,3,4,5].copyWithin(1, 0)       → 1 1 2 3 4
length never changes, returns the same array

Syntax

The target is required. Start and end are optional and the end index is not included.

JavaScript
typedArray.copyWithin(target, start)
typedArray.copyWithin(target, start, end)
CallWhat it does
ta.copyWithin(0, 3)Copy everything from index 3 to the end to the beginning.
ta.copyWithin(2, 0, 2)Copy the elements at indexes 0 and 1 to indexes 2 and 3.
ta.copyWithin(-2, 0)Negative numbers count from the end: write at the second-to-last slot.

Available since ES2015 on all 11 types. The same method exists on regular Arrays, but a typed array can never grow or shrink.

Library declarations
JavaScript
TypedArray.prototype.copyWithin(target, start, end = length)

// negative numbers count from the end
// copies at most length - target elements
// overlapping ranges are copied safely
// returns the SAME typed array (this)

Parameters

ParameterDescription
targetIndex where the copied elements are written. Negative counts from the end.
start (optional)Index of the first element to copy. Negative counts from the end. Defaults to 0.
end (optional)Index to stop before. Negative counts from the end. Defaults to the length.

Return Value

Return ValueDescription
TypedArrayThe same typed array you called it on, changed in place. Its length is the same as before.

JavaScript Examples

Example 1 — Copy Part of the Array Forward

Six samples are stored in a Uint8Array. We copy the second half to the front, then a smaller range into the middle.

JavaScript
const samples = new Uint8Array([1, 2, 3, 4, 5, 6]);

samples.copyWithin(0, 3);
console.log(samples.join(' '));   // 4 5 6 4 5 6

const grid = new Uint8Array([1, 2, 3, 4, 5, 6]);
const result = grid.copyWithin(1, 3, 5);
console.log(grid.join(' '));      // 1 4 5 4 5 6
console.log(result === grid);     // true
Try It Yourself

How It Works

  1. Target 0, start 3. The elements at indexes 3 to 5 are written to indexes 0 to 2. The second half stays as it was.
  2. A range with an end. copyWithin(1, 3, 5) copies indexes 3 and 4 (the values 4 and 5) to indexes 1 and 2.
  3. The same array is returned. The result is the object grid itself, not a copy, so the comparison is true.

Example 2 — Overlapping Copies Are Safe

When the source and the target ranges overlap, the copy still behaves as if the source were saved first. That makes shifting data easy.

JavaScript
const right = new Uint8Array([1, 2, 3, 4, 5]);
right.copyWithin(1, 0);
console.log(right.join(' '));   // 1 1 2 3 4

const left = new Uint8Array([1, 2, 3, 4, 5]);
left.copyWithin(0, 1);
console.log(left.join(' '));    // 2 3 4 5 5

const tail = new Uint8Array([1, 2, 3, 4, 5]);
tail.copyWithin(3, 0);
console.log(tail.join(' '));    // 1 2 3 1 2
Try It Yourself

How It Works

  1. Shifting right. Index 0 to 3 move one step up, giving 1 1 2 3 4. A naive loop would have produced 1 1 1 1 1.
  2. Shifting left. Index 1 to 4 move one step down. The last element is not cleared, so the final 5 appears twice.
  3. Anything past the end is dropped. Only two slots remain after index 3, so just the values 1 and 2 are copied and the length stays 5.

Example 3 — Negative Indexes and Out-of-Range Targets

Negative numbers count from the end. An Int16Array keeps its negative values while they are copied.

JavaScript
const wave = new Int16Array([10, -20, 30, -40, 50]);
wave.copyWithin(-2, 0, 2);
console.log(wave.join(' '));        // 10 -20 30 10 -20

const history = new Int16Array([1, 2, 3, 4, 5]);
history.copyWithin(0, -2);
console.log(history.join(' '));     // 4 5 3 4 5

const safe = new Int16Array([1, 2, 3]);
safe.copyWithin(5, 0);
console.log(safe.join(' '));        // 1 2 3
console.log(safe.length);           // 3
Try It Yourself

How It Works

  1. -2 is the second-to-last index. On five elements, copyWithin(-2, 0, 2) writes the first two values at indexes 3 and 4.
  2. A negative start works too. copyWithin(0, -2) reads the last two elements, 4 and 5, and puts them at the front.
  3. A target past the end does nothing. Index 5 is outside a three-element array, so there is no room to write, and no error is thrown.

Browser & Runtime Support

TypedArray.prototype.copyWithin() is part of ES2015 (ES6), together with the other array-like typed array methods.

✓ Baseline · ES2015

TypedArray.prototype.copyWithin()

Supported in every modern browser, plus Node.js, Deno, and Bun.

98% Modern browser support
Google Chrome All modern versions
Full support
Mozilla Firefox All modern versions
Full support
Apple Safari All modern versions
Full support
Microsoft Edge All modern versions
Full support
Node.js All current releases
Supported
Deno All releases
Supported
Internet Explorer IE 10 and 11 have typed arrays, but not this method
Not supported
copyWithin() Excellent

Bottom line: Safe everywhere modern JavaScript runs. Internet Explorer 10 and 11 have typed arrays, but not the copyWithin() method.

Frequently Asked Questions

It copies a range of elements to another position in the same typed array. It changes the array in place, keeps its length, and returns the same typed array.
Yes. The elements are copied as if they were saved first, so copyWithin(1, 0) on 1 2 3 4 5 gives 1 1 2 3 4.
No. The source elements stay where they are unless they get overwritten. Use fill() afterwards if you want to reset them.
Only the elements that fit are copied, and the rest are dropped. A target past the end copies nothing. The length never changes and no error is thrown.
copyWithin() moves values inside one typed array. set() copies from another array or typed array into the target, and throws a RangeError if the source does not fit.

Next: entries()

Walk through [index, value] pairs of a typed array with the entries() iterator.

entries() 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