Sass @mixin and @include

What You’ll Learn

Sass mixins let you define styles once and reuse them anywhere with @include. This page covers arguments, defaults, keyword args, argument lists, @content blocks, and five compiled examples.

What Are Mixins?

Official docs: mixins allow you to define styles that can be re-used throughout your stylesheet. They make it easy to avoid non-semantic classes like .float-left, and to distribute collections of styles in libraries.

• Defined with @mixin name { … } or @mixin name($args…) { … }.
• Included with @include name or @include name($args…).
• Names cannot begin with --.
• Hyphens and underscores are identical: reset-list = reset_list.
• Mixin names never appear in CSS—only the styles they generate.

📝 Syntax

@mixin reset-list {
  margin: 0;
  padding: 0;
  list-style: none;
}

nav ul {
  @include reset-list;
}

@mixin square($size, $radius: 0) {
  width: $size;
  height: $size;
  @if $radius != 0 {
    border-radius: $radius;
  }
}

.avatar {
  @include square(100px, $radius: 4px);
}

🔢 Arguments

Official docs: arguments let you customize a mixin each time it is included. Declare variable names in parentheses after the mixin name, then pass matching SassScript expressions in @include.

Optional arguments

Give a default with $name: value. Callers can omit that argument. Defaults can be any expression and may refer to earlier arguments.

Keyword arguments

Pass by name: @include square(100px, $radius: 4px). Especially helpful for booleans and multiple optional values.

🔀 Taking Arbitrary Arguments

Official docs: if the last parameter ends in ..., extra positional arguments become a list (an argument list).

• Pass a list with $list... to expand positional args.
• Pass a map with $map... to expand keyword args.
• Use meta.keywords($args) to read extra keyword arguments as a map.
• Forward everything to another mixin with @include other($args...).

📄 Content Blocks (@content)

Official docs: a mixin can take an entire block of styles. Declare @content in the mixin body; callers pass styles in braces after @include.

@mixin hover {
  &:not([disabled]):hover {
    @content;
  }
}

.button {
  border: 1px solid black;
  @include hover {
    border-width: 2px;
  }
}

• A mixin may include @content more than once.
• Content blocks are lexically scoped—they see variables from the include site, not from inside the mixin.
• Pass values into the block with @content($args…) and accept them with @include … using ($args…) (Dart Sass 1.15+).

📦 Mixins With @use

In modern Sass, put mixins in a partial and load them with a namespace:

// _buttons.scss
@mixin primary {
  background: #222;
  color: #fff;
}

// style.scss
@use "buttons";

.cta {
  @include buttons.primary;
}

Examples Gallery

Each example defines and includes mixins at compile time. Open View Compiled CSS for verified output.

@mixin reset-list {
  margin: 0;
  padding: 0;
  list-style: none;
}

@mixin horizontal-list {
  @include reset-list;

  li {
    display: inline-block;
    margin: {
      left: -2px;
      right: 2em;
    }
  }
}

nav ul {
  @include horizontal-list;
}

nav ul {
  margin: 0;
  padding: 0;
  list-style: none;
}
nav ul li {
  display: inline-block;
  margin-left: -2px;
  margin-right: 2em;
}

@mixin rtl($property, $ltr-value, $rtl-value) {
  #{$property}: $ltr-value;

  [dir=rtl] & {
    #{$property}: $rtl-value;
  }
}

.sidebar {
  @include rtl(float, left, right);
}

.sidebar {
  float: left;
}
[dir=rtl] .sidebar {
  float: right;
}

@mixin replace-text($image, $x: 50%, $y: 50%) {
  text-indent: -99999em;
  overflow: hidden;
  text-align: left;

  background: {
    image: $image;
    repeat: no-repeat;
    position: $x $y;
  }
}

@mixin square($size, $radius: 0) {
  width: $size;
  height: $size;

  @if $radius != 0 {
    border-radius: $radius;
  }
}

.mail-icon {
  @include replace-text(url("/images/mail.svg"), 0);
}

.avatar {
  @include square(100px, $radius: 4px);
}

.mail-icon {
  text-indent: -99999em;
  overflow: hidden;
  text-align: left;
  background-image: url("/images/mail.svg");
  background-repeat: no-repeat;
  background-position: 0 50%;
}

.avatar {
  width: 100px;
  height: 100px;
  border-radius: 4px;
}

@mixin hover {
  &:not([disabled]):hover {
    @content;
  }
}

.button {
  border: 1px solid black;
  @include hover {
    border-width: 2px;
  }
}

.button {
  border: 1px solid black;
}
.button:not([disabled]):hover {
  border-width: 2px;
}

@use "sass:list";

@mixin order($height, $selectors...) {
  @for $i from 0 to list.length($selectors) {
    #{list.nth($selectors, $i + 1)} {
      position: absolute;
      height: $height;
      margin-top: $i * $height;
    }
  }
}

@include order(150px, "input.name", "input.address", "input.zip");

input.name {
  position: absolute;
  height: 150px;
  margin-top: 0px;
}

input.address {
  position: absolute;
  height: 150px;
  margin-top: 150px;
}

input.zip {
  position: absolute;
  height: 150px;
  margin-top: 300px;
}

🚀 Real-World Use Cases

• Design-system primitives — buttons, cards, focus rings.
• RTL helpers — flip properties with one include.
• Responsive wrappers — @content inside breakpoints.
• Icon / image replacement — shared background text tricks.
• Library APIs — ship mixins via @use / @forward.

⚠️ Common Pitfalls

• Expecting a CSS class — mixin names are not selectors.
• Missing required args — every non-default parameter must be passed.
• Content scope surprises — @content cannot see mixin-local variables.
• Overusing mixins for one-liners — a variable or plain CSS may be clearer.
• Huge CSS output — including a large mixin everywhere duplicates rules.

💡 Best Practices