Suggest an edit

Improve this article

Refine the answer for “The unshift() 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)

**`unshift()` does the opposite of what `shift()` does: it adds one or more elements to the beginning of an array and returns the array's new length.** The method changes (mutates) the original array, and every existing element is shifted to the right onto new indexes.

## Theory

### TL;DR

- `unshift()` adds elements **to the beginning of the array**, at index `0`.
- All existing elements are **shifted to the right**.
- The method **mutates** the original array.
- It returns the **new length of the array**, not the array itself.
- You can pass **several values at once**, and they keep their order.
- Its counterpart: `shift()` removes an element from the front.

### Quick example

```javascript
const fruits = ['banana', 'cherry'];
const newLength = fruits.unshift('apple');

console.log(fruits);     // ['apple', 'banana', 'cherry']
console.log(newLength);  // 3
```

Here `'apple'` became the element at index `0`, `'banana'` moved from `0` to `1`, and `'cherry'` from `1` to `2`. The variable holds the number `3`, because the method returns the length, not the array.

### Several elements in one call

```javascript
const numbers = [3, 4];
numbers.unshift(1, 2);

console.log(numbers); // [1, 2, 3, 4]
```

The arguments are inserted **as a block and in the same order** in which they were passed. So `unshift(1, 2)` is not the same as two consecutive calls `unshift(1)` and `unshift(2)`: the second variant would give `[2, 1, 3, 4]`.

### How it works internally

1. It makes room at the beginning of the array.
2. It shifts all current elements onto new indexes.
3. It inserts the new values at the positions starting from `0`.
4. It updates the `length` property.

Step 2 is exactly why `unshift()` is more expensive than `push()`: appending at the end does not touch any other element's index, while inserting at the front requires rewriting the indexes of the whole array.

### Comparison with the other methods

| Method | What it does | Where it adds / removes | What it returns | Mutates the array |
| --- | --- | --- | --- | --- |
| `push()` | Adds an element | At the **end** | The new length | Yes |
| `pop()` | Removes an element | From the **end** | The removed element | Yes |
| `unshift()` | Adds an element | At the **beginning** | The new length | Yes |
| `shift()` | Removes an element | From the **beginning** | The removed element | Yes |

### Usage example: a queue

```javascript
const queue = [];

queue.unshift('first');
queue.unshift('second');

console.log(queue); // ['second', 'first']
```

Each new element lands in front of the previous one, so the oldest value stays at the end of the array. Such a queue is convenient to serve with `pop()`: you take from the end the item that got there earliest, which gives you **FIFO (First In - First Out)** behaviour.

### In brief

| Action | Description |
| --- | --- |
| `arr.unshift(value1, value2, ...)` | Adds an element or elements to the beginning |
| Returns | The new length of the array |
| Changes the array | Yes |
| Example | `[2, 3].unshift(1)` gives `[1, 2, 3]` |

> **Bottom line:** `unshift()` is the method for adding elements to the beginning of an array, with an automatic shift of all indexes and an update of the length.

### Common mistakes

- **Assuming the method returns the array.** `const arr = old.unshift(x)` puts a number into `arr`. To keep working with the array, call `unshift()` on its own line.
- **Counting on immutability.** `unshift()` mutates the original array. If you need a new copy, use `[newItem, ...arr]` or `arr.toSpliced(0, 0, newItem)`.
- **Mixing up the argument order.** `unshift(1, 2)` gives `[1, 2, ...]`, not `[2, 1, ...]`.
- **Putting `unshift()` in a hot loop.** Every call reindexes the whole array, so accumulating thousands of elements from the front is noticeably slower than `push()` followed by `reverse()`.
- **Using it on "array-like" objects carelessly.** On `arguments` or on a DOM collection the method is only available through `Array.prototype.unshift.call(...)`, and on a live DOM collection it will not work.

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

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.