unshift() - метод для добавления элементов в начало массива в JavaScript

unshift() добавляет один или несколько элементов в начало массива.

Это парный метод к shift(): shift() удаляет первый элемент, а unshift() добавляет новые элементы в начало.

Синтаксис

array.unshift(element1)
array.unshift(element1, element2, ...)

Метод принимает один или несколько элементов и вставляет их в начало массива.

Что делает unshift()

После вызова unshift() новые элементы появляются в начале массива, а старые сдвигаются вправо.

const numbers = [20, 30];

numbers.unshift(10);

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

Метод работает прямо с исходным массивом, а не создаёт новый.

Добавление одного элемента

const fruits = ["banana", "orange"];

fruits.unshift("apple");

console.log(fruits); // ["apple", "banana", "orange"]

Это самый простой сценарий использования unshift().

Добавление нескольких элементов

За один вызов можно добавить сразу несколько значений:

const numbers = [3, 4];

numbers.unshift(1, 2);

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

Элементы добавляются в том порядке, в котором были переданы.

Что возвращает unshift()

unshift() возвращает не массив, а новую длину массива.

const items = ["b", "c"];
const result = items.unshift("a");

console.log(result); // 3
console.log(items);  // ["a", "b", "c"]

Это важный момент, потому что его часто путают.

unshift() меняет исходный массив

После вызова unshift() сам массив становится другим:

const list = [2, 3];

list.unshift(1);

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

Если нужен новый массив без изменения старого, чаще используют spread:

const list = [2, 3];
const newList = [1, ...list];

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

Когда это полезно

unshift() удобно использовать, когда:

нужно добавить элемент в начало массива
нужно быстро собрать массив слева направо
изменение исходного массива допустимо

Пример:

const messages = ["world"];

messages.unshift("hello");

console.log(messages); // ["hello", "world"]

unshift() и push()

Оба метода добавляют элементы, но с разных сторон массива.

const values = [2, 3];

values.unshift(1);

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

unshift() добавляет элементы в начало, а push() — в конец.

Частые ошибки

Думать, что unshift() возвращает массив

const numbers = [2, 3];
const result = numbers.unshift(1);

console.log(result); // 3

Здесь result - это новая длина массива, а не [1, 2, 3].

Забывать, что метод меняет массив

const items = ["b", "c"];

items.unshift("a");

После этого items уже содержит новое значение в начале.

Путать добавление элемента и массива

const numbers = [3, 4];

numbers.unshift([1, 2]);

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

Если передать массив, он добавится как один элемент.

Быстрая памятка

unshift() добавляет элементы в начало массива
можно передать один или несколько аргументов
метод меняет исходный массив
unshift() возвращает новую длину массива
если нужен новый массив без изменения старого, чаще используют spread

Коротко

unshift() - это стандартный способ добавить элементы в начало массива в JavaScript. Главное, что стоит запомнить: метод изменяет исходный массив и возвращает его новую длину.