How to Merge Map Objects in JavaScript

A common task when working with Map objects is to combine two or more of them into a single Map. Whether you're aggregating configuration settings, merging datasets, or simply combining key-value pairs from different sources, you need an efficient and reliable way to do it.

This guide will teach you the modern and most concise method for merging Map objects using the Map constructor and the spread syntax (...). You will also learn the critical rule about how duplicate keys are handled during a merge.

The Core Method: The Map Constructor with Spread Syntax

The simplest and most idiomatic way to merge Map objects is to spread their key-value pairs into a new Map constructor.

For example, you have two Map objects and want to create a third that contains all the key-value pairs from both.

// Problem: How to combine these two Maps?
const map1 = new Map([['name', 'Alice']]);
const map2 = new Map([['age', 30]]);

Solution: the spread syntax (...) can be used on a Map to get an array of its [key, value] pairs. By spreading multiple maps into an array and passing that array to new Map(), you create a merged Map.

const map1 = new Map([['name', 'Alice']]);
const map2 = new Map([['age', 30]]);

const mergedMap = new Map([...map1, ...map2]);

console.log(mergedMap); 
// Output: Map(2) { 'name' => 'Alice', 'age' => 30 }

How the Merge Works

The magic of this technique lies in understanding what the spread syntax does to a Map. It converts the Map into an array of its [key, value] entries.

const map1 = new Map([['name', 'Alice']]);
const map2 = new Map([['age', 30]]);

// Spreading the maps creates an array of entries
const combinedEntries = [...map1, ...map2];

console.log(combinedEntries);
// Output: [ ['name', 'Alice'], ['age', 30] ]

note

The new Map() constructor can accept an array of [key, value] pairs to create a new Map. By providing this combined array, you effectively create a new Map from the merged entries.

The Golden Rule: Later Maps Overwrite Earlier Keys

This is the most critical concept to understand when merging. If multiple Map objects contain the same key, the value from the last Map in the sequence will win.

For example, both maps contain a status key. Which status value will be in the final map?

// Problem: Which 'status' value will be in the final map?
const defaults = new Map([
  ['theme', 'dark'],
  ['status', 'active']
]);

const userSettings = new Map([
  ['status', 'inactive'],
  ['notifications', 'enabled']
]);

Solution: the order in which you spread the maps determines the final result.

const defaults = new Map([
  ['theme', 'dark'],
  ['status', 'active']
]);

const userSettings = new Map([
  ['status', 'inactive'],
  ['notifications', 'enabled']
]);

// The userSettings map comes last, so its 'status' value will overwrite the one from defaults.
const finalSettings = new Map([...defaults, ...userSettings]);

console.log(finalSettings);
// Output: Map(3) { 'theme' => 'dark', 'status' => 'inactive', 'notifications' => 'enabled' }

This behavior is extremely useful for applying user overrides to a set of default options.

Merging Multiple Maps at Once

The spread syntax method can be used to merge any number of Map objects in a single, readable line.

Solution:

const map1 = new Map([['a', 1]]);
const map2 = new Map([['b', 2]]);
const map3 = new Map([['c', 3]]);
const map4 = new Map([['a', 4]]); // This will overwrite the 'a' from map1

const merged = new Map([...map1, ...map2, ...map3, ...map4]);

console.log(merged);
// Output: Map(3) { 'a' => 4, 'b' => 2, 'c' => 3 }

An Alternative (Verbose) Method: Using a for...of Loop

While the spread syntax is recommended, you can also merge maps manually by iterating through each map's entries and setting them on a new Map object.

Solution:

function mergeMaps(...maps) {
  const newMap = new Map();

  for (const map of maps) {
    for (const [key, value] of map) {
      newMap.set(key, value);
    }
  }

  return newMap;
}

const map1 = new Map([['a', 1]]);
const map2 = new Map([['b', 2]]);
const merged = mergeMaps(map1, map2);

console.log(merged); 
// Output: Map(2) { 'a' => 1, 'b' => 2 }

note

This method produces the same result and also respects the "last one wins" rule, but it is significantly more verbose than the spread syntax approach.

Conclusion

Merging Map objects in JavaScript is a simple and elegant task thanks to modern syntax.

• The new Map([...map1, ...map2]) pattern is the most concise, readable, and idiomatic way to merge Map objects.
• The most important rule to remember is that when keys conflict, the value from the last Map provided in the sequence will always take precedence. This makes the operation predictable and useful for tasks like applying configuration overrides.