If you want to set a font-stack as a variable in Sass you could do something like $fonts: Helvetica, Arial, sans-serif in a single variable. Later you could assign the font stack with font-family: $fonts; However what if you only wanted to assign one of the fonts and not the whole stack? Sass lists might be your answer.

The last month or so I’ve been talking about Sass data types, the operations you can perform on them and the built-in functions Sass offers to manipulate them. I started with an overview and have since taken deeper looks at numbers, strings, and colors not once, but twice.

Today I want to look at the list data type, which allows you to create flat data structures and later access the data point you want from within the structure.

Sass Lists

Lists in Sass are a data structures containing zero or more values. They’re similar to the arrays of most programming languages, though they’re not exactly the same. Lists are how Sass represents any series of values of a single type or of several mixed types. They’re even how Sass stores single values, which become lists containing a single item.

If you’ve been working with variables in Sass you’ve already been using lists even if you didn’t realize it. You don’t do anything special to create a list. When you create a variable or set values on a property, Sass stores those values in a list.

Consider the following variables

$ margin : 1px 2px 3px 4px ; $a: "hello" 9 #ff0; $b: hello there; $c: red; $d: ();

Each of these is a Sass list, the last being an empty list. Notice that both “hello” and hello are valid list items. The quotes around strings are optional in a list.

That said, the following are different lists.

$a: "hello there" $b: hello there

$a is a list with the single string “hello there” while $b is a list with two items, hello and there.

The values in a Sass list can be separated with either white space or commas so the following both represent the same list of items.

$ margin : 0 2em 0 1.5em ; $ margin : 0, 2em, 0, 1.5em ;

You can also mix spaces and commas, though this will created nested lists, which I’ll cover momentarily.

$ margin : 0, 2em, 0 1.5em ;

Parenthesis aren’t necessary, but it’s common to use them to make it clear your values are part of a list.

$list: (a, b, c, d);

Lists can also be written multi-line as opposed to having all the list items on a single line.

$list: ( a, b, c, d, )

The trailing comma after the last item isn’t necessary, but it’s often used when writing multi-line lists. One place where you would want to use a trailing comma is in a single item list.

$list (a); $list(a,);

Even though Sass is storing both values as a single item list, it will report the type of the first one as a string, and the second one as a list. Both are still treated as lists and you can use the same list functions on either.

If you have programming experience, one thing to note with lists in Sass is that the index of the first item is 1 and not 0, which is different than what you would find in the arrays of most programming languages.

I mentioned that lists can be empty as in $d: () . An empty list will throw an error when output to CSS.

$d: (); margin : $d ; // throws an error when compiling

You would typically add values to a list before compiling to CSS. An empty list is usually set up for the purpose of adding values to it later. If a list contains an empty list or null values, they will be stripped when compiling to CSS.

margin : 1px 2px () 3px 4px ; margin : 1px 2px null 3px 4px ;

will both compile to:

margin : 1px 2px 3px 4px ;

Notice that the () and null values have been removed when the Sass is compiled to CSS. The reason the code compiles unlike the previous example is the lists contains an empty list or null along with other values, where the previous example only included the empty list.

Nested Lists

Just as arrays can contain other arrays, lists can contain other lists. Earlier I mentioned you could mix commas and spaces when separating items in a list. When you do, you’re creating a nested list. For example:

$ margin : 1px 2px, 3px 4px ;

This creates a list with two items, the first being the list 1px 2px and the second being the list 3px 4px. Remove the comma:

$ margin : 1px 2px 3px 4px ;

You now have a single list with four items.

That can get confusing pretty quickly, especially as you aren’t limited to two levels of nesting. An easier way to write and read a list is to use multiple lines.

$list: item-1 item-2 item-3, item-4 item-5 item-6, item-7 item-8 item-9;

or using parenthesis:

$list: ( (item-1 item-2 item-3), (item-4 item-5 item-6), (item-7 item-8 item-9) );

The parenthesis will be removed when compiling to CSS as they won’t make sense in CSS. Whether you write a list as (1px 2px), (3px 4px) or 1px 2px, 3px 4px, they’ll look the same when compiled to CSS

Guidelines for Creating Lists in Sass

There are a few options for how you create lists. Should you write them on a single line or on multiple lines? Should you use commas or are spaces enough to separate items? When should you use parenthesis? As you might guess some have proposed guidelines for the best way to write your lists.

Hugo Giraudel, who maintains the Sass guidelines project (and is the author of many articles about Sass), recommends the following guidelines for creating lists:

Either inlined or multilines;

Necessarily on multilines if too long to fit on an 80-character line;

Unless used as is for CSS purposes, always comma separated;

Always wrapped in parenthesis;

Trailing comma if multilines, not if inlined.

It’s best to stick with commas and parenthesis because it will make your lists clearer to read and understand. The exception is when you want the list to compile to CSS exactly as written.

When it comes to single line or multi-line, either is fine and you might choose based on how many items are in the list or what the list is meant to hold.

Closing Thoughts

Let’s leave things here for today. The main thing to take away is that lists are data structures similar to the arrays of most programming languages. You can nest lists creating structures similar to multi-dimensional arrays.

Because you have several options in what syntax you use to declare a list, it means you’ll see lists written in a variety of different ways. You’ll thank yourself for choosing a standard and following it and I think Hugo Giraudel’s recommendations offer a good standard.

Now that you understand how to create lists we need to know how to work with them and how to manipulate their values. That’ll be the topic for next week when I talk about list functions.

« Prev PostNext Post »

Download a free sample from my book, Design Fundamentals.