JavaScript Map

Why should you care about JavaScript Map?

Map gives you reliable key-value storage when plain objects feel limiting. It is especially useful when keys are not just strings, like objects, arrays, or IDs from external data.

A Map is a built-in structure for storing key-value pairs, similar to an object.

The big difference is that Map accepts any type as a key, not just strings. That means numbers, booleans, objects, and arrays can all be keys, and JavaScript keeps each key in its original type instead of converting it to a string.

A Map pairs keys with values
A key can be any JavaScript value.
String key: "username": Stores "js_dev".
Number key: 1: Stores "one". The string "1" is a different key.
Boolean key: true: Stores "yes".
Object key: user: Look up the value with the same object.
const user = {};
const map = new Map();
map.set("username", "js_dev");
map.set(1, "one");
map.set(true, "yes");
map.set(user, "editor");
map.get(user); // "editor"

javascript

const map = new Map();

map.set("username", "js_dev");   // string key
map.set(1, "one");               // number key
map.set(true, "yes");            // boolean key

console.log(map.get("username")); // js_dev
console.log(map.get(1));          // one
console.log(map.get(true));       // yes

Both structures store key-value associations, but they express different ownership. Choose Map when the collection itself should keep entries available. Choose WeakMap when metadata should disappear automatically after an object key is no longer used elsewhere.

Choose Map or WeakMap
Do you need to list entries or count them?
Map: Use for entries you need to list or count.
WeakMap: Use for metadata tied to an object.
const visibleUsers = new Map();
visibleUsers.set("user-1", { name: "Sam" });
const button = {};
const metadata = new WeakMap();
metadata.set(button, { clickCount: 0 });
visibleUsers.size; // 1
WeakMap has neither iteration nor a size property.
Map and WeakMap differences that affect your choice.
QuestionMapWeakMap
What can be a key?Any value, including primitives and objects.Objects and non-registered symbols only.
Can you count or iterate entries?Yes: size and iteration methods.No enumeration or size; entries may disappear during garbage collection.
Does it keep an object key alive?Yes, while the key remains in the Map.No. The object can be garbage-collected when nothing else references it.
Typical useMenus, caches, registries, counts, and data you need to list.Private metadata attached to DOM nodes or objects.

javascript

const visibleUsers = new Map();
visibleUsers.set("user-1", { name: "Sam" });
console.log(visibleUsers.size); // 1: listable application data

const elementMetadata = new WeakMap();
const button = document.querySelector("#save");
elementMetadata.set(button, { clickCount: 0 });

// When the button is removed and no other code references it,
// its WeakMap metadata can be collected automatically.
button.remove();

Do not use WeakMap as a hidden list. You cannot inspect all its entries, force garbage collection, or rely on a specific cleanup moment. If you need to display, count, or save every entry, use a regular Map and remove entries deliberately.

Decision shortcut: “Do I need to enumerate this collection?” Use Map. “Is this temporary metadata owned by an object?” Consider WeakMap.

You create a Map with new Map(). You can either start empty and add entries later, or pass an array of [key, value] pairs during creation.

The constructor accepts any iterable that produces two-item pairs, such as an array of arrays or another Map. Each pair becomes one key-value entry, and later entries replace earlier values when they use the same key.

Create a Map
Start empty or supply an iterable of entry pairs.
new Map(): Starts with zero entries.
new Map(pairs): Each pair has a key followed by a value.
const empty = new Map();
const map = new Map([
  ["username", "js_dev"],
  ["role", "admin"],
  ["status", "active"],
]);
map.size; // 3

javascript

// Empty Map
const emptyMap = new Map();

// Map with initial values
const map = new Map([
  ["username", "js_dev"],
  ["role", "admin"],
  ["status", "active"]
]);

console.log(map); // Map(3) { 'username' => 'js_dev', 'role' => 'admin', 'status' => 'active' }

Create a Map, add entries, and update an existing key.

Use map.set(key, value) to add or update data. If the key already exists, its value is replaced. If the key is new, a new entry is created.

Add or update a map entry
const map = new Map();
map.set("name", "Ada").get("name")
Returns: "Ada"

javascript

const map = new Map();

map.set("language", "JavaScript");
map.set("version", 2024);

// Update existing key
map.set("language", "TypeScript");

console.log(map.get("language")); // TypeScript
console.log(map.get("version"));  // 2024

set() returns the same Map, so you can chain multiple calls in a single statement. This makes initialization shorter and easier to read.

Chain calls to set()
const map = new Map();
[...map.set("a", 1).set("b", 2)]
Returns: [["a", 1], ["b", 2]]

javascript

const map = new Map();

map
  .set("username", "coder42")
  .set("role", "editor")
  .set("theme", "dark");

console.log(map.size); // 3

Here's a quick look at the methods and properties you'll use with Map:

  • set(key, value) - Add or update a key-value pair.
  • get(key) - Retrieve the value for a given key.
  • has(key) - Check whether a key exists in the Map.
  • size - Returns the number of entries in the Map.
  • clear() - Remove all entries from the Map.
  • delete(key) - Remove a specific entry by key.
  • keys() - Returns an iterator of all keys.
  • values() - Returns an iterator of all values.
  • entries() - Returns an iterator of all [key, value] pairs.
  • forEach(callback) - Runs a function for each entry in the Map.
Common Map operations
Use the key to read, update, or remove an entry.
set(key, value): Adds or updates an entry. Returns the Map.
get(key): Reads the value, or undefined if absent.
has(key): Checks whether the key exists.
delete(key): Returns true if an entry was removed.
clear(): Removes every entry.
size: Counts the entries.
const map = new Map();
map.set("role", "admin");
map.get("role"); // "admin"
map.size; // 1

Use map.get(key) to retrieve the value associated with a key. If the key does not exist, it returns undefined.

Because undefined can also be a stored value, use map.has(key) when you need to distinguish a missing key from an entry whose value is explicitly undefined.

Read a map entry
const map = new Map([["a", 1]]);
map.get("a")
Returns: 1

javascript

const map = new Map([
  ["role", "admin"],
  ["theme", "dark"]
]);

console.log(map.get("role"));    // admin
console.log(map.get("theme"));   // dark
console.log(map.get("locale"));  // undefined (key not found)

Read Map values with get, has, and size.

Use map.has(key) to check whether a key exists in the Map. It returns true if the key is present, and false if not.

Check for a key
const map = new Map([["a", 1]]);
map.has("b")
Returns: false

javascript

const map = new Map([["username", "js_dev"]]);

console.log(map.has("username")); // true
console.log(map.has("locale"));   // false

The size property returns the number of key-value pairs stored in the Map. Unlike arrays, you do not use .length; Maps use .size.

Count the entries
const map = new Map([["a", 1]]);
map.size
Returns: 1

javascript

const map = new Map();
map.set("a", 1);
map.set("b", 2);
map.set("c", 3);

console.log(map.size); // 3

The clear() method removes all key-value pairs from the Map.

After calling clear(), the Map still exists. It is just empty.

Clear every entry
const map = new Map([["a", 1]]);
map.clear()
Result: undefined
Afterward: map.size: 0

javascript

const map = new Map([["x", 10], ["y", 20]]);
console.log(map.size); // 2

map.clear();
console.log(map.size); // 0

Use map.delete(key) to remove a specific entry. It returns true if the key was found and removed, and false if the key did not exist.

Delete one entry
const map = new Map([["a", 1]]);
map.delete("a")
Returns: true
Afterward: map.size: 0

javascript

const map = new Map([["username", "js_dev"], ["role", "admin"]]);

map.delete("role");

console.log(map.has("role")); // false
console.log(map.size);        // 1

Since a Map accepts any value as a key, you can even use an array or object as a key. Map object and array keys are matched by reference identity, not by content. Two different arrays or objects with the same contents are different keys.

javascript

const coords = [10, 20];
const map = new Map();

map.set(coords, "location A");

console.log(map.get(coords));   // location A
console.log(map.get([10, 20])); // undefined (different array reference)

Two separate arrays with the same values are not the same reference, just as [10, 20] === [10, 20] is false. Map does not compare object and array keys by their contents, so map.get([10, 20]) returns undefined.

Use an array as a key
const key = [1, 2];
const map = new Map([[key, "Ada"]]);
map.get(key)
Returns: "Ada"

See how object keys use reference identity.

You can iterate over a Map with a for...of loop. Use map.entries(), map.keys(), or map.values(); entries are returned in insertion order.

Iterate over a Map
Entries, keys, and values follow insertion order.
entries(): Yields [key, value] pairs.
keys(): Yields only the keys.
values(): Yields only the values.
const map = new Map([["a", 1], ["b", 2]]);
for (const [key, value] of map) {
  console.log(key, value); // a 1, then b 2
}
[...map.keys()]; // ["a", "b"]
[...map.values()]; // [1, 2]
Iterating the Map directly yields entries.

javascript

const map = new Map([["a", 1], ["b", 2], ["c", 3]]);

// Iterate over entries (key-value pairs)
for (const [key, value] of map.entries()) {
  console.log(key, value); // a 1, b 2, c 3
}

// Iterate over keys only
for (const key of map.keys()) {
  console.log(key); // a, b, c
}

// Iterate over values only
for (const value of map.values()) {
  console.log(value); // 1, 2, 3
}

Iterate through Map entries in insertion order.

You can convert a plain object to a Map with Object.entries(obj). This returns an array of [key, value] pairs, which you can pass directly to new Map().

Convert object entries to a map
const item = { name: "Ada" };
new Map(Object.entries(item)).size
Returns: 1

javascript

const session = { username: "js_dev", role: "admin", status: "active" };

const map = new Map(Object.entries(session));

console.log(map.get("username")); // js_dev
console.log(map.size);            // 3

Convert between plain objects and Maps.

You can convert a Map to an array with the spread operator [...map]. You can also use Array.from(map); both approaches produce an array of [key, value] pairs.

Copy map entries to an array
const map = new Map([["a", 1]]);
[...map]
Returns: [["a", 1]]

javascript

const map = new Map([["a", 1], ["b", 2]]);

// Using spread operator
const arr1 = [...map];
console.log(arr1); // [['a', 1], ['b', 2]]

// Using Array.from
const arr2 = Array.from(map);
console.log(arr2); // [['a', 1], ['b', 2]]

// Keys or values only as arrays
const keys = [...map.keys()];     // ['a', 'b']
const values = [...map.values()]; // [1, 2]

The forEach method iterates over each entry in the Map. It calls a callback function with (value, key, map). Notice that value comes before key, which is the opposite of what you might expect from a key-value pair.

Visit entries with forEach()
The callback receives the value before the key.
First argument: The current value.
Second argument: The current key.
Third argument: The Map being visited.
const map = new Map([
  ["username", "js_dev"], ["role", "admin"],
]);
map.forEach((value, key) => {
  console.log(`${key}: ${value}`);
});
Prints username: js_dev, then role: admin.

javascript

const map = new Map([["username", "js_dev"], ["role", "admin"]]);

map.forEach((value, key) => {
  console.log(`${key}: ${value}`);
});
// username: js_dev
// role: admin

A WeakMap is an advanced alternative to Map for metadata linked to objects. It allows object and non-registered Symbol keys, which it holds weakly; entries can disappear after a key is no longer reachable elsewhere. A WeakMap cannot be enumerated or queried for size, so it has no keys(), values(), entries(), clear(), or size.

The supported operations are set(), get(), has(), and delete(). Use them when you know the object key and do not need to enumerate every entry.

Store metadata in a WeakMap
An object key is not kept alive by the WeakMap.
While you have the key: Use get(), has(), or delete() with that key.
When the key is unreachable: Its entry can be garbage-collected.
const metadata = new WeakMap();
let session = { id: "sess_abc123" };
metadata.set(session, "authenticated");
metadata.get(session); // "authenticated"
session = null;
Keys can be objects or non-registered symbols.

WeakMap is useful when you attach extra data to an object. It does this without preventing JavaScript from cleaning that object up later.

javascript

const weakMap = new WeakMap();

let session = { id: "sess_abc123" };
weakMap.set(session, "authenticated");

console.log(weakMap.get(session)); // authenticated
console.log(weakMap.has(session)); // true

                          // When 'session' is set to null and no other references remain,
                          // the entry may eventually be garbage collected.
session = null;
  • Map - stores key-value pairs where keys can be of any type.
  • new Map() - creates a new Map, optionally initialized with [key, value] pairs.
  • set(key, value) - adds or updates an entry; returns the Map (chainable).
  • get(key) - retrieves the value for a key; returns undefined if not found.
  • has(key) - returns true if the key exists, otherwise false.
  • size - returns the number of entries in the Map.
  • clear() - removes all entries from the Map.
  • delete(key) - removes a specific entry by key.
  • Iteration - use for...of with entries(), keys(), or values(); Map preserves insertion order.
  • Object to Map - use new Map(Object.entries(obj)).
  • Map to Array - use [...map] or Array.from(map).
  • forEach - callback receives (value, key) - value comes first.
  • WeakMap - an advanced collection with weakly held object and non-registered Symbol keys; it cannot be enumerated or sized.

What's next? You now know how Maps organize key-value data.

The next tutorial covers destructuring. It makes reading values from objects and arrays much cleaner.

Videos for this topic will be added soon.

Reviewed by

SimplyJavaScript Editorial Team

Technical editors and JavaScript educators with hands-on experience building frontend projects, writing learning material, and reviewing tutorials for clarity, accuracy, and beginner-friendly guidance.