ThecopyWithin() method ofArray instances shallow copies part of this array to another location in the same array and returns this array without modifying its length.

Try it

const array = ["a", "b", "c", "d", "e"];// Copy to index 0 the element at index 3console.log(array.copyWithin(0, 3, 4));// Expected output: Array ["d", "b", "c", "d", "e"]// Copy to index 1 all elements from index 3 to the endconsole.log(array.copyWithin(1, 3));// Expected output: Array ["d", "d", "e", "d", "e"]

Syntax

copyWithin(target, start)copyWithin(target, start, end)

Parameters

target

Zero-based index at which to copy the sequence to,converted to an integer. This corresponds to where the element atstart will be copied to, and all elements betweenstart andend are copied to succeeding indices.

• Negative index counts back from the end of the array — if-array.length <= target < 0,target + array.length is used.
• Iftarget < -array.length,0 is used.
• Iftarget >= array.length, nothing is copied.
• Iftarget is positioned afterstart after normalization, copying only happens until the end ofarray.length (in other words,copyWithin() never extends the array).

start

Zero-based index at which to start copying elements from,converted to an integer.

• Negative index counts back from the end of the array — if-array.length <= start < 0,start + array.length is used.
• Ifstart < -array.length,0 is used.
• Ifstart >= array.length, nothing is copied.

endOptional

Zero-based index at which to end copying elements from,converted to an integer.copyWithin() copies up to but not includingend.

• Negative index counts back from the end of the array — if-array.length <= end < 0,end + array.length is used.
• Ifend < -array.length,0 is used.
• Ifend >= array.length orend is omitted orundefined,array.length is used, causing all elements until the end to be copied.
• Ifend implies a position before or at the position thatstart implies, nothing is copied.

Return value

The modified array.

Description

ThecopyWithin() method works like C and C++'smemmove, and is a high-performance method to shift the data of anArray. This especially applies to theTypedArray method of the same name. The sequence is copied and pasted as one operation; the pasted sequence will have the copied values even when the copy and paste region overlap.

Becauseundefined becomes0 when converted to an integer, omitting thestart parameter has the same effect as passing0, which copies the entire array to the target position, equivalent to a right shift where the right boundary is clipped off and the left boundary is duplicated. This behavior may confuse readers of your code, so you should explicitly pass0 asstart instead.

console.log([1, 2, 3, 4, 5].copyWithin(2));// [1, 2, 1, 2, 3]; move all elements to the right by 2 positions

ThecopyWithin() method is amutating method. It does not alter the length ofthis, but it will change the content ofthis and create new properties or delete existing properties, if necessary.

ThecopyWithin() method preserves empty slots. If the region to be copied from issparse, the empty slots' corresponding new indices aredeleted and also become empty slots.

ThecopyWithin() method isgeneric. It only expects thethis value to have alength property and integer-keyed properties. Although strings are also array-like, this method is not suitable to be applied on them, as strings are immutable.

Examples

Using copyWithin()

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

Using copyWithin() on sparse arrays

copyWithin() will propagate empty slots.

console.log([1, , 3].copyWithin(2, 1, 2)); // [1, empty, empty]

Calling copyWithin() on non-array objects

ThecopyWithin() method reads thelength property ofthis and then manipulates the integer indices involved.

const arrayLike = {  length: 5,  3: 1,};console.log(Array.prototype.copyWithin.call(arrayLike, 0, 3));// { '0': 1, '3': 1, length: 5 }console.log(Array.prototype.copyWithin.call(arrayLike, 3, 1));// { '0': 1, length: 5 }// The '3' property is deleted because the copied source is an empty slot

Specifications

Browser compatibility

See also

• Polyfill ofArray.prototype.copyWithin incore-js
• es-shims polyfill ofArray.prototype.copyWithin
• Indexed collections guide
• Array
• TypedArray.prototype.copyWithin()