The copyWithin() method

JavaScriptMiddle~3 min read

copyWithin() is an array method that copies a part of the array into another place inside that same array without changing its length. It mutates the array in place and returns a reference to it, so it works as a cheap data shift with no new array allocated.

Theory

TL;DR

arr.copyWithin(target, start, end) copies the slice [start, end) to position target of the same array.
The method mutates the original array and returns that very array (this), not a copy.
The array length never changes: elements that do not fit are simply not inserted.
end is optional: without it the copying runs to the end of the array.
Indexes may be negative, in which case they count from the end of the array.
A typical use is shifting values inside a buffer without creating a new array.

Quick example

javascript

const arr = [1, 2, 3, 4, 5];
arr.copyWithin(0, 3);

console.log(arr); // [4, 5, 3, 4, 5]

Syntax and parameters

javascript

arr.copyWithin(target, start, end);

Parameter	Description
`target`	The index to which the elements will be copied
`start`	The index from which to start copying (inclusive)
`end`	The index at which to stop (this index is not included). Optional. If omitted, copies to the end of the array

Example 1: the basic case

javascript

const arr = [1, 2, 3, 4, 5];
arr.copyWithin(0, 3);

console.log(arr); // [4, 5, 3, 4, 5]

Step by step:

target = 0, so we insert starting at position 0.
start = 3, so we start copying from index 3.
We copy [4, 5].
Result: [4, 5, 3, 4, 5].

Example 2: with start and end

javascript

const arr = [1, 2, 3, 4, 5];
arr.copyWithin(1, 3, 5);

console.log(arr); // [1, 4, 5, 4, 5]

We copy the elements [4, 5] (from index 3 up to 5, not including 5).
We insert them starting at position 1.

Example 3: negative indexes

javascript

const arr = [10, 20, 30, 40, 50];
arr.copyWithin(-2, 0, 2);

console.log(arr); // [10, 20, 30, 10, 20]

-2 means «insert starting from the second element from the end».
We copy [10, 20] and insert it at the end.

Behaviour details

Property	Description
Mutates the array	Yes
Returns	The changed array
Array length	Does not change
Copies inside the array	Yes
Return value	A reference to the same array (`this`)

A practical use: shifting values inside an array without creating a new one.

javascript

const buffer = [1, 2, 3, 4, 5];
buffer.copyWithin(1, 0, 3);
console.log(buffer); // [1, 1, 2, 3, 5]

In brief

Question	Answer
What it does	Copies a part of the array into another place inside it
Does it change the original array	Yes
What it returns	The array itself
Does it change the length	No, the length is fixed
Example	`[1, 2, 3, 4, 5].copyWithin(0, 3)` gives `[4, 5, 3, 4, 5]`

In short: copyWithin() is a way to move or duplicate elements inside an array without creating a new array and without changing its length.

Common mistakes

Expecting the method to return a new array. It mutates the original and returns a reference to it, so const copy = arr.copyWithin(0, 3) gives you the same array, not a copy.
Thinking the array will get longer or shorter. The length is fixed: anything that does not fit is simply dropped.
Confusing copyWithin() with slice() or splice(): slice() returns a new array and mutates nothing, splice() changes the length.
Forgetting that end is exclusive: copyWithin(1, 3, 5) takes the elements at indexes 3 and 4, not 3, 4 and 5.
Ignoring negative indexes and getting an unexpected result: -1 is the last element, not «one before the start».
Applying the method to an array that is referenced somewhere else and then being surprised by changed data in another part of the code.

Short Answer

Interview ready

Premium

A concise answer to help you respond confidently on this topic during an interview.