Google+
4elements web design & consultancy

Shineyrock

web design & consultancy
Shineyrock web design & consultancy

Shineyrock

  1. web design and consultancy

blog

  1. Home
  2. blog
  3. read
  4. An Introduction to Sass Maps: Usage and Examples
  • dislike -9 29

    An Introduction to Sass Maps: Usage and Examples

    1. December 2014
    2. Daily
    3. read 803

    For scalable front-ends Sass Maps are a blessing. Extracting configuration from the logic of a module is a great method for structuring. Let me explain to you why I think Sass Maps are the best feature in Sass 3.3.

    Sass 3.3

    Sass 3.3 has been within everyone’s reach for a while now, but many of its real-world features are still unfamiliar to many developers. The new version of Sass brought us a new data type named map. Maps hold a collection of key/value pairs and help us create small configuration areas for a simplified codebase.

    How to Use Sass Maps

    To being with we’ll cover the basics of using Sass Maps, then later on we’ll look at some use cases.

    Generating a Map

    Here’s a quick overview of the syntax for a sassy map. Start with a variable name ($map in this case) and then enter some keys with values, separated with commas, all within braces:

    $map: (
    key: value,
    nextkey: nextvalue
);

    How to Get a Value

    Having stored multiple key/value pairs at some point you’ll need to retrieve that information. If you need to find the value of a key use the function map-get(). We’re going to pass two parameters to it: the name of the map and then the key.

    .element:before {
    content: map-get($map, key);
}

    Once compiled the output will be as follows:

    .element:before {
    content: value;
}

    How to Check if a Key is Available

    It’s strongly advisable that you use solid error handling in your Sass development process. For this Sass gives us the function map-has-key(). This helper looks whether a key exists, and if not delivers another output to warn the developer. 

    Take a look at this An Introduction to Error Handling in Sass  by Hugo Giraudel for an awesome way to handle errors.

    $map: (
    key: value,
    nextkey: nextvalue
);

.element {
  @if map-has-key($map, key) {
    content: ’Map has this key.’;
  } @else {
    content: ’Map has not this key.’;
  }
}

    Result:

    .element {
  content: ’Map has this key.’;
}

    How to Merge Maps Together

    Bonus time: Sass allows us to merge two or more maps together. You’re getting the hang of this now, so take a look at this example of how to use the map-merge() function:

    $colors: (
  light: #ccc,
  dark: #000
);

$brand-colors: (
  main: red,
  alternative: blue
);

// Merge maps
$merged: map-merge($colors, $brand-colors);

.element {
  content: map-get($merged, alternative);
}

    The result:

    .element {
  content: blue;
}

    Real-World Use Cases

    We’ve covered the how, now let’s look at the where.

    1. How to Loop Through a Map and Generate Classes

    Maps can also be useful without the accompanying functions. For example you can perform a loop through your map, define the parameters with the values which you expect and then add the name of the Sass Map. By doing this it’s possible to work with different kind of values. 

    In this example I’m outputting classes to display icons. I put the name of the icon as the key, leaving the value to store the actual content (which we’d then add via pseudo elements).

    Note: In a real-world scenario we would first declare some basic styles, but that’s beyond the scope of this tutorial.

    /* Define the Sassy Map called $icons */
$icons: (
  checkmark: a,
  plus: b,
  minus: c
);

/* For each key in the map, created an own class */
@each $name, $value in $icons {
  .icon--#{$name} {
    content: $value;
  }
}

    The output speaks for itself:

    /* For each key in the map, created an own class */
.icon--checkmark {
  content: "a";
}

.icon--plus {
  content: "b";
}

.icon--minus {
  content: "c";
}

    This is a really efficient way to output loads of classes for icons. There are plenty more use cases too–let’s look at some.

    2. Multiple Values for Added Awesomeness

    Moving on, it’s possible to give a key more than one value. This is done by using clippings and entering multiple values with a comma separator. This, for example, could be great to transfer styles for variants of a module. 

    Here I’m going to style a series of buttons. The first value for each key is for the background-color and the second one is for the font-color.

    Then I loop through the keys with the expected object $colors. I get the value of the first key in this object with nth($colors, 1) (start with the name of the object and then the position of the sought value). If you need the the second value, then you’d enter 2. 

    // _m-buttons.scss
$buttons: (
  error: (#d82d2d, #666),
  success: (#52bf4a, #fff),
  warning: (#c23435, #fff)
);

.m-button {
  display: inline-block;
  padding: .5em;
  background: #ccc;
  color: #666;
  
  @each $name, $colors in $buttons {
    $bgcolor: nth($colors, 1);
    $fontcolor: nth($colors, 2);
    
    &--#{$name} {
      background-color: $bgcolor;
      color: $fontcolor;
    }  
  }
}

    The output:

    .m-button {
  display: inline-block;
  padding: .5em;
  background: #ccc;
  color: #666;
}

.m-button--error {
  background-color: #d82d2d;
  color: #666;
}

.m-button--success {
  background-color: #52bf4a;
  color: #fff;
}

.m-button--warning {
  background-color: #c23435;
  color: #fff;
}

    3. Handling Layers (z-index)

    I don’t know a single front-end developer who hasn’t wrestled with z-index at some point. Problems usually arise from losing an overview if you need to use z-index in multiple places in a project. Sass maps can help us.

    Let’s start with $layer as the map. The keys should be logically named so that you know which value is for which element - maybe offcanvas, lightbox, dropdown etc.

    // _config.scss
$layer: (
  offcanvas: 1,
  lightbox: 500,
  dropdown: 10,
  tooltip: 15
);

// _m-lightboxes.scss
@function layer($name) {
  @if map-has-key($layer, $name) {
    @return map-get($layer, $name);  
  }
  
  @warn "The key #{$name} is not in the map ’$layer’";
  @return null;
};

.m-lightbox {
  z-index: layer(lightbox);
}

    Here I wrote a function to get the value of a specific key, but why did I do that? The answer is thankfully straightforward: it’s quicker than writing map-get() each time. Another positive aspect is that you can create an error-handling and give the developer a little feedback as to why is nothing happening.

    This is the output:

    .m-lightbox {
  z-index: 500;
}

    4. Using Base Styles for Fonts in a Project

    Every project has its own configuration file; basics for global usage. For example in my projects I define some values for font properties: font-color, alternative font-color, font-family or font-size. I used to create a variable for each property, but a map would be better.

    Here is a quick example, to begin with the old solution:

    $base-font-color: #666;
$base-font-family: Arial, Helvetica, Sans-Serif;
$base-font-size: 16px;
$base-line-height: 1.4;

    Then the new solution using a Sass map:

    // _config.scss
$font: (
  color: #666,
  family: (Arial, Helvetica),
  size: 16px,
  line-height: 1.4
);

// _presets.scss
body {
  color: map-get($font, color-light);
  font-family: map-get($font, family);
  font-size: map-get($font, size);
  line-height: map-get($font, line-height);
}

    5. Breakpoints <3

    I love this use-case. It’s superb to have an area for the breakpoints which are in your whole project. So, like the section about the handling with z-index, you have an overview of all used breakpoints. If you change the value there, than you change the behaviour throughout your project. Awesome.

    So let’s start with a map called $breakpoints. 

    Our goal is to use breakpoints with implicit names instead of hard pixel values in an element. Because of this we need a mixin which will output the value of the stated name. I called the mixin respond-to and pass $breakpoint as a parameter. With $value I get the value of the expected breakpoint and put it later in the media query. 

    // Map with much breakpoints
$breakpoints: (
    small: 320px,
    medium: 600px,
    large: 768px
);

// Respond-To Mixin
@mixin respond-to($breakpoint) {
    @if map-has-key($breakpoints, $breakpoint) {
        $value: map-get($breakpoints, $breakpoint);
        
        @media screen and (min-width: $value) {
            @content;
        }
    }
    
    @warn "Unknown `#{$breakpoint}` in $breakpoints";
}

    Example:

    // Sass
.m-tabs {
    background-color: #f2f2f2;
    
    @include respond-to(medium) {
        background-color: #666;
    }
}

// Output
.m-tabs {
    background-color: #f2f2f2;
}
@media screen and (min-width: 600px) {
    background-color: #666;
}

    This use-case is one of my favorites! 

    6. Advanced Usage for Colors

    Things are getting a little tricker now. Let’s look at nested maps–awesome for color schemes with a range of tones. 

    Our Sass map in this case gets the name $colorscheme and it has objects with keys and values. The project has differing gray tones, but we don’t want to declare a variable for each one. So we add an object gray, add clippings and then the keys with values. 

    Start with a Map like this one here:

    // Scheme of colors
$colorscheme: (
  gray: (
    base: #ccc,
    light: #f2f2f2,
    dark: #666
  ),
  brown: (
    base: #ab906b,
    light: #ecdac3,
    dark: #5e421c
  )
);

    Now let’s add the function setcolor for a shorter way to get our color of choice. The first expected value is the object of the Sass map ($scheme) - in this example it could be gray or brown. The second parameter is the color which you want ($tone) - the default value for this being the key base.

    // Our function for shorter usage of map-get();
@function setcolor($scheme, $tone: base) {
    @return map-get(map-get($colorscheme, $scheme), $tone);
}

    Finally, here’s an example of how you can use it and how you get the different colors from the nested map. It’s easier than you think (maybe)!

    // Sass
.element {
  color: setcolor(brown);
}
.element--light {
  color: setcolor(brown, light);
}

// Output
.element {
    color: #ab906b;
}
.element--light {
    color: #ecdac3;
}

    You’ve completed the challenge. Now you can create a palette without bloating your code with too many variables for each type of color. 

    For this technique I was inspired by Tom Davies and I recommend you check out his article on the matter.

    Theming with Classes

    Now something for advanced Sass users. In projects it’s often a requirement to create different kinds of themes with the same codebase. So here is a proposal to set a theme-class on the top of the document to apply a specific look. We need an object where we can handle the name of themes and set the different styles for the module. 

    Define the themes

    Start with a Sass map and define the themes globally for your project. The value is the name and the class, which you must append to the <body> element. In this example I created the map $themes with two variants: theme-light and theme-dark.

    // _config.scss
$themes: (
  theme1: theme-light,
  theme2: theme-dark
);

    Getting the Value (Short Way)

    Now we need a function for a quick way to get values of the modules. It’s a brief helper and needs three parameters. These are:

    • $map: Define the name of the map where all values come from.
    • $object: In this case the key for the theme.
    • $style: The property for the style which is needed.
    // _functions.scss
@function setStyle($map, $object, $style) {
  @if map-has-key($map, $object) {
    @return map-get(map-get($map, $object), $style);
  }
  @warn "The key ´#{$object} is not available in the map.";
  @return null;
}

    Build the Module

    Now create a new Sass Map called $config. Each theme gets an object and the name must be the same key as you define in $themes: if not you will get an error. 

    // _m-buttons.scss
// 1.Config
$config: (
  theme1: (
    background: #f2f2f2,
    color: #000
  ),
  theme2: (
    background: #666,
    color: #fff
  )
);

    Loop Through the Themes

    Finally the part with a little bit of magic. We start with a module like .m-button and then we want to create a different look in each theme. So we use @each with $key and $value as expected values which we get from the Map $themes. Now Sass loops through the keys in the map and creates something for each theme.

    At the beginning of this section I mentioned that it’s necessary that the keys are the same in each map ($themes and $config). Therefore we must check if the map $config has the key from the map $themes, so use the function map-has-key(). If the key is available do the following, else throw an error to inform the developer.

    // _m-buttons.scss
// 2.Base
.m-button {
  @each $key, $value in $themes {
    @if map-has-key($config, $key) {
      .#{$value} & {
        background: setStyle($config, $key, background);
        color: setStyle($config, $key, color);
      }
    } @else {
      @warn "The key ´#{$key} isn’t defined in the map $config´"
    }
  }
}

    After all the written code, let’s take a look at the result. It’s superb that the configuration area is separated from the logic of the module. 

    .theme-light .m-button {
  background: #f2f2f2;
  color: #000;
}
.theme-dark .m-button {
  background: #666;
  color: #fff;
}

    Finally it’s time to try it out by yourself. Maybe this solution doesn’t work for you and you need another one, but all in all I hope it will help you to maintain your code well. You can play with this example on Codepen:

    Final Thoughts

    In my eyes Sass Maps were the best feature to be introduced in Sass 3.3. Personally, I feel they’re a great way to give your foundation better structure and create small configuration areas. Sass maps make it easier to handle and change values without affecting the logic of the whole codebase. Start using them today, your coworkers will be grateful!

    If you’re already using Sass maps, let us know how you use them in your projects!

    Photo

    martijn broeders

    founder/ strategic creative at shineyrock web design & consultancy
    e-mail: .(JavaScript must be enabled to view this email address)
    phone: 434 210 0245
    Add a comment...
    4elements
    Comments

By - category

By - date

Copyright © 1999 - 2026 Shineyrock web design and consultancy, All Rights Reserved / Terms of Conditions / Sitemap: XML, HTML, Images, Mobile, News