Mixin and Function Parameters

How Sass Parameters Work

Parameters are declared inside the parentheses of a @mixin or @function definition, optionally with a default value. At the call site, arguments can be passed positionally (in order) or by name, which can appear in any order and improves readability for optional parameters.

@mixin box($width, $height: $width, $radius: 0) {
  width: $width;
  height: $height;
  border-radius: $radius;
}

.square {
  @include box(100px);           // height defaults to $width, radius to 0
}

.rounded-rect {
  @include box(200px, $height: 80px, $radius: 12px);
}

Notice $height: $width as a default, a later parameter can default to the value of an earlier one.

Parameter Syntax Forms

@mixin name($a, $b: default, $rest...) { ... }
@include name($a, $b: value, $c, $d);

• $param: default gives a parameter a fallback value if the caller omits it.
• $rest... collects any remaining positional arguments into a list.
• Named arguments ($param: value) can appear in any order at the call site.
• Positional arguments must come before named arguments in the same call.

Parameters Cheatsheet

Common parameter patterns for mixins and functions alike.

Default Parameter Values

Default values make a parameter optional. They are evaluated at call time, so a default can reference another parameter, or even call a function, as long as everything it depends on is already available.

@function spacing($multiplier, $base: 8px) {
  @return $multiplier * $base;
}

.stack {
  gap: spacing(2); // => 16px, using the default $base
}

Variable Argument Lists With ...

The ... syntax, called "argument globbing", lets a mixin or function accept any number of positional arguments, collected into a single list variable inside the body.

@mixin box-shadows($shadows...) {
  box-shadow: $shadows;
}

.card {
  @include box-shadows(
    0 1px 2px rgba(0, 0, 0, 0.05),
    0 4px 8px rgba(0, 0, 0, 0.08)
  );
}

Any number of shadow values can be passed; they're joined into one comma-separated box-shadow value.

Spreading a List as Arguments

The same ... syntax can also be used at the call site to "spread" an existing list or map into a function or mixin's positional (or keyword) arguments, the reverse of argument globbing.

$shadow-list: (0 1px 2px rgba(0, 0, 0, 0.05), 0 4px 8px rgba(0, 0, 0, 0.08));

.card {
  @include box-shadows($shadow-list...);
}

Common Mistakes

• Passing a positional argument after a named argument in the same call, which is invalid syntax.
• Assuming default parameter values are evaluated once globally, they're actually evaluated fresh at every call.
• Forgetting the ... when trying to spread an existing list into a mixin or function call, resulting in the whole list being treated as a single argument.
• Overloading a single mixin with too many optional parameters instead of splitting it into smaller, more focused mixins.

Key Takeaways

• Parameters can have default values, evaluated fresh at every call.
• Named arguments can appear in any order and are especially useful for optional parameters.
• The ... syntax collects extra positional arguments into a list (argument globbing) or spreads a list into arguments (the reverse).
• Positional arguments must always precede named arguments within the same call.