JavaScript unshift Function: How it Works with Examples

The JavaScript unshift function adds one or more elements at the start of an array. It shifts existing items to higher indexes and changes the array length. You need this function when you want new data at the front of a list.

Syntax of the unshift Function in JavaScript

The unshift function is part of the Array object.

Here is the syntax:

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

• array means the target array.
• element1, element2, ..., elementN are new elements you want to add.

The function returns the new length of the array after insertion.

Here is a quick example:

let items = [2, 3, 4]
let newLength = items.unshift(1)
console.log(items)      // [1, 2, 3, 4]
console.log(newLength)  // 4

This array had three numbers, and the unshift function added 1 at the start. It returned 4 because the new array length became four.

Add Multiple Elements with the unshift Function in JavaScript

You can insert many values in one call. Each value appears in the array in the same order you pass.

let fruits = ["mango", "banana"]
fruits.unshift("apple", "orange")
console.log(fruits) // ["apple", "orange", "mango", "banana"]

The array first had two fruits. The unshift function added apple then orange. Both values appeared at the start in the same order.

The unshift function does not return the new array. It returns only the new length after insertion.

let colors = ["blue", "green"]
let length = colors.unshift("red")
console.log(length)  // 3
console.log(colors)  // ["red", "blue", "green"]

The return value is the new length 3. The array itself changed because red was added at index 0.

The Difference Between unshift and push

The unshift function adds values at the start, while the push function adds values at the end.

let numbers = [2, 3]
numbers.unshift(1)
numbers.push(4)
console.log(numbers) // [1, 2, 3, 4]

This function places 1 at the start and the push function puts 4 at the end.

The unshift function can be slower than push. The function must move every existing element to a higher index. So large arrays with many elements can take more time. For small arrays, the difference is not visible.

You can use unshift when:

• You need new items at the front of a list.
• The order of data must keep new items first.
• You want to handle small or medium arrays.

Do not use it when you must handle very large arrays because of the performance cost.

Examples

Add One Element:

let nums = [2, 3, 4]
nums.unshift(1)
console.log(nums) // [1, 2, 3, 4]

This adds 1 at the start of the array and shifts old elements forward.

Add Many Elements:

let fruits = ["mango"]
fruits.unshift("apple", "orange")
console.log(fruits) 

This adds apple and orange at the front of the array. Here is the output:

 ["apple", "orange", "mango"]

Get New Length:

let colors = ["blue"]
let length = colors.unshift("red")
console.log(length) // 2

This example shows 2 in the output because it returns the length after it adds red at index zero.

Wrapping Up

You understood how the unshift function works in JavaScript. Here is a quick recap:

• The JavaScript unshift function adds elements at the start of an array.
• It changes the array and returns the new length.
• You can add one or many values.
• It works best for small arrays when you need fresh data first.

FAQs

let arr = [2, 3]
arr.unshift(1)
console.log(arr) // [1, 2, 3]

let nums = [2, 3]
nums.unshift(1) // [1, 2, 3]
nums.push(4)    // [1, 2, 3, 4]

let colors = ["blue"]
let length = colors.unshift("red")
console.log(length)  // 2
console.log(colors)  // ["red", "blue"]

Similar Reads