Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 39 ยท Mixins and Functions

Sass Mixin Arguments and @content Blocks

Make mixins flexible: parameters, default values, keyword and rest arguments, passing blocks of styles with @content, and content arguments with using.

A mixin that always outputs the same thing is useful, but a mixin that accepts arguments is a small tool you can adapt. You can pass values in (sizes, colors, names), give them defaults, collect extra ones, and even hand the mixin a whole block of your own styles with @content. These features turn mixins into the building blocks of responsive helpers, button generators and design-system components.

Arguments

Declare parameters in parentheses after the mixin name. Parameters are variables, so they start with $:

SCSS
@mixin size($width, $height) {
  width: $width;
  height: $height;
}

.avatar { @include size(48px, 48px); }
.banner { @include size(100%, 240px); }

If you pass too few arguments (and there is no default) or too many, Sass reports an error.

Default values

Give a parameter a default with a colon. Callers may then leave it out:

SCSS
@mixin button($bg: #0ea5e9, $color: white, $radius: 6px) {
  background: $bg;
  color: $color;
  border: 0;
  border-radius: $radius;
  padding: 8px 16px;
}

.btn { @include button; }                        // all defaults
.btn-danger { @include button(#dc2626); }        // only the first
.btn-pill { @include button($radius: 99px); }    // by keyword

Defaults can use other parameters declared before them, for example @mixin box($w, $h: $w) makes a square when only $w is given.

Keyword arguments

You can pass arguments by name, in any order, which makes calls readable and lets you skip optional parameters:

SCSS
.card { @include button($radius: 12px, $bg: #7c3aed); }

For mixins with more than two or three parameters, keyword arguments are almost always clearer than positional ones. Name them whenever the meaning is not obvious from the value.

Arguments, defaults and keywords

Variable arguments (rest)

Sometimes you do not know how many values the caller will pass: shadows, transitions, gradient stops. End the parameter list with ... and Sass gathers the extras into a list:

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

.card {
  @include shadow(0 1px 2px rgb(0 0 0 / .2), 0 8px 24px rgb(0 0 0 / .15));
}

The reverse also works: spread a list or map into the arguments of a call with ....

SCSS
$sizes: 48px, 48px;
.avatar { @include size($sizes...); }       // size(48px, 48px)

$box: (width: 100%, height: 200px);
.banner { @include size($box...); }          // keywords from a map

You can combine required parameters with a rest parameter: @mixin transition($property, $others...).

@content: passing a block of styles

Arguments pass values. @content passes styles. The caller writes a block after the @include, and the mixin decides where to place it. This is the foundation of media query helpers:

SCSS
@mixin on-tablet {
  @media (min-width: 768px) {
    @content;
  }
}

.sidebar {
  width: 100%;
  @include on-tablet {
    width: 280px;
  }
}

Compiled, you get .sidebar { width: 100%; } followed by @media (min-width: 768px) { .sidebar { width: 280px; } }. The curly braces after the @include are the content block; Sass drops it where @content stands.

Combine arguments and @content for flexible helpers:

SCSS
@mixin breakpoint($size) {
  @media (min-width: $size) { @content; }
}

.nav {
  display: none;
  @include breakpoint(600px) { display: flex; }
}

Maps will let you replace raw pixel values with names like md, and the responsive breakpoint system project builds on exactly this pattern.

A responsive mixin with @content

Passing arguments to @content

A mixin can hand values back to the content block. Add arguments to @content, and receive them in the caller with using:

SCSS
@mixin dark-mode-aware {
  @content("light");
  @media (prefers-color-scheme: dark) {
    @content("dark");
  }
}

.card {
  @include dark-mode-aware using ($mode) {
    @if $mode == "dark" {
      background: #0f172a;
      color: white;
    } @else {
      background: white;
    }
  }
}

That using ($mode) clause is like a parameter list for the block, so the same styles can be written once and specialized by the mixin. This is the tool for generating rules per breakpoint, per theme or per state.

Passing values back with using

If a mixin does not call @content, you cannot pass it a block: @include foo { ... } is an error. To make a block optional, check with meta.content-exists() from sass:meta.

Check for content and pass sensible defaults

SCSS
@use "sass:meta";

@mixin card($padding: 1rem) {
  padding: $padding;
  border-radius: 8px;
  @if meta.content-exists() {
    @content;
  }
}

With that, @include card; and @include card { color: red; } both work. You will see @if in depth in the conditions lesson.

Good mixin design

  • Give every optional parameter a sensible default.
  • Use keyword arguments at the call site when a call has three or more values.
  • Keep a mixin focused on one job; split big ones.
  • Document public mixins with /// comments (see Comments and output styles).
  • Prefer a mixin with @content over copy-pasting media queries.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you give a mixin parameter a default value?

    Defaults use a colon, just like a declaration.
  2. 2. What does the rest parameter in @mixin shadow($layers...) do?

    The three dots gather all remaining arguments into one list variable.
  3. 3. What is @content for?

    The block written after @include is placed where @content appears.
  4. 4. How does the caller receive arguments passed with @content("dark")?

    @include name using ($param) { ... } declares the content block's parameters.

Summary

  • Mixins take parameters, with defaults, keyword arguments and rest/spread ($args...).
  • @content lets the caller pass styles into a mixin, which is the basis of media query helpers.
  • @content(args) with using (...) hands values back to the block.
  • meta.content-exists() makes a content block optional.
  • Prefer clear defaults and keyword calls for readable mixin use.

Next: Custom functions