Lists in Sass: syntax and use cases with examples

Sass lists are pretty cool.

Lists in Sass are kind of like an arrays, but not. Sass is quite a modern language, and often modern programming languages don’t require you to type things really strictly, so the list syntax in Sass is extremely flexible and thus, confusing.

Defining a list

Simple list:

$horse-types: pony horse mini-horse maxi-pony;

It can be comma separated if that feels more familiar:

$horse-types: pony, horse, mini-horse, maxi-pony;

If the list items have spaces or other special characters they should be quoted:

$horse-types: "pony", "horse", "mini horse", "maxi pony";

The lists can be nested:

$hrs: pony #996633,
      horse #fff,
      mini-horse #333,
      maxi-pony #cc9849

This could be written with parentheses also:

$hrs: (pony #996633)
      (horse #fff)
      (mini-horse #333)
      (maxi-pony #cc9849)

See how to access the values later on.

Noteworthy things about lists

Indexing starts at 1, not from 0, as in all other programming languages.

Everything is a list, variables, booleans, strings, anything. This means, that list functions can be used on, say, strings:

$thing: "Fire Walk with me"
length($thing) # Length is 1

# Drop out quotes, and BOOM, it's a list
$thing: Fire Walk with me
length($thing) # Length is 4

List functions

Here are all the functions we have at our disposal.

Name Description
length($list) Returns the length of a list.
nth($list, $n) Returns a specific item in a list.
set-nth($list, $n, $value) Replaces the nth item in a list.
join($list1, $list2, [$separator]) Joins together two lists into one.
append($list1, $val, [$separator]) Appends a single value onto the end of a list.
zip($lists…) Combines several lists into a single multidimensional list.
index($list, $value) Returns the position of a value within a list.
list-separator(#list) Returns the separator of a list.

Now let’s put them in good use.

Accessing a list

Lets whip our good old test list out.

$horse-types: pony horse mini-horse maxi-pony;

To access an individual node of a list, use the nth() function:

nth($horse-types, 1)
// Results in pony

Negative index values address elements in reverse order, starting from end. A good trick if you need to get the last node in a list:

nth($horse-types, -1)
// Results in maxi-pony

Access list with @for loop:

@for $i from 1 through length($hrs) {
  .horses-#{$i} {
    &:after {
      content: "#{$i}. #{nth($hrs, $i)}";

See the deme below for a tangible example.

@each loops is made for lists, they eats them up for breakfast:

@each $item in $hrs {
    .hrs-photo-#{$item} {
        background: image-url("img/horses/#{$item}.png") no-repeat;

Loop trivia: each loops are common to Ruby, PHP also has foreach loops that server the similar purpose, JavaScript doesn’t have a native each loop (turns out JavaScript has a forEach loop), silly me). jQuery also has .each().

This is a good time for a little demo.

Play with this gist on SassMeister.

Accessing nested lists

Remember the nested list from before:

$horses: pony #996633,
         horse Pink,
         mini-horse #333,
         maxi-pony #cc9849

It has name color pairs, in a way it looks a bit like an associative array, but it’s not, it’s nested list, a different data type. Here’s a cool use case for it:

@each $horse in $horses {
    .horses--#{hth($horse, 1)} {
        background-color: url('#{nth($horse, 2)}');
        background-image: url('img/horse-types/#{nth($horse, 1)}.png') no-repeat;

Here’s the breakdown:

           ┌──Access the first level
@each $horse in $horses {

                    ┌──Now that we're in, access the second level
    .horses--#{hth($horse, 1)} {
                                       ┌──Second level, node 2, the color
        background-color: url('#{nth($horse, 2)}');
                                                       ┌──Second level, node 1, the name
        background-image: url('img/horse-types/#{nth($horse, 1)}.png') no-repeat;

And a demo for clarity:

Play with this gist on SassMeister.

Adding to a list

Use the aptly named append function.

          ┌──The list where you want to append
          |      ┌──The appended value
       ┌──┴─┐  ┌─┴─┐
append($list1, $val, [$separator])
                           └─Just 'comma' or 'space'

The appending is usually done inside a loop:

// The list
$horse-types: pony horse mini-horse maxi-pony;

// The thing to append
$another-type-of-pony: shetland;

// The append itself
$horse-types: append($horse-types, unquote($another-type-of-pony), space);

// Outputs: pony horse mini-horse maxi-pony shetland

Notes about adding to lists:

  • The added value might need to be unquotes with the unquote function.
  • The separator is just an english name for the character, like ‘comma’ or ‘space’.
  • If using comma as the separator value in the original list, and space in the append, then the whole list is converted to space separated list.

Common use cases for lists

For instance, pass a list to a mixin, here’s a little rounded corners example:

@mixin round-corner (
  $corners: 0 0 0 0
) {

  $top-left: nth($corners, 1);
  $top-right: nth($corners, 2);
  $bottom-right: nth($corners, 3);
  $bottom-left: nth($corners, 4);

  border-top-left-radius: $top-left;
  border-top-right-radius: $top-right;
  border-bottom-right-radius: $bottom-right;
  border-bottom-left-radius: $bottom-left;


Lists excel at passing parameter to mixins for example.


There probably could’ve been more examples, but that’s subject for another post. I don’t really have much more to say about lists, lists are prettyy, prettyy, prettyy great.


  • r says:

    @each $horse in $horses {
    .horses–#{hth($horse, 1)} {
    background-color: url(‘#{nth($horse, 2)}’);
    background-image: url(‘img/horse-types/#{nth($horse, 1)}.png’) no-repeat;

    you have an ‘h’ in there, at line 2.
    i think it should be an n

  • Tim Bushell says:

    “I can write pretty much anything here, no one will notice…”

    Pretty much the most truthful thing I’ve seen on the Internet forever.

    Also your post about sass lists was really helpful.

    Tim Bushell
    laughingmyassoff since 2004! I accept for your contribution.

Club-Mate, the beverage →