Sass Mixin Arguments — Parameters, Defaults, and Keyword Args

In this tutorial, you will learn about Sass Mixin Arguments. We cover key concepts, practical examples, and best practices to help you master this topic.

Sass mixin arguments make mixins flexible by accepting parameters with default values, keyword arguments, rest parameters for variable-length inputs, and argument lists.

What You'll Learn

You will learn how to create mixins with required and optional parameters, set defaults, use keyword arguments, accept variable arguments with ..., and work with argument lists.

Why It Matters

Parameterized mixins handle variations without duplication. DodaTech uses a single button-style mixin with parameters for background, text color, and size.

Real-World Use

Durga Antivirus Pro uses a single card($padding, $shadow, $border-color) mixin to generate 6 different card variants from one definition.

flowchart LR
    A[Mixins Basics] --> B[Mixin Arguments]
    B --> C[Required Params]
    B --> D[Default Values]
    B --> E[Keyword Args]
    B --> F[Rest Params]
    style B fill:#c69,stroke:#c69,color:#fff
    style C fill:#22c55e,stroke:#16a34a,color:#fff

Required Arguments

@mixin button-style($bg, $text) {
  background-color: $bg;
  color: $text;
  padding: 0.5rem 1rem;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.btn-primary {
  @include button-style(#7c3aed, white);
}

.btn-danger {
  @include button-style(#ef4444, white);
}

Expected output: Two button variants with different background colors, both generated from one mixin.

Default Values

@mixin card($padding: 1rem, $shadow: 0 2px 4px rgba(0,0,0,0.1), $radius: 8px) {
  background: white;
  padding: $padding;
  box-shadow: $shadow;
  border-radius: $radius;
}

.card-default {
  @include card; // Uses all defaults
}

.card-large {
  @include card(2rem); // Only override padding
}

.card-custom {
  @include card(1rem, 0 4px 12px rgba(0,0,0,0.2), 12px);
}

Expected output: Three cards with different padding, shadows, and radii, all from the same mixin.

Keyword Arguments

Use named parameters for clarity, especially when skipping optional ones:

@mixin button($bg: #7c3aed, $color: white, $size: md, $full-width: false) {
  background: $bg;
  color: $color;
  padding: if($size == sm, 0.25rem 0.5rem, if($size == md, 0.5rem 1rem, 0.75rem 1.5rem));
  width: if($full-width, 100%, auto);
}

.btn-download {
  @include button($bg: #059669, $full-width: true);
}

.btn-small {
  @include button($size: sm);
}

Expected output: A download button with custom background and full width, and a small button, both with clear keyword argument syntax.

Rest Parameters

Accept multiple values with ...:

@mixin margins($values...) {
  margin: $values;
}

.condensed {
  @include margins(10px);          // All sides
}

.normal {
  @include margins(10px 20px);     // Vertical horizontal
}

.verbose {
  @include margins(10px 20px 10px 20px); // Top right bottom left
}

Expected output: The mixin accepts 1 to 4 values and passes them directly to the margin property.

Argument Lists

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

.card {
  @include box-shadow(0 2px 4px rgba(0,0,0,0.1));
}

.card-prominent {
  @include box-shadow(
    0 4px 6px rgba(0,0,0,0.1),
    0 2px 4px rgba(0,0,0,0.06)
  );
}

Expected output: The card has a single shadow. The prominent card has multiple shadows from one mixin call.

Passing Arguments Through

@mixin themed-button($bg, $color, $size: md) {
  @include button-base($bg, $color);
  @include button-size($size);
}

// Or pass all arguments through
@mixin wrapper-mixin($args...) {
  @include target-mixin($args...);
}

Expected output: Arguments pass through wrapper mixins to the actual implementation.

Argument Validation

@mixin container($max-width) {
  @if type-of($max-width) != number {
    @error "container mixin requires a number. Got #{type-of($max-width)}: #{$max-width}";
  }

  max-width: $max-width;
  margin: 0 auto;
  padding: 0 1rem;
}

.container {
  @include container(1200px);  // Works
  // @include container(full); // Error
}

Expected output: The compiled version works correctly. Invalid inputs produce clear error messages.

Common Mistakes

1. Forgetting Required Arguments

Calling a mixin without a required argument causes a compilation error. Use defaults for optional parameters.

2. Argument Order Mismatch

Using positional arguments, order matters. Provide all required before optional, or use keyword arguments.

3. Type Errors in Arguments

Passing a string where a number is expected can cause invalid CSS. Validate arguments with type-of checks.

4. Too Many Arguments

A mixin with 8+ parameters is hard to use. Consider splitting into smaller mixins or using a configuration map.

5. Not Using Keyword Arguments for Readability

@include card(1rem, 0 2px 4px rgba(0,0,0,0.1), 8px) is unclear. Use @include card($padding: 1rem) for readability.

Practice Questions

1. How do you set a default value for a mixin parameter? @mixin name($param: default) { ... } assigns a default value.

2. How do you use keyword arguments when including a mixin? @include mixin($arg1: value1, $arg2: value2) uses named parameters.

3. How do you accept an unknown number of arguments? Use rest parameters: @mixin name($args...) { ... }.

4. What happens if a required argument is missing? Sass throws a compilation error indicating the missing argument.

5. How do you validate argument type inside a mixin? Use @if type-of($arg) != number { @error "..."; } for validation.

Challenge

Create a button-variant mixin with parameters for background, color, border, hover-background, hover-color, padding, and font-size (all with sensible defaults). Use it to generate primary, secondary, danger, and ghost button variants.

FAQ

Mini Project

Create a themed-element mixin with parameters for background, text, border, hover, and active colors. Use it to generate styles for buttons, alerts, and badges from a single mixin with different arguments.

What's Next

Learn about Sass Mixin Content for passing style blocks with @content. Then explore Sass Functions for computed values.