JavaScript Map: key-value storage and lookup

A JavaScript Map object stores key-value pairs and allows any value—objects, functions, primitives—to be a key. Use it when you need insertion-order iteration, non-string keys, or frequent additions and deletions. Unlike plain objects, Map keys aren’t affected by inherited prototype properties, which avoids surprises with dynamic string keys.

JavaScript Map Example For Key-Value Storage

JavaScript Editor

const scores = new Map();
scores.set("alice", 92);
scores.set("bob", 87);
scores.set("alice", 95); // updates existing key

console.log(scores.get("alice"));
console.log(scores.has("charlie"));
console.log(scores.size);

Output:

Output will appear here...

Output:

95
false
2

How This Example Works

new Map() creates an empty map. Calling Map() without new throws a TypeError.
set adds a key-value pair and returns the Map instance, enabling call chaining like map.set("a", 1).set("b", 2). Calling set with an existing key overwrites the value without changing that key’s iteration position.
get returns the stored value, or undefined if the key is missing. Use has to distinguish a missing key from one explicitly set to undefined.
size reflects the current entry count—unlike objects, which require Object.keys(obj).length.

Common Mistakes With JavaScript Map

Using bracket syntax instead of set/get:

Wrong:

const map = new Map();
map["key"] = "value";
console.log(map.get("key")); // undefined

Right:

const map = new Map();
map.set("key", "value");
console.log(map.get("key")); // "value"

Bracket syntax sets an object property on the Map instance, not a Map entry. get, has, and size ignore it.

Expecting structural equality for object keys:

Wrong:

const map = new Map();
map.set({id: 1}, "alice");
console.log(map.get({id: 1})); // undefined

Right:

const key = {id: 1};
map.set(key, "alice");
console.log(map.get(key)); // "alice"

Map uses SameValueZero for key equality. For objects, that means reference identity: two identical-looking object literals are different keys.

JavaScript Map vs Object

	`Map`	Object
Key types	Any value (objects, functions, primitives)	Strings and Symbols only
Iteration order	Insertion order (guaranteed)	Mostly insertion order, but integer-like keys sort first
Size	`map.size`	`Object.keys(obj).length`
Prototype collisions	None	Keys can shadow `toString`, `constructor`, etc.
JSON serialization	Manual via `Object.fromEntries`	`JSON.stringify` built in

Use Map when keys aren’t strings, when entries are added and removed frequently, or when you store untrusted keys. Use a plain object for fixed-shape records or data that needs JSON serialization. If you need an object but want to avoid prototype-key collisions, use Object.create(null) as the backing object.

FAQ

Does JavaScript Map preserve insertion order?

Yes. Map iterates entries in the order they were first inserted. set() on an existing key updates the value but keeps the original position. Deleting a key and re-adding it moves it to the end.

Can JavaScript Map use objects as keys?

Yes, but Map compares object keys by reference, not by structure. Two different objects with the same properties are treated as separate keys. Store the reference in a variable and use that same reference for both set and get.

How do I convert a JavaScript Map to an object or JSON?

Call Object.fromEntries(map) to create a plain object—this works when all keys are strings or symbols. For non-string keys, serialize the entries array: JSON.stringify([...map]).

What is the difference between JavaScript Map and the JavaScript map() function?

Map is a key-value collection for storing and retrieving data. The JavaScript map() function (Array.prototype.map) is an array method that returns a new array by applying a callback to each element. They share the name but serve different purposes.