Map
FromThe Map
object holds key-value pairs and remembers the original insertion order of the keys. Any value (both objects and ) may be used as either a key or a value.
A Map
object iterates its elements in insertion order — a loop returns an array of [key, value]
for each iteration.
Key equality
- Key equality is based on the algorithm.
- is considered the same as
NaN
(even thoughNaN !== NaN
) and all other values are considered equal according to the semantics of the===
operator. - In the current ECMAScript specification,
-0
and+0
are considered equal, although this was not so in earlier drafts. See "Value equality for -0 and 0" in the table for details.
Objects vs. Maps
is similar to Map
—both let you set keys to values, retrieve those values, delete keys, and detect whether something is stored at a key. For this reason (and because there were no built-in alternatives), Object
s have been used as Map
s historically.
However, there are important differences that make Map
preferable in certain cases:
Map
does not contain any keys by default. It only contains what is explicitly put into it. An Object
has a prototype, so it contains default keys that could collide with your own keys if you're not careful.
Map
's keys can be any value (including functions, objects, or any primitive). The keys of an Object
must be either a or a . Key Order The keys in Map
are ordered. Thus, when iterating over it, a Map
object returns keys in order of insertion.
The keys of an Object
are not ordered.
Note: Since ECMAScript 2015, objects do preserve creation order for string and Symbol
keys. In JavaScript engines that comply with the ECMAScript 2015 spec, iterating over an object with only string keys will yield the keys in order of insertion.
Map
is easily retrieved from its property. The number of items in an Object
must be determined manually. Iteration A Map
is an , so it can be directly iterated. Iterating over an Object
requires obtaining its keys in some fashion and iterating over them. Performance Performs better in scenarios involving frequent additions and removals of key-value pairs.
Not optimized for frequent additions and removals of key-value pairs.
Setting object properties
Setting Object properties works for Map objects as well, and can cause considerable confusion.
Therefore, this still sort-of works....
let wrongMap = new Map() wrongMap['bla'] = 'blaa' wrongMap['bla2'] = 'blaaa2' console.log(wrongMap) // Map { bla: 'blaa', bla2: 'blaaa2' }
...But, it does not behave as expected:
wrongMap.has('bla') // false wrongMap.delete('bla') // false console.log(wrongMap) // Map { bla: 'blaa', bla2: 'blaaa2' }
And there's very little difference from the correct usage, anyway:
let myMap = new Map() myMap.set('bla','blaa') myMap.set('bla2','blaa2') console.log(myMap) // Map { 'bla' => 'blaa', 'bla2' => 'blaa2' } myMap.has('bla') // true myMap.delete('bla') // true console.log(myMap) // Map { 'bla2' => 'blaa2' }Constructor Creates a new
Map
object.Static properties The constructor function that is used to create derived objects.
Instance properties Returns the number of key/value pairs in the
Map
object.Instance methods Removes all key-value pairs from the
Map
object. Returns true
if an element in the Map
object existed and has been removed, or false
if the element does not exist. Map.prototype.has(key)
will return false
afterwards. Returns a new Iterator
object that contains an array of [key, value]
for each element in the Map
object in insertion order. Calls callbackFn
once for each key-value pair present in the Map
object, in insertion order. If a thisArg
parameter is provided to forEach
, it will be used as the this
value for each callback. Returns the value associated to the key
, or undefined
if there is none. Returns a boolean asserting whether a value has been associated to the key
in the Map
object or not. Returns a new Iterator
object that contains the keys for each element in the Map
object in insertion order. Sets the value
for the key
in the Map
object. Returns the Map
object. Returns a new Iterator
object that contains the values for each element in the Map
object in insertion order. Returns a new Iterator
object that contains an array of [key, value]
for each element in the Map
object in insertion order.Examples
Using the Map
object
let myMap = new Map() let keyString = 'a string' let keyObj = {} let keyFunc = function() {} // setting the values myMap.set(keyString, "value associated with 'a string'") myMap.set(keyObj, 'value associated with keyObj') myMap.set(keyFunc, 'value associated with keyFunc') myMap.size // 3 // getting the values myMap.get(keyString) // "value associated with 'a string'" myMap.get(keyObj) // "value associated with keyObj" myMap.get(keyFunc) // "value associated with keyFunc" myMap.get('a string') // "value associated with 'a string'" // because keyString === 'a string' myMap.get({}) // undefined, because keyObj !== {} myMap.get(function() {}) // undefined, because keyFunc !== function () {}
Using NaN
as Map
keys
can also be used as a key. Even though every NaN
is not equal to itself (NaN !== NaN
is true), the following example works because NaN
s are indistinguishable from each other:
let myMap = new Map() myMap.set(NaN, 'not a number') myMap.get(NaN) // "not a number" let otherNaN = Number('foo') myMap.get(otherNaN) // "not a number"
Iterating Map
with for..of
Maps can be iterated using a for..of
loop:
let myMap = new Map() myMap.set(0, 'zero') myMap.set(1, 'one') for (let [key, value] of myMap) { console.log(key + ' = ' + value) } // 0 = zero // 1 = one for (let key of myMap.keys()) { console.log(key) } // 0 // 1 for (let value of myMap.values()) { console.log(value) } // zero // one for (let [key, value] of myMap.entries()) { console.log(key + ' = ' + value) } // 0 = zero // 1 = one
Iterating Map
with forEach()
Maps can be iterated using the method:
myMap.forEach(function(value, key) { console.log(key + ' = ' + value) }) // 0 = zero // 1 = one
Relation with Array objects
let kvArray = [['key1', 'value1'], ['key2', 'value2']] // Use the regular Map constructor to transform a 2D key-value Array into a map let myMap = new Map(kvArray) myMap.get('key1') // returns "value1" // Use Array.from() to transform a map into a 2D key-value Array console.log(Array.from(myMap)) // Will show you exactly the same Array as kvArray // A succinct way to do the same, using the spread syntax console.log([...myMap]) // Or use the keys() or values() iterators, and convert them to an array console.log(Array.from(myMap.keys())) // ["key1", "key2"]
Cloning and merging Map
s
Just like Array
s, Map
s can be cloned:
let original = new Map([ [1, 'one'] ]) let clone = new Map(original) console.log(clone.get(1)) // one console.log(original === clone) // false (useful for shallow comparison)
Important: Keep in mind that the data itself is not cloned.
Maps can be merged, maintaining key uniqueness:
let first = new Map([ [1, 'one'], [2, 'two'], [3, 'three'], ]) let second = new Map([ [1, 'uno'], [2, 'dos'] ]) // Merge two maps. The last repeated key wins. // Spread operator essentially converts a Map to an Array let merged = new Map([...first, ...second]) console.log(merged.get(1)) // uno console.log(merged.get(2)) // dos console.log(merged.get(3)) // three
Maps can be merged with Arrays, too:
let first = new Map([ [1, 'one'], [2, 'two'], [3, 'three'], ]) let second = new Map([ [1, 'uno'], [2, 'dos'] ]) // Merge maps with an array. The last repeated key wins. let merged = new Map([...first, ...second, [1, 'eins']]) console.log(merged.get(1)) // eins console.log(merged.get(2)) // dos console.log(merged.get(3)) // threeSpecifications Browser compatibility DesktopMobileServerChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
Map
Chrome Full support 38Edge Full support 12Firefox Full support 13IE Full support 11Opera Full support 25Safari Full support 8WebView Android Full support 38Chrome Android Full support 38Firefox Android Full support 14Opera Android Full support 25Safari iOS Full support 8Samsung Internet Android Full support 3.0nodejs Full support 0.12 Full support 0.12 Full support 0.10Disabled From version 0.10: this feature is behind the --harmony
runtime flag.Chrome Full support 38Edge Full support 12Firefox Full support 13IE Full support 11Opera Full support 25Safari Full support 8WebView Android Full support 38Chrome Android Full support 38Firefox Android Full support 14Opera Android Full support 25Safari iOS Full support 8Samsung Internet Android Full support 3.0nodejs Full support YesChrome Full support 38Edge Full support 12Firefox Full support 19IE Full support 11Opera Full support 25Safari Full support 8WebView Android Full support 38Chrome Android Full support 38Firefox Android Full support 19Opera Android Full support 25Safari iOS Full support 8Samsung Internet Android Full support 3.0nodejs Full support 0.12Chrome Full support 38Edge Full support 12Firefox Full support 13IE Full support 11Opera Full support 25Safari Full support 8WebView Android Full support 38Chrome Android Full support 38Firefox Android Full support 14Opera Android Full support 25Safari iOS Full support 8Samsung Internet Android Full support 3.0nodejs Full support 0.12 Full support 0.12 Full support 0.10Disabled From version 0.10: this feature is behind the --harmony
runtime flag.Chrome Full support 38Edge Full support 12Firefox Full support 20IE No support NoOpera Full support 25Safari Full support 8WebView Android Full support 38Chrome Android Full support 38Firefox Android Full support 20Opera Android Full support 25Safari iOS Full support 8Samsung Internet Android Full support 3.0nodejs Full support 0.12Chrome Full support 38Edge Full support 12Firefox Full support 25IE Full support 11Opera Full support 25Safari Full support 8WebView Android Full support 38Chrome Android Full support 38Firefox Android Full support 25Opera Android Full support 25Safari iOS Full support 8Samsung Internet Android Full support 3.0nodejs Full support 0.12Chrome Full support 38Edge Full support 12Firefox Full support 13IE Full support 11Opera Full support 25Safari Full support 8WebView Android Full support 38Chrome Android Full support 38Firefox Android Full support 14Opera Android Full support 25Safari iOS Full support 8Samsung Internet Android Full support 3.0nodejs Full support YesChrome Full support 38Edge Full support 12Firefox Full support 13IE Full support 11Opera Full support 25Safari Full support 8WebView Android Full support 38Chrome Android Full support 38Firefox Android Full support 14Opera Android Full support 25Safari iOS Full support 8Samsung Internet Android Full support 3.0nodejs Full support YesKey equality for -0 and 0Chrome Full support 38Edge Full support 12Firefox Full support 29IE No support NoOpera Full support 25Safari Full support 9WebView Android Full support 38Chrome Android Full support 38Firefox Android Full support 29Opera Android Full support 25Safari iOS Full support 9Samsung Internet Android Full support 3.0nodejs Full support 4.0.0Chrome Full support 38Edge Full support 12Firefox Full support 20IE No support NoOpera Full support 25Safari Full support 8WebView Android Full support 38Chrome Android Full support 38Firefox Android Full support 20Opera Android Full support 25Safari iOS Full support 8Samsung Internet Android Full support 3.0nodejs Full support 0.12Chrome Full support 38Edge Full support 12Firefox Full support 13IE Partial support 11 Partial support 11Notes Returns 'undefined' instead of the 'Map' object.Opera Full support 25Safari Full support 8WebView Android Full support 38Chrome Android Full support 38Firefox Android Full support 14Opera Android Full support 25Safari iOS Full support 8Samsung Internet Android Full support 3.0nodejs Full support YesChrome Full support 38Edge Full support 12Firefox Full support 19 Full support 19Notes From Firefox 13 to Firefox 18, the size
property was implemented as a Map.prototype.size()
method, this has been changed to a property in later versions conform to the ECMAScript 2015 specification.IE Full support 11Opera Full support 25Safari Full support 8WebView Android Full support 38Chrome Android Full support 38Firefox Android Full support 19 Full support 19Notes From Firefox 13 to Firefox 18, the size
property was implemented as a Map.prototype.size()
method, this has been changed to a property in later versions conform to the ECMAScript 2015 specification.Opera Android Full support 25Safari iOS Full support 8Samsung Internet Android Full support 3.0nodejs Full support 0.12Chrome Full support 38Edge Full support 12Firefox Full support 20IE No support NoOpera Full support 25Safari Full support 8WebView Android Full support 38Chrome Android Full support 38Firefox Android Full support 20Opera Android Full support 25Safari iOS Full support 8Samsung Internet Android Full support 3.0nodejs Full support 0.12Chrome Full support 43Edge Full support 12Firefox Full support 36 Full support 36 No support 27 — 36Notes A placeholder property named @@iterator
is used.Alternate Name Uses the non-standard name: @@iterator
No support 17 — 27Notes A placeholder property named iterator
is used.Alternate Name Uses the non-standard name: iterator
IE No support NoOpera Full support 30Safari Full support 10WebView Android Full support 43Chrome Android Full support 43Firefox Android Full support 36 Full support 36 No support 27 — 36Notes A placeholder property named @@iterator
is used.Alternate Name Uses the non-standard name: @@iterator
No support 17 — 27Notes A placeholder property named iterator
is used.Alternate Name Uses the non-standard name: iterator
Opera Android Full support 30Safari iOS Full support 10Samsung Internet Android Full support 4.0nodejs Full support 0.12Chrome Full support 51Edge Full support 13Firefox Full support 41IE No support NoOpera Full support 38Safari Full support 10WebView Android Full support 51Chrome Android Full support 51Firefox Android Full support 41Opera Android Full support 41Safari iOS Full support 10Samsung Internet Android Full support 5.0nodejs Full support 6.5.0 Full support 6.5.0 Full support 6.0.0Disabled From version 6.0.0: this feature is behind the --harmony
runtime flag.Chrome Full support 44Edge Full support 79Firefox Full support 51IE No support NoOpera No support NoSafari No support NoWebView Android Full support 44Chrome Android Full support 44Firefox Android Full support 51Opera Android No support NoSafari iOS No support NoSamsung Internet Android Full support 4.0nodejs No support No Full support Full support Partial support Partial support No support No supportSee implementation notes.See implementation notes.User must explicitly enable this feature.User must explicitly enable this feature.Uses a non-standard name.Uses a non-standard name. See also