---
title: sass:list
---

<%= partial '../snippets/built-in-module-status' %>

<% fun_fact do %>
  In Sass, every [map][] counts as a list that contains a two-element list for
  each key/value pair. For example, `(1: 2, 3: 4)` counts as `(1 2, 3 4)`. So
  all these functions work for maps as well!

  [map]: ../values/maps

  Individual values also count as lists. All these functions treat `1px` as a
  list that contains the value `1px`.
<% end %>


<% function 'list.append($list, $val, $separator: auto)',
            'append($list, $val, $separator: auto)',
            returns: 'list' do %>
  Returns a copy of `$list` with `$val` added to the end.

  If `$separator` is `comma`, `space`, or `slash`, the returned list is
  comma-separated, space-separated, or slash-separated, respectively. If it's
  `auto` (the default), the returned list will use the same separator as `$list`
  (or `space` if `$list` doesn't have a separator). Other values aren't allowed.

  [separator]: ../values/lists

  Note that unlike [`list.join()`](#join), if `$val` is a list it's nested
  within the returned list rather than having all its elements added to the
  returned list.

  <% example(autogen_css: false) do %>
    @debug list.append(10px 20px, 30px); // 10px 20px 30px
    @debug list.append((blue, red), green); // blue, red, green
    @debug list.append(10px 20px, 30px 40px); // 10px 20px (30px 40px)
    @debug list.append(10px, 20px, $separator: comma); // 10px, 20px
    @debug list.append((blue, red), green, $separator: space); // blue red green
    ===
    @debug list.append(10px 20px, 30px)  // 10px 20px 30px
    @debug list.append((blue, red), green)  // blue, red, green
    @debug list.append(10px 20px, 30px 40px)  // 10px 20px (30px 40px)
    @debug list.append(10px, 20px, $separator: comma)  // 10px, 20px
    @debug list.append((blue, red), green, $separator: space)  // blue red green
  <% end %>
<% end %>


<% function 'list.index($list, $value)',
            'index($list, $value)',
            returns: 'number | null' do %>
  Returns the [index][] of `$value` in `$list`.

  [index]: ../values/lists#indexes

  If `$value` doesn't appear in `$list`, this returns [`null`][]. If `$value`
  appears multiple times in `$list`, this returns the index of its first
  appearance.

  [`null`]: ../values/null

  <%= partial 'code-snippets/example-list-index' %>
<% end %>


<% function 'list.is-bracketed($list)',
            'is-bracketed($list)',
            returns: 'boolean' do %>
  Returns whether `$list` has square brackets.

  <% example(autogen_css: false) do %>
    @debug list.is-bracketed(1px 2px 3px); // false
    @debug list.is-bracketed([1px, 2px, 3px]); // true
    ===
    @debug list.is-bracketed(1px 2px 3px)  // false
    @debug list.is-bracketed([1px, 2px, 3px])  // true
  <% end %>
<% end %>


<% function 'list.join($list1, $list2, $separator: auto, $bracketed: auto)',
            'join($list1, $list2, $separator: auto, $bracketed: auto)',
            returns: 'list' do %>
  Returns a new list containing the elements of `$list1` followed by the elements
  of `$list2`.

  <% heads_up do %>
    Because individual values count as single-element lists, it's possible to
    use `list.join()` to add a value to the end of a list. However, *this is not
    recommended*, since if that value is a list it will be concatenated, which
    is probably not what you're expecting.

    Use [`list.append()`](#append) instead to add a single value to a list. Only
    use `list.join()` to combine two lists together into one.
  <% end %>

  If `$separator` is `comma`, `space`, or `slash`, the returned list is
  comma-separated, space-separated, or slash-separated, respectively. If it's
  `auto` (the default), the returned list will use the same separator as
  `$list1` if it has a separator, or else `$list2` if it has a separator, or
  else `space`. Other values aren't allowed.

  If `$bracketed` is `auto` (the default), the returned list will be bracketed
  if `$list1` is. Otherwise, the returned list will have square brackets if
  `$bracketed` is [truthy] and no brackets if `$bracketed` is falsey.

  [truthy]: /documentation/values/booleans#truthiness-and-falsiness

  <% example(autogen_css: false) do %>
    @debug list.join(10px 20px, 30px 40px); // 10px 20px 30px 40px
    @debug list.join((blue, red), (#abc, #def)); // blue, red, #abc, #def
    @debug list.join(10px, 20px); // 10px 20px
    @debug list.join(10px, 20px, $separator: comma); // 10px, 20px
    @debug list.join((blue, red), (#abc, #def), $separator: space); // blue red #abc #def
    @debug list.join([10px], 20px); // [10px 20px]
    @debug list.join(10px, 20px, $bracketed: true); // [10px 20px]
    ===
    @debug list.join(10px 20px, 30px 40px)  // 10px 20px 30px 40px
    @debug list.join((blue, red), (#abc, #def))  // blue, red, #abc, #def
    @debug list.join(10px, 20px)  // 10px 20px
    @debug list.join(10px, 20px, comma)  // 10px, 20px
    @debug list.join((blue, red), (#abc, #def), space)  // blue red #abc #def
    @debug list.join([10px], 20px)  // [10px 20px]
    @debug list.join(10px, 20px, $bracketed: true)  // [10px 20px]
  <% end %>
<% end %>


<% function 'list.length($list)', 'length($list)', returns: 'number' do %>
  Returns the length of `$list`.

  This can also return the number of pairs in a map.

  <% example(autogen_css: false) do %>
    @debug list.length(10px); // 1
    @debug list.length(10px 20px 30px); // 3
    @debug list.length((width: 10px, height: 20px)); // 2
    ===
    @debug list.length(10px)  // 1
    @debug list.length(10px 20px 30px)  // 3
    @debug list.length((width: 10px, height: 20px))  // 2
  <% end %>
<% end %>


<% function 'list.separator($list)',
            'list-separator($list)',
            returns: 'unquoted string' do %>
  Returns the name of the separator used by `$list`, either `space`, `comma`, or
  `slash`.

  If `$list` doesn't have a separator, returns `space`.

  <% example(autogen_css: false) do %>
    @debug list.separator(1px 2px 3px); // space
    @debug list.separator(1px, 2px, 3px); // comma
    @debug list.separator('Helvetica'); // space
    @debug list.separator(()); // space
    ===
    @debug list.separator(1px 2px 3px)  // space
    @debug list.separator(1px, 2px, 3px)  // comma
    @debug list.separator('Helvetica')  // space
    @debug list.separator(())  // space
  <% end %>
<% end %>


<% function 'list.nth($list, $n)', 'nth($list, $n)' do %>
  Returns the element of `$list` at [index][] `$n`.

  [index]: ../values/lists#indexes

  If `$n` is negative, it counts from the end of `$list`. Throws an error if
  there is no element at index `$n`.

  <%= partial 'code-snippets/example-list-nth' %>
<% end %>


<% function 'list.set-nth($list, $n, $value)',
            'set-nth($list, $n, $value)',
            returns: 'list' do %>
  Returns a copy of `$list` with the element at [index][] `$n` replaced with
  `$value`.

  [index]: ../values/lists#indexes

  If `$n` is negative, it counts from the end of `$list`. Throws an error if
  there is no existing element at index `$n`.

  <% example(autogen_css: false) do %>
    @debug list.set-nth(10px 20px 30px, 1, 2em); // 2em 20px 30px
    @debug list.set-nth(10px 20px 30px, -1, 8em); // 10px, 20px, 8em
    @debug list.set-nth((Helvetica, Arial, sans-serif), 3, Roboto); // Helvetica, Arial, Roboto
    ===
    @debug list.set-nth(10px 20px 30px, 1, 2em); // 2em 20px 30px
    @debug list.set-nth(10px 20px 30px, -1, 8em); // 10px, 20px, 8em
    @debug list.set-nth((Helvetica, Arial, sans-serif), 3, Roboto); // Helvetica, Arial, Roboto
  <% end %>
<% end %>


<% function 'list.slash($elements...)', returns: 'list' do %>
  Returns a slash-separated list that contains `$elements`.

  <% heads_up do %>
    This function is a temporary solution for creating slash-separated lists.
    Eventually, they'll be written literally with slashes, as in
    `1px / 2px / solid`, but for the time being [slashes are used for division]
    so Sass can't use them for new syntax until the old syntax is removed.

    [slashes are used for division]: ../breaking-changes/slash-div
  <% end %>

  <% example(autogen_css: false) do %>
    @debug list.slash(1px, 50px, 100px); // 1px / 50px / 100px
    ===
    @debug list.slash(1px, 50px, 100px)  // 1px / 50px / 100px
  <% end %>
<% end %>


<% function 'list.zip($lists...)', 'zip($lists...)', returns: 'list' do %>
  Combines every list in `$lists` into a single list of sub-lists.

  Each element in the returned list contains all the elements at that position
  in `$lists`. The returned list is as long as the shortest list in `$lists`.

  The returned list is always comma-separated and the sub-lists are always
  space-separated.

  <% example(autogen_css: false) do %>
    @debug list.zip(10px 50px 100px, short mid long); // 10px short, 50px mid, 100px long
    @debug list.zip(10px 50px 100px, short mid); // 10px short, 50px mid
    ===
    @debug list.zip(10px 50px 100px, short mid long)  // 10px short, 50px mid, 100px long
    @debug list.zip(10px 50px 100px, short mid)  // 10px short, 50px mid
  <% end %>
<% end %>