new Map()
Creates a keyed collection where any value can be a key and insertion order is preserved.
new Map()
new Map(iterable)- Added in JavaScript ES2015
Parameters
| Parameter | Type | Description |
|---|---|---|
$iterableoptional | Iterable= undefined | An iterable object, such as an array, whose elements are each an object with properties 0 and 1 corresponding to key and value. If omitted, null, or undefined, the new Map is empty. |
Return value
MapA new Map object containing an entry for every element of iterable, or an empty Map when no argument is given.
Errors
Throws a TypeError when called without new, and when an element of the supplied iterable is not an object with 0 and 1 properties.
Changelog
- PHP ES2015Map introduced as a built-in keyed collection.
A Map stores key/value pairs where the key can be any value — an object, a function, a number, NaN — not just a string. That is the main reason to reach for it instead of a plain object, whose keys are always strings or symbols.
When to use it over an object
- Keys are objects, DOM nodes, or numbers you do not want coerced to strings.
- You add and remove entries constantly and want
sizeanddelete()without writing helpers. - You need iteration in insertion order. Plain objects reorder integer-like keys; a Map never does.
- The keys come from user input, so inherited names like
constructoror__proto__must not collide with anything.
Building one
The constructor accepts any iterable of two-element pairs, so new Map(Object.entries(obj)), new Map(otherMap) and new Map([[k, v]]) all work. Passing a Map copies its entries shallowly — the two maps are independent, but the values are still shared references.
Key comparison uses SameValueZero: NaN matches itself, and 0 and -0 are the same key. Everything else is strict identity, so two structurally identical objects are two different keys.
Example
When to use it
- Attach metadata to objects you do not own without mutating them
- Keep a lookup table whose keys are numbers and must stay numbers
- Store user-supplied keys safely, with no prototype names to collide with
- Preserve the order records arrived in while still allowing fast lookup
Frequently asked questions
When should I use a Map instead of an object in JavaScript?
Use a Map when keys are not strings, when you add and delete entries frequently, or when guaranteed insertion order matters. Use a plain object for fixed, string-keyed records you serialize to JSON, since JSON.stringify() turns a Map into {}.
How do I create a Map from an object?
Pass Object.entries(obj) to the constructor: new Map(Object.entries(obj)). Every key becomes a string, because object keys already are strings.
Can I use an object as a Map key?
Yes, and it is one of the main reasons Map exists. The key is matched by reference, so you must hold on to the same object to look the entry up again.
More examples
Converting to and from a plain object
Object.entries() produces exactly the [key, value] pairs the constructor wants, and Object.fromEntries() reverses it. The round trip only survives if every key is a string — numeric or object keys become strings, or unusable, on the way back.
const obj = { host: "localhost", port: 8080 };
const map = new Map(Object.entries(obj));
map.set("secure", false);
console.log(map.size);
const back = Object.fromEntries(map);
console.log(back);
console.log(typeof back.port);Copying a map is shallow
The new Map has its own entry list, so adding a key does not affect the original. The values are copied by reference, though, so mutating an array stored in one map is visible through the other.
const original = new Map([["list", [1, 2]]]);
const copy = new Map(original);
copy.set("extra", true);
console.log(original.has("extra")); // false — separate maps
copy.get("list").push(3);
console.log(original.get("list")); // [1, 2, 3] — shared array
Discussion