Sass list.zip() Function

What You’ll Learn

list.zip() belongs to the built-in sass:list module. It pairs items from parallel lists into sublists. This page covers shortest-list length, comma vs space separators, looping with @each, Dart Sass support, and five compiled examples.

What Is list.zip()?

Imagine two columns of sticky notes: sizes on the left, names on the right. Zipping them stacks each row into a small pair—10px short, 50px mid, and so on. That is what list.zip does at compile time.

• list.zip(10px 50px 100px, short mid long) → 10px short, 50px mid, 100px long
• list.zip(10px 50px 100px, short mid) → 10px short, 50px mid (shortest wins)

📝 Syntax

Load the list module, then pass two or more lists:

@use "sass:list";

list.zip($lists...)

Parameters

Return value

📦 Loading sass:list

// Recommended — namespaced
@use "sass:list";
$pairs: list.zip(10px 50px, short mid);

// Optional — bring members into scope
@use "sass:list" as *;
$pairs: zip(10px 50px, short mid);

// Optional — custom namespace
@use "sass:list" as l;
$pairs: l.zip(10px 50px, short mid);

🔍 Separators: Comma Outside, Space Inside

Official docs fix the structure of the result. Input separators do not change that shape.

@use "sass:list";

$z: list.zip(10px 50px 100px, short mid long);

list.separator($z);              // comma
list.separator(list.nth($z, 1)); // space
// first pair → 10px short

📋 list.zip vs list.join

🛠 Compatibility

This is about Sass compilers, not browsers. Compiled CSS only contains the finished utilities or values you emit from the zipped pairs.

Examples Gallery

Each example uses @use "sass:list". Open View Compiled CSS for verified Dart Sass output (official samples where noted).

@use "sass:list";
@use "sass:meta";

@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

.zip {
  --a: #{meta.inspect(list.zip(10px 50px 100px, short mid long))};
  --b: #{meta.inspect(list.zip(10px 50px 100px, short mid))};
  --sep: #{meta.inspect(list.separator(list.zip(10px 50px 100px, short mid long)))};
  --inner: #{meta.inspect(list.separator(list.nth(list.zip(10px 50px 100px, short mid long), 1)))};
}

.zip {
  --a: 10px short, 50px mid, 100px long;
  --b: 10px short, 50px mid;
  --sep: comma;
  --inner: space;
}

@use "sass:list";

$sizes: 10px 50px 100px;
$names: short mid long;
$pairs: list.zip($sizes, $names);

@each $pair in $pairs {
  .gap-#{list.nth($pair, 2)} {
    margin: list.nth($pair, 1);
  }
}

.gap-short {
  margin: 10px;
}

.gap-mid {
  margin: 50px;
}

.gap-long {
  margin: 100px;
}

@use "sass:list";

$colors: #336699 #e67e22 #94a3b8;
$roles: primary accent muted;
$theme: list.zip($roles, $colors);

@each $pair in $theme {
  .swatch-#{list.nth($pair, 1)} {
    background: list.nth($pair, 2);
  }
}

.swatch-primary {
  background: #336699;
}

.swatch-accent {
  background: #e67e22;
}

.swatch-muted {
  background: #94a3b8;
}

@use "sass:list";
@use "sass:meta";

$a: 1 2 3 4;
$b: a b;
$c: x y z;
$z: list.zip($a, $b, $c);

.three {
  --len: #{list.length($z)};
  --all: #{meta.inspect($z)};
}

.three {
  --len: 2;
  --all: 1 a x, 2 b y;
}

@use "sass:list";
@use "sass:meta";

$fonts: Helvetica Arial;
$weights: 400 700;
$fw: list.zip($fonts, $weights);

.card {
  --pair1: #{meta.inspect(list.nth($fw, 1))};
  --pair2: #{meta.inspect(list.nth($fw, 2))};
}

.card {
  --pair1: Helvetica 400;
  --pair2: Arial 700;
}

🚀 Real-World Use Cases

• Utility generators — zip values to class-name tokens.
• Design tokens — keep parallel role/color or size/label lists aligned.
• Mixin APIs — accept two lists and iterate one zipped structure.
• Multi-column data — zip three or more related lists into rows.
• Safe pairing — shortest-list rule avoids out-of-range indexes.

⚠️ Common Pitfalls

• Silent truncation — longer lists lose trailing items without an error.
• Expecting input separators — output is always comma outer / space inner.
• Confusing with join — join flattens; zip builds pairs.
• Forgetting @use — list.zip needs sass:list.
• Misreading sublists — use list.nth($pair, 1) / 2 inside @each.

💡 Best Practices