Array.unshift()

The JavaScript Array.unshift() method, which is very similar to the Array.push() method, allows you to add one or more items to the start of an Array and will subsequently return the new length property of the Array.

Syntax

arr.unshift(item1[, item n, ...])

Email Inbox Example 📨

In a typical email inbox, the most recent emails that are received appear at the top thus moving the older emails to the bottom.

Using Array.unshift() we can simulate an email inbox of our own!

Let's Try It Out 📬

First we will create an array named inbox and we will add a few emails into it. Let's use Objects to simulate the emails.

var inbox = [
    { subject: 'CodeSnippet - Array.pop()', received: '11:41am', status: 'unread' },
    { subject: 'Quora - JavaScript in 2018', received: '8:27am', status: 'unread' },
    { subject: 'YCombinator - Before You Grow', received: '8:11am', status: 'unread' }
];

console.log(inbox);

Try this the code snippet in your browser console.

Sweet - so now we have 3 emails in our inbox, and we can see that the most recent email, which was received at 11:41am, is all the way at the top.

Receiving Another Email 📩

Now let's imagine that we receive another email. As we know, with the way our inbox is configured, the newest emails should appear at the top. We can simulate this by using Array.unshift().

var inbox = [
    { subject: 'CodeSnippet - Array.pop()', received: '11:41am', status: 'unread' },
    { subject: 'Quora - JavaScript in 2018', received: '8:27am', status: 'unread' },
    { subject: 'YCombinator - Before You Grow', received: '8:11am', status: 'unread' }
];

inbox.unshift({ subject: 'Your Hacktoberfest 2018 Prize', received: '12:06pm', status: 'unread' }) // returns 4 - the new length of inbox

console.log(inbox);

Try this the code snippet in your browser console.

Using Array.unshift() with Multiple Items

We can add multiple items to our inbox array the same we were able to add that new email to the top of our inbox. We just need to separate each new item with a comma. The first item passed into the argument will be at the top of the inbox, or the beginning of the Array for that matter.

var inbox = [
    { subject: 'Your Hacktoberfest 2018 Prize', received: '12:06pm', status: 'unread' },
    { subject: 'CodeSnippet - Array.pop()', received: '11:41am', status: 'unread' },
    { subject: 'Quora - JavaScript in 2018', received: '8:27am', status: 'unread' },
    { subject: 'YCombinator - Before You Grow', received: '8:11am', status: 'unread' }
];

inbox.unshift(
    { subject: 'TechCrunch - Hottest Startups of the Year', received: '12:21pm', status: 'unread' },
    { subject: 'Re: Great Meeting Your Team', received: '12:19pm', status: 'unread' }
);

// returns 6 - the new length of inbox

console.log(inbox);

Combining With Other Array Methods 🤝

You could definitely start to play around with our inbox example and even use other Array methods such as Array.shift(), Array.push(), and even Array.pop() among other handy JavaScript Array methods.

Wrapping Up 📝

As you can see, the Array.unshift() method is a really handy tool when you need to add one or more elements to the beginning of an Array.

Stay Tuned 📺

If you have any questions or improvements, or if you'd like to see additional examples, feel free to reach out to me anytime at tim@timwheeler.com. If you're enjoying my posts, please subscribe below! 👇