--- title: Map slug: Web/JavaScript/Reference/Global_Objects/Map tags: - ECMAScript 2015 - JavaScript - Map - NeedsTranslation - TopicStub translation_of: Web/JavaScript/Reference/Global_Objects/Map ---
{{JSRef}}

The Map object holds key-value pairs. Any value (both objects and {{Glossary("Primitive", "primitive values")}}) may be used as either a key or a value.

Syntax

new Map([iterable])

Parameters

iterable
An {{jsxref("Array")}} or other iterable object whose elements are key-value pairs (arrays with two elements, e.g. [[ 1, 'one' ],[ 2, 'two' ]]). Each key-value pair is added to the new Map; null values are treated as undefined.

Description

A Map object iterates its elements in insertion order — a {{jsxref("Statements/for...of", "for...of")}} loop returns an array of [key, value] for each iteration.

It should be noted that a Map which is a map of an object, especially a dictionary of dictionaries, will only map to the object's insertion order—which is random and not ordered.

Key equality

Key equality is based on the "SameValueZero" algorithm: NaN is considered the same as NaN (even though NaN !== 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 browser compatibility table for details.

Objects and maps compared

{{jsxref("Object", "Objects")}} are similar to Maps in that both let you set keys to values, retrieve those values, delete keys, and detect whether something is stored at a key. Because of this (and because there were no built-in alternatives), Objects have been used as Maps historically; however, there are important differences that make using a Map preferable in certain cases:

Properties

Map.length
The value of the length property is 0.
{{jsxref("Map.@@species", "get Map[@@species]")}}
The constructor function that is used to create derived objects.
{{jsxref("Map.prototype")}}
Represents the prototype for the Map constructor. Allows the addition of properties to all Map objects.

Map instances

All Map instances inherit from {{jsxref("Map.prototype")}}.

Properties

{{page('en-US/Web/JavaScript/Reference/Global_Objects/Map/prototype','Properties')}}

Methods

{{page('en-US/Web/JavaScript/Reference/Global_Objects/Map/prototype','Methods')}}

Examples

Using the Map object

var myMap = new Map();

var keyString = 'a string',
    keyObj = {},
    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

NaN 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 NaNs are indistinguishable from each other:

var myMap = new Map();
myMap.set(NaN, 'not a number');

myMap.get(NaN); // "not a number"

var otherNaN = Number('foo');
myMap.get(otherNaN); // "not a number"

Iterating Maps with for..of

Maps can be iterated using a for..of loop:

var myMap = new Map();
myMap.set(0, 'zero');
myMap.set(1, 'one');
for (var [key, value] of myMap) {
  console.log(key + ' = ' + value);
}
// 0 = zero
// 1 = one

for (var key of myMap.keys()) {
  console.log(key);
}
// 0
// 1

for (var value of myMap.values()) {
  console.log(value);
}
// zero
// one

for (var [key, value] of myMap.entries()) {
  console.log(key + ' = ' + value);
}
// 0 = zero
// 1 = one

Iterating Maps with forEach()

Maps can be iterated using the forEach() method:

myMap.forEach(function(value, key) {
  console.log(key + ' = ' + value);
});
// Will show 2 logs; first with "0 = zero" and second with "1 = one"

Relation with Array objects

var kvArray = [['key1', 'value1'], ['key2', 'value2']];

// Use the regular Map constructor to transform a 2D key-value Array into a map
var myMap = new Map(kvArray);

myMap.get('key1'); // returns "value1"

// Use the Array.from function to transform a map into a 2D key-value Array
console.log(Array.from(myMap)); // Will show you exactly the same Array as kvArray

// Or use the keys or values iterators and convert them to an array
console.log(Array.from(myMap.keys())); // Will show ["key1", "key2"]

Specifications

Specification Status Comment
{{SpecName('ES2015', '#sec-map-objects', 'Map')}} {{Spec2('ES2015')}} Initial definition.
{{SpecName('ESDraft', '#sec-map-objects', 'Map')}} {{Spec2('ESDraft')}}  

Browser compatibility

{{Compat("javascript.builtins.Map")}}

See also