Manipulate And Retrieve Data With Sass List Functions

Posted: 16 Aug 2016 05:30 AM PDT

Lists are a series of values stored together as a data structure. On their own they're not any more useful than regular Sass variables, however they become more useful when using the built-in functions Sass provides for working with them.

I've been talking about Sass data types, the operations you can perform on them and the built-in functions Sass gives us to manipulate them. I started with an overview and have since taken deeper looks at numbers, strings, colors, and then colors a second time.

Last week I talked about lists in Sass and showed you the different syntax for creating lists before offering some guidelines for how to declare them. Today I want to continue with the built-in list functions Sass provides.

Sass' Built-In List Functions

Lists don't support any special operators. To work with lists you use Sass' built-in list functions. In fact it's these functions that really make lists useful. They allow you to access specific values in a list, combine lists, and add items to lists.

One thing to note before getting to the functions is that a list in Sass is immutable. It doesn't change. When you work with the list functions they return a new list rather than making changes to the original list.

If you want to know how many items are stored in a list you can use the length($list) function.

1  2  3  4  5

$list-1: (10px 20px 30px 40px);    length($list-1) => 4    $list-2: (10px 20px, 30px 40px);    length($list-2) => 2

Notice that the first list is 4 items long, while the second list is only 2 items long. That's because $list–2 actually contains 2 nested lists (note the comma) so it contains 2 items of type list.

To get the value of a specific item in the list you can use the nth($list, $n) function

1  2  3  4  5

$list-1: (10px 20px 30px 40px);    nth($list-1, 3) => 30px    $list-2: helvetica, arial, sans-serif;    nth($list-2, 1) => helvetica

Remember that the first item in the list is at index 1 and not index 0 like most programming languages.

If you know the value of a list item, but aren't sure where in the list it's located you can use the index($list, $value) function to find the index or position of the value within the list.

1 2	$list: (10px 20px 30px 40px); index($list, 20px) => 2

If the value isn't in the list the function returns null.

1 2	$list: (10px 20px 30px 40px); index($list, 25px) => null

You might at times need to know how the items in a list are separated and you can use the list-separator(#list) function to find out.

1  2  3  4  5

$list-1: (10px 20px 30px 40px);    $list-2: (10px, 20px, 30px, 40px);    list-separator(#list-1) => space    list-separator(#list-2) => comma

If the list has only a single element with no trailing comma, the function will return space. If the trailing comma is present, the function returns comma

1  2  3  4  5

$list-1: (10px);    $list-2: (10px,);    list-separator(#list-1) => space    list-separator(#list-2) => comma

To change the value of any list item you use the set-nth($list, $n, $value) function, which replaces the value of the list item at index $n with $value.

1  2  3  4  5

$list: (10px 20px 30px 40px);    h1 {     margin: set-nth($list, 4, 50px);    }

Here I used set-nth() to replace the last item (40px) with a new value of 50px. The Sass compiles to:

1  2  3

h1 {     margin: 10px 20px 30px 50px;    }

To add an item to a list you use the append($list1, $val, $separator) function, which will add the new item at the end of the list. The separator is optional, but if you use one, all the separators in the new list will be of the type specified.

1  2  3

$list: (10px 20px 30px 40px);    append($list, 50px) => (10px 20px 30px 40px 50px)    append($list, 50px, comma) => (10px, 20px, 30px, 40px, 50px)

Because I set the separator as a comma in the second function call, all the items become separated by commas, not just the last item. Since I didn't specify a separator in the first function call, the new item is added using the same separator that was present, in this case a space.

If you want to combine two lists you can use the join($list1, $list2, $separator) function. The items in $list1 will come first and the items in $list2 will come second in the new list. Like append, the separator is optional. If not given, the first separator encountered in $list1 will be used.

1  2  3  4  5  6  7

$list-1: (10px 20px 30px 40px);    $list-2: (50px, 60px, 70px, 80px);    join($list-1, $list-2) => (10px 20px 30px 40px 50px 60px 70px 80px)    join($list-2, $list-1) => (50px, 60px, 70px, 80px, 10px, 20px, 30px, 40px)    join($list-1, $list-2, comma) => (10px, 20px, 30px, 40px, 50px, 60px, 70px, 80px)    join($list-2, $list-1, comma) => (50px, 60px, 70px, 80px, 10px, 20px, 30px, 40px)

Here the first join uses spaces because no separator has been specified and $list1 uses spaces. The second join reverse the two lists and so a comma is used. The last two joins explicitly sets the comma as a separator so it makes no difference which list comes first, at least as far as the separator is concerned.

You can combine the values of multiple lists into a single multidimensional list using the zip($lists…) function. However, the items in each list will be combined in a way you might not expect as you can see in the following example.

1  2  3  4  5

$list-1: (1px 2px 3px);    $list-2: (solid, dashed, dotted);    $list-3: (red green blue);    zip($list-1, $list-2, $list-3) => 1px solid red, 2px dashed green, 3px dotted blue

Notice that the new list contains three nested lists. The first nested list takes the first value in each list that gets zipped, the second nested list takes the second value in each list, and so on.

The length of the new list will be the length of the shortest list being zipped. Here I've added a 4th item to the first 2 lists, but notice that the final result is still the same because $list–3 only has 3 items.

1  2  3  4  5

$list-1: (1px 2px 3px 4px);    $list-2: (solid, dashed, dotted, ridge);    $list-3: (red green blue);    zip($list-1, $list-2, $list-3) => 1px solid red, 2px dashed green, 3px dotted blue

You do need to be careful about separators. Note the lone comma in the first list (after 3px) making it a list with 2 items, the first being a nested list containing 3 values, and the second being a single value. The resulting zipped list now contains a 2 item list as $list–1 only contains 2 items.

1  2  3  4  5

$list-1: (1px 2px 3px, 4px);    $list-2: (solid, dashed, dotted, ridge);    $list-3: (red green blue);    zip($list-1, $list-2, $list-3) => 1px 2px 3px solid red, 4px dashed green

Closing Thoughts

Sass lists are data structures. They may not seem like the most useful thing at first and unless you write your own custom functions or mixins you probably won't work with lists a lot.

However, if you do write your own functions or mixins, lists can become powerful data structures, especially when combined with control directives that let you loop through a list and manipulate a different list item each time through the loop.

We'll get control directives in a couple of weeks, but first we have to go through one last data type, maps, which are a special type of list that you might find easier to work with.

Download a free sample from my book Design Fundamentals.

Join me as I share my creative process and journey as a writer.