Suggest an edit

Improve this article

Refine the answer for “The copyWithin() method”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

**`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.

Markdown · drag & drop images · ⌘B / ⌘I shortcuts729 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.