JavaScript reference

    A deep dive into Array.unshift().

    The unshift method adds one or more elements to the beginning of an array and returns the new length. Here is everything you need to know.

    The basics

    Understanding unshift.

    The unshift method inserts elements at the start of an array and returns the new length. It directly modifies the array, which distinguishes it from methods that do not alter the array's original structure.

    Syntax

    Syntax and parameters.

    The method accepts multiple parameters, which are the elements that you want to add to the array. You can pass one or several elements separated by commas.

    Return value

    Return value and side effects.

    Besides returning the new length of the array, unshift modifies the array in place. This is a critical consideration when managing array states in applications, especially in React where immutability is often preferred.

    Use cases

    Multiple examples and use cases.

    • Prepending items to a list of elements, for example adding new logs at the top of a log file display.
    • Using unshift for queue operations where new tasks are added to the front.
    • Combining unshift with pop to rotate elements in the array.
    Try it

    Interactive example: unshift in action.

    Enter numbers separated by commas to add to the beginning of the array.

    Advanced

    Calling unshift on non-array objects.

    Typically, unshift is a method designed for arrays. However, it can be applied to objects that mimic arrays: objects with indexed properties and a length property.

    This example shows how the unshift method can be coerced to work with non-traditional objects by explicitly setting the context with call. It manipulates the object by adding a new indexed property at the beginning, shifting the existing ones, and updating the length property.

    Note: Using unshift on non-array objects is not standard practice and can lead to unusual bugs and maintenance challenges. Use with caution, and only when traditional data structures and their methods are insufficient.

    Performance

    Advanced scenarios and performance.

    While unshift is convenient, it can lead to performance issues in high-complexity applications, particularly with large arrays, as it has to reindex all elements. For performance-critical applications, alternative data structures like linked lists or using arrays more judiciously may be advisable.

    • Using unshift on arrays with thousands of elements can significantly impact performance.
    • Alternative strategies might involve using different data structures or avoiding frequent reindexing of large arrays.
    Browser support

    Works everywhere.

    The JavaScript unshift method enjoys widespread support across all major browsers, making it a dependable option for front-end development.

    Browser
    Supported versions
    Google Chrome
    Since version 1
    Mozilla Firefox
    Since version 1
    Safari
    Since version 1
    Opera
    Since version 5
    Microsoft Edge
    All versions
    Internet Explorer
    Since version 5.5
    Chrome for Android
    Supported
    Firefox for Android
    Supported
    Safari on iOS
    Supported
    Samsung Internet
    Supported