JavaScript Array copyWithin() Method

What You’ll Learn

The copyWithin() method copies a run of elements from one index range to another inside the same array, overwriting what was there. Length stays the same; only slot values change. This tutorial covers syntax, five examples, overlap behavior, and how it differs from slice and splice.

Introduction

Sometimes you need to move or duplicate a block of values within one array—shift the last few items to the front, fill a gap with a repeated pattern, or rotate a buffer without allocating a new array. That is what copyWithin() is for.

Unlike concat(), which returns a new array, copyWithin() modifies the array you call it on. Unlike splice(), it never inserts or removes slots—the array length is unchanged.

Understanding the copyWithin() Method

Think of copyWithin(target, start, end) as selecting elements from index start up to (but not including) end, then writing them sequentially starting at target, replacing whatever was already there.

Negative indices count from the end, like other array methods. If end is omitted, copying continues through the end of the array.

📝 Syntax

General form of Array.prototype.copyWithin:

array.copyWithin(target, start, end)

Parameters

• target — index where pasted values begin (0-based).
• start — first source index to copy (inclusive).
• end — optional; stop before this index (exclusive). Defaults to array.length.

Return value

• The modified array (same reference as the caller).
• Length is never changed.

Common patterns

• arr.copyWithin(0, 3, 6) — copy three elements from index 3 to the front.
• arr.copyWithin(0, -3) — move the last three elements to the start.
• [...arr].copyWithin(...) — mutate a clone to preserve the original.

Examples Gallery

Open DevTools Console (F12) or use Try-it labs. Example N maps to ?tryit=N.

const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9];

numbers.copyWithin(0, 3, 6);

console.log(numbers);
// [4, 5, 6, 4, 5, 6, 7, 8, 9]

[4, 5, 6, 4, 5, 6, 7, 8, 9]

const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9];

numbers.copyWithin(0, -3);

console.log(numbers);
// [7, 8, 9, 4, 5, 6, 7, 8, 9]

[7, 8, 9, 4, 5, 6, 7, 8, 9]

const pattern = [1, 2, 3, 0, 0, 0];

pattern.copyWithin(3, 0, 3);

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

[1, 2, 3, 1, 2, 3]

const original = [1, 2, 3, 4, 5];
const working = [...original];

working.copyWithin(0, 2, 4);

console.log(original);  // [1, 2, 3, 4, 5]
console.log(working);   // [3, 4, 3, 4, 5]

[1, 2, 3, 4, 5]
[3, 4, 3, 4, 5]

const letters = ["a", "b", "c", "d", "e"];

letters.copyWithin(1, 3);

console.log(letters);
// ["a", "d", "e", "d", "e"]

["a", "d", "e", "d", "e"]

🚀 Common Use Cases

• Ring buffers — rotate or slide window contents without reallocating.
• In-place normalization — move defaults or padding within a fixed-size array.
• Typed arrays — efficient bulk moves on binary data views.
• Game grids — scroll tile rows/columns inside a flat representation.
• Audio samples — shift waveform segments inside a buffer.
• Immutable UI state — clone first, then copyWithin on the copy for Redux-style updates.

📝 Notes

• end is exclusive, like slice(start, end).
• Overlapping source and destination is allowed; engines copy in a safe order.
• Out-of-range indices are clamped; copying zero elements is valid and is a no-op.
• Holey (sparse) arrays copy holes as empty slots.
• For a new array instead of mutation, use slice or spread, not copyWithin on the original.
• Works on typed arrays such as Uint8Array with the same signature.

💡 Best Practices