W3cubDocs

/JavaScript

Array

The JavaScript Array class is a global object that is used in the construction of arrays; which are high-level, list-like objects.

Description

Arrays are list-like objects whose prototype has methods to perform traversal and mutation operations. Neither the length of a JavaScript array nor the types of its elements are fixed. Since an array's length can change at any time, and data can be stored at non-contiguous locations in the array, JavaScript arrays are not guaranteed to be dense; this depends on how the programmer chooses to use them. In general, these are convenient characteristics; but if these features are not desirable for your particular use, you might consider using typed arrays.

Arrays cannot use strings as element indexes (as in an associative array) but must use integers. Setting or accessing via non-integers using bracket notation (or dot notation) will not set or retrieve an element from the array list itself, but will set or access a variable associated with that array's object property collection. The array's object properties and list of array elements are separate, and the array's traversal and mutation operations cannot be applied to these named properties.

Common operations

Create an Array

let fruits = ['Apple', 'Banana']

console.log(fruits.length)
// 2

Access an Array item using the index position

let first = fruits[0]
// Apple

let last = fruits[fruits.length - 1]
// Banana

Loop over an Array

fruits.forEach(function(item, index, array) {
  console.log(item, index)
})
// Apple 0
// Banana 1

Add an item to the end of an Array

let newLength = fruits.push('Orange')
// ["Apple", "Banana", "Orange"]

Remove an item from the end of an Array

let last = fruits.pop() // remove Orange (from the end)
// ["Apple", "Banana"]

Remove an item from the beginning of an Array

let first = fruits.shift() // remove Apple from the front
// ["Banana"]

Add an item to the beginning of an Array

let newLength = fruits.unshift('Strawberry') // add to the front
// ["Strawberry", "Banana"]

Find the index of an item in the Array

fruits.push('Mango')
// ["Strawberry", "Banana", "Mango"]

let pos = fruits.indexOf('Banana')
// 1

Remove an item by index position

let removedItem = fruits.splice(pos, 1) // this is how to remove an item

// ["Strawberry", "Mango"]

Remove items from an index position

let vegetables = ['Cabbage', 'Turnip', 'Radish', 'Carrot']
console.log(vegetables)
// ["Cabbage", "Turnip", "Radish", "Carrot"]

let pos = 1
let n = 2

let removedItems = vegetables.splice(pos, n)
// this is how to remove items, n defines the number of items to be removed,
// starting at the index position specified by pos and progressing toward the end of array.

console.log(vegetables)
// ["Cabbage", "Carrot"] (the original array is changed)

console.log(removedItems)
// ["Turnip", "Radish"]

Copy an Array

let shallowCopy = fruits.slice() // this is how to make a copy
// ["Strawberry", "Mango"]

Accessing array elements

JavaScript arrays are zero-indexed. The first element of an array is at index 0, and the last element is at the index value equal to the value of the array's length property minus 1.

Using an invalid index number returns undefined.

let arr = ['this is the first element', 'this is the second element', 'this is the last element']
console.log(arr[0])              // logs 'this is the first element'
console.log(arr[1])              // logs 'this is the second element'
console.log(arr[arr.length - 1]) // logs 'this is the last element'

Array elements are object properties in the same way that toString is a property (to be specific, however, toString() is a method). Nevertheless, trying to access an element of an array as follows throws a syntax error because the property name is not valid:

console.log(arr.0) // a syntax error

There is nothing special about JavaScript arrays and the properties that cause this. JavaScript properties that begin with a digit cannot be referenced with dot notation and must be accessed using bracket notation.

For example, if you had an object with a property named 3d, it can only be referenced using bracket notation.

let years = [1950, 1960, 1970, 1980, 1990, 2000, 2010]
console.log(years.0)   // a syntax error
console.log(years[0])  // works properly
renderer.3d.setTexture(model, 'character.png')     // a syntax error
renderer['3d'].setTexture(model, 'character.png')  // works properly

In the 3d example, '3d' had to be quoted (because it begins with a digit). But it's also possible to quote the array indexes as well (e.g., years['2'] instead of years[2]), although it's not necessary.

The 2 in years[2] is coerced into a string by the JavaScript engine through an implicit toString conversion. As a result, '2' and '02' would refer to two different slots on the years object, and the following example could be true:

console.log(years['2'] != years['02'])

Relationship between length and numerical properties

A JavaScript array's length property and numerical properties are connected.

Several of the built-in array methods (e.g., join(), slice(), indexOf(), etc.) take into account the value of an array's length property when they're called.

Other methods (e.g., push(), splice(), etc.) also result in updates to an array's length property.

const fruits = []
fruits.push('banana', 'apple', 'peach')

console.log(fruits.length) // 3

When setting a property on a JavaScript array when the property is a valid array index and that index is outside the current bounds of the array, the engine will update the array's length property accordingly:

fruits[5] = 'mango'
console.log(fruits[5])            // 'mango'
console.log(Object.keys(fruits))  // ['0', '1', '2', '5']
console.log(fruits.length)        // 6

Increasing the length.

fruits.length = 10
console.log(fruits)              // ['banana', 'apple', 'peach', empty x 2, 'mango', empty x 4]
console.log(Object.keys(fruits)) // ['0', '1', '2', '5']
console.log(fruits.length)       // 10
console.log(fruits[8])           // undefined

Decreasing the length property does, however, delete elements.

fruits.length = 2
console.log(Object.keys(fruits)) // ['0', '1']
console.log(fruits.length)       // 2

This is explained further on the Array.length page.

Creating an array using the result of a match

The result of a match between a RegExp and a string can create a JavaScript array. This array has properties and elements which provide information about the match. Such an array is returned by RegExp.exec(), String.match(), and String.replace().

To help explain these properties and elements, see this example and then refer to the table below:

// Match one d followed by one or more b's followed by one d
// Remember matched b's and the following d
// Ignore case

const myRe = /d(b+)(d)/i
const myArray = myRe.exec('cdbBdbsbz')

The properties and elements returned from this match are as follows:

Property/Element Description Example
input
Read only
The original string against which the regular expression was matched. "cdbBdbsbz"
index
Read only
The zero-based index of the match in the string. 1
[0]
Read only
The last matched characters. "dbBd"
[1], ...[n]
Read only
Elements that specify the parenthesized substring matches (if included) in the regular expression. The number of possible parenthesized substrings is unlimited. [1]: "bB"
[2]: "d"

Constructor

Array()
Creates a new Array object.

Static properties

get Array[@@species]
The constructor function is used to create derived objects.

Static methods

Array.from()
Creates a new Array instance from an array-like or iterable object.
Array.isArray()
Returns true if the argument is an array, or false otherwise.
Array.of()
Creates a new Array instance with a variable number of arguments, regardless of number or type of the arguments.

Instance properties

Array.prototype.length
Reflects the number of elements in an array.
Array.prototype[@@unscopables]
A symbol containing property names to exclude from a with binding scope.

Instance methods

Array.prototype.concat()
Returns a new array that is this array joined with other array(s) and/or value(s).
Array.prototype.copyWithin()
Copies a sequence of array elements within the array.
Array.prototype.entries()
Returns a new Array Iterator object that contains the key/value pairs for each index in the array.
Array.prototype.every()
Returns true if every element in this array satisfies the testing function.
Array.prototype.fill()
Fills all the elements of an array from a start index to an end index with a static value.
Array.prototype.filter()
Returns a new array containing all elements of the calling array for which the provided filtering function returns true.
Array.prototype.find()
Returns the found element in the array, if some element in the array satisfies the testing function, or undefined if not found.
Array.prototype.findIndex()
Returns the found index in the array, if an element in the array satisfies the testing function, or -1 if not found.
Array.prototype.forEach()
Calls a function for each element in the array.
Array.prototype.includes()
Determines whether the array contains a value, returning true or false as appropriate.
Array.prototype.indexOf()
Returns the first (least) index of an element within the array equal to an element, or -1 if none is found.
Array.prototype.join()
Joins all elements of an array into a string.
Array.prototype.keys()
Returns a new Array Iterator that contains the keys for each index in the array.
Array.prototype.lastIndexOf()
Returns the last (greatest) index of an element within the array equal to an element, or -1 if none is found.
Array.prototype.map()
Returns a new array containing the results of calling a function on every element in this array.
Array.prototype.pop()
Removes the last element from an array and returns that element.
Array.prototype.push()
Adds one or more elements to the end of an array, and returns the new length of the array.
Array.prototype.reduce()
Apply a function against an accumulator and each value of the array (from left-to-right) as to reduce it to a single value.
Array.prototype.reduceRight()
Apply a function against an accumulator> and each value of the array (from right-to-left) as to reduce it to a single value.
Array.prototype.reverse()
Reverses the order of the elements of an array in place. (First becomes the last, last becomes first.)
Array.prototype.shift()
Removes the first element from an array and returns that element.
Array.prototype.slice()
Extracts a section of the calling array and returns a new array.
Array.prototype.some()
Returns true if at least one element in this array satisfies the provided testing function.
Array.prototype.sort()
Sorts the elements of an array in place and returns the array.
Array.prototype.splice()
Adds and/or removes elements from an array.
Array.prototype.toLocaleString()
Returns a localized string representing the array and its elements. Overrides the Object.prototype.toLocaleString() method.
Array.prototype.toString()
Returns a string representing the array and its elements. Overrides the Object.prototype.toString() method.
Array.prototype.unshift()
Adds one or more elements to the front of an array, and returns the new length of the array.
Array.prototype.values()
Returns a new Array Iterator object that contains the values for each index in the array.
Array.prototype[@@iterator]()
Returns a new Array Iterator object that contains the values for each index in the array.

Examples

Creating an array

The following example creates an array, msgArray, with a length of 0, then assigns values to msgArray[0] and msgArray[99], changing the length of the array to 100.

let msgArray = []
msgArray[0] = 'Hello'
msgArray[99] = 'world'

if (msgArray.length === 100) {
  console.log('The length is 100.')
}

Creating a two-dimensional array

The following creates a chessboard as a two-dimensional array of strings. The first move is made by copying the 'p' in board[6][4] to board[4][4]. The old position at [6][4] is made blank.

let board = [ 
  ['R','N','B','Q','K','B','N','R'],
  ['P','P','P','P','P','P','P','P'],
  [' ',' ',' ',' ',' ',' ',' ',' '],
  [' ',' ',' ',' ',' ',' ',' ',' '],
  [' ',' ',' ',' ',' ',' ',' ',' '],
  [' ',' ',' ',' ',' ',' ',' ',' '],
  ['p','p','p','p','p','p','p','p'],
  ['r','n','b','q','k','b','n','r'] ]

console.log(board.join('\n') + '\n\n')

// Move King's Pawn forward 2
board[4][4] = board[6][4]
board[6][4] = ' '
console.log(board.join('\n'))

Here is the output:

R,N,B,Q,K,B,N,R
P,P,P,P,P,P,P,P
 , , , , , , , 
 , , , , , , , 
 , , , , , , , 
 , , , , , , , 
p,p,p,p,p,p,p,p
r,n,b,q,k,b,n,r

R,N,B,Q,K,B,N,R
P,P,P,P,P,P,P,P
 , , , , , , , 
 , , , , , , , 
 , , , ,p, , , 
 , , , , , , , 
p,p,p,p, ,p,p,p
r,n,b,q,k,b,n,r

Using an array to tabulate a set of values

values = []
for (let x = 0; x < 10; x++){
 values.push([
  2 ** x,
  2 * x ** 2
 ])
}
console.table(values)

Results in

// The first column is the index
0	1	0
1	2	2
2	4	8
3	8	18
4	16	32
5	32	50
6	64	72
7	128	98
8	256	128
9	512	162

Specifications

Specification Initial publication
ECMAScript (ECMA-262)
The definition of 'Array' in that specification.
ECMAScript 1

Browser compatibilityUpdate compatibility data on GitHub

Desktop
Chrome Edge Firefox Internet Explorer Opera Safari
Array 1 12 1 4 4 1
Array() constructor 1 12 1 4 4 1
concat 1 12 1 5.5 4 1
copyWithin 45 12 32 No 32 9
entries 38 12 28 No 25 8
every 1 12 1.5 9 9.5 3
fill 45 12 31 No 32 8
filter 1 12 1.5 9 9.5 3
find 45 12 25 No 32 8
findIndex 45 12 25 No 32 8
flat 69 79 62 No 56 12
flatMap 69 79 62 No 56 12
forEach 1 12 1.5 9 9.5 3
from 45 12 32 No 32 9
includes 47 14 43 No 34 9
indexOf 1 12 1.5 9 9.5 3
isArray 5 12 4 9 10.5 5
join 1 12 1 5.5 4 1
keys 38 12 28 No 25 8
lastIndexOf 1 12 1.5 9 9.5 3
length 1 12 1 4 4 1
map 1 12 1.5 9 9.5 3
of 45 12 25 No 26 9
pop 1 12 1 5.5 4 1
push 1 12 1 5.5 4 1
reduce 3 12 3 9 10.5 5
reduceRight 3 12 3 9 10.5 5
reverse 1 12 1 5.5 4 1
shift 1 12 1 5.5 4 1
slice 1 12 1 4 4 1
some 1 12 1.5 9 9.5 3
sort 1 12 1 5.5 4 1
splice 1 12 1 5.5
5.5
From Internet Explorer 5.5 through 8, all elements of the array will not be deleted if deleteCount is omitted. This behavior was fixed in Internet Explorer 9.
4 1
toLocaleString 1 12 1 5.5 4 1
toSource No No 1 — 74
1 — 74
Starting in Firefox 74, toSource() is no longer available for use by web content. It is still allowed for internal and privileged code.
No No No
toString 1 12 1 4 4 1
unshift 1 12 1 5.5 4 1
values 66 12 60 No 53 9
@@iterator 38 12 36
36
27 — 36
A placeholder property named @@iterator is used.
Uses the non-standard name: @@iterator
17 — 27
A placeholder property named iterator is used.
Uses the non-standard name: iterator
No 25 10
@@species 51 79 48 No 38 10
@@unscopables 38 12 48 No 25 10
Mobile
Android webview Chrome for Android Firefox for Android Opera for Android Safari on iOS Samsung Internet
Array ≤37 18 4 10.1 1 1.0
Array() constructor ≤37 18 4 10.1 1 1.0
concat 1 18 4 10.1 1 1.0
copyWithin 45 45 32 32 9 5.0
entries 38 38 28 25 8 3.0
every ≤37 18 4 10.1 1 1.0
fill 45 45 31 32 8 5.0
filter ≤37 18 4 10.1 1 1.0
find 45 45 4 32 8 5.0
findIndex 45 45 4 32 8 5.0
flat 69 69 62 48 12 10.0
flatMap 69 69 62 48 12 10.0
forEach ≤37 18 4 10.1 1 1.0
from 45 45 32 32 9 5.0
includes 47 47 43 34 9 5.0
indexOf ≤37 18 4 10.1 1 1.0
isArray 1 18 4 14 5 1.0
join 1 18 4 10.1 1 1.0
keys 38 38 28 25 8 3.0
lastIndexOf ≤37 18 4 10.1 1 1.0
length ≤37 18 4 10.1 1 1.0
map ≤37 18 4 10.1 1 1.0
of 39 39 25 26 9 4.0
pop 1 18 4 10.1 1 1.0
push 1 18 4 10.1 1 1.0
reduce ≤37 18 4 14 4 1.0
reduceRight ≤37 18 4 14 4 1.0
reverse 1 18 4 10.1 1 1.0
shift 1 18 4 10.1 1 1.0
slice 1 18 4 10.1 1 1.0
some ≤37 18 4 10.1 1 1.0
sort 1 18 4 10.1 1 1.0
splice 1 18 4 10.1 1 1.0
toLocaleString ≤37 18 4 10.1 1 1.0
toSource No No 4 No No No
toString ≤37 18 4 10.1 1 1.0
unshift 1 18 4 10.1 1 1.0
values 66 66 60 47 9 9.0
@@iterator 38 38 36
36
27 — 36
A placeholder property named @@iterator is used.
Uses the non-standard name: @@iterator
17 — 27
A placeholder property named iterator is used.
Uses the non-standard name: iterator
25 10 3.0
@@species 51 51 48 41 10 5.0
@@unscopables 38 38 48 25 10 3.0
Server
Node.js
Array 0.1.100
Array() constructor 0.1.100
concat 0.1.100
copyWithin 4.0.0
entries 0.12
every 0.1.100
fill 4.0.0
4.0.0
0.12
Disabled
Disabled From version 0.12: this feature is behind the --harmony runtime flag.
filter 0.1.100
find 4.0.0
4.0.0
0.12
Disabled
Disabled From version 0.12: this feature is behind the --harmony runtime flag.
findIndex 4.0.0
4.0.0
0.12
Disabled
Disabled From version 0.12: this feature is behind the --harmony runtime flag.
flat 11.0.0
flatMap 11.0.0
forEach 0.1.100
from 4.0.0
includes 6.0.0
6.0.0
5.0.0
Disabled
Disabled From version 5.0.0: this feature is behind the --harmony runtime flag.
indexOf 0.1.100
isArray 0.1.100
join 0.1.100
keys 0.12
lastIndexOf 0.1.100
length 0.1.100
map 0.1.100
of 4.0.0
pop 0.1.100
push 0.1.100
reduce 0.1.100
reduceRight 0.1.100
reverse 0.1.100
shift 0.1.100
slice 0.1.100
some 0.1.100
sort 0.1.100
splice 0.1.100
toLocaleString 0.1.100
toSource No
toString 0.1.100
unshift 0.1.100
values 10.9.0
10.9.0
6.5.0
Disabled
The --harmony-array-prototype-values flag is required; the --harmony flag is not sufficient in this case.
Disabled From version 6.5.0: this feature is behind the --harmony-array-prototype-values runtime flag.
0.12 — 4.0.0
@@iterator 0.12
@@species 6.5.0
6.5.0
6.0.0
Disabled
Disabled From version 6.0.0: this feature is behind the --harmony runtime flag.
@@unscopables 0.12

See also

© 2005–2018 Mozilla Developer Network and individual contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array