Sass map-merge() Function

Posted in Sass Tutorial

Updated on Sep 30, 2024

By Mari Selvan

👁️ 56 - Views

⏳ 4 mins

💬 1 Comment

Photo Credit to CodeToFun

🙋 Introduction

The map-merge() function in Sass is an essential utility for working with maps (associative arrays). It allows you to merge two maps together, combining their key-value pairs.

This function is particularly useful when you need to extend or override a map with additional values without altering the original data structure.

💡 Syntax

The syntax of the map-merge() function is straightforward. It takes two arguments:

Syntax

Copied

map-merge($map1, $map2)

🔢 Parameters

$map1: The base map that will be merged with $map2.
$map2: The map whose key-value pairs will be added to $map1. If both maps contain the same key, the value from $map2 will overwrite the value from $map1.

↩️ Return Value

The function returns a new map containing the merged key-value pairs from both maps. If there are any duplicate keys, the values from $map2 will overwrite those from $map1.

📝 Example Usage

Let’s look at some examples to understand how map-merge() can be used effectively.

📜 Example 1: Basic Map Merge

example.scss

Copied

$map1: (
  color: blue,
  size: large
);

$map2: (
  size: medium,
  weight: bold
);

$result: map-merge($map1, $map2);

body {
  color: map-get($result, color);
  font-size: map-get($result, size);
  font-weight: map-get($result, weight);
}

In this example, $map1 and $map2 are merged. The key size exists in both maps, so the value from $map2 (medium) overwrites the value from $map1 (large). The final map contains the keys color, size, and weight.

📜 Example 2: Merging Nested Maps

example.scss

Copied

$map1: (
  header: (
    color: blue,
    size: large
  )
);

$map2: (
  header: (
    size: medium,
    weight: bold
  )
);

$result: map-merge($map1, $map2);

.header {
  color: map-get(map-get($result, header), color);
  font-size: map-get(map-get($result, header), size);
  font-weight: map-get(map-get($result, header), weight);
}

In this example, both $map1 and $map2 contain nested maps under the key header. The nested maps are merged, and the value from $map2 takes precedence where keys overlap.

📜 Example 3: Using Map-Merge for Configuration

example.scss

Copied

$default-settings: (
  color: black,
  font-size: 16px,
  margin: 10px
);

$user-settings: (
  color: red,
  margin: 20px
);

$final-settings: map-merge($default-settings, $user-settings);

.container {
  color: map-get($final-settings, color);
  font-size: map-get($final-settings, font-size);
  margin: map-get($final-settings, margin);
}

This example demonstrates how map-merge() can be used to create a configuration map where user-defined settings can override default values. The final map includes the user’s preferences while retaining default values for any keys not specified by the user.

🎉 Conclusion

The map-merge() function in Sass is a powerful tool for combining maps, allowing you to build more dynamic and flexible stylesheets. Whether you're dealing with configurations, theme settings, or any scenario requiring map manipulation, map-merge() helps streamline your code by efficiently merging maps while preserving or overriding specific values as needed.

Understanding and leveraging map-merge() in your Sass projects can lead to cleaner, more maintainable code, especially when working with complex stylesheets that rely heavily on maps for organizing data. Experiment with different maps and configurations to explore the full potential of this function.