Sass @function Rule

What You’ll Learn

Sass @function lets you define complex operations on SassScript values and reuse them throughout your stylesheet. This page covers @return, arguments, defaults, keywords, argument lists, early returns, how functions differ from mixins, and five compiled examples.

What Are Sass Functions?

Official docs: functions allow you to define complex operations on SassScript values that you can re-use throughout your stylesheet. They make it easy to abstract out common formulas and behaviors in a readable way.

• Defined with @function name($args…) { … }.
• Called with normal CSS function syntax: rem(24px), sum(1px, 2px).
• Must end with @return (the value used as the call result).
• Names cannot begin with --.
• Hyphens and underscores are identical: str-insert = str_insert.
• Function names never appear in CSS—only the returned values do.

📝 Syntax

Write @function (<arguments…>) { … }. The body may contain universal statements (variables, control flow, other function calls) plus @return.

@use "sass:math";

@function rem($px, $base: 16px) {
  @return math.div($px, $base) * 1rem;
}

.title {
  font-size: rem(24px); // 1.5rem
}

📤 The @return At-Rule

Official docs: @return indicates the value to use as the result of calling a function. It is only allowed inside @function, and each function must end with a @return.

• When @return is hit, the function ends immediately.
• Early returns are great for edge cases without wrapping everything in @else.
• You can have multiple @return paths; exactly one runs per call.

🔢 Arguments

Official docs: arguments let you customize a function each time it is called. Declare variable names in parentheses after the function name, then pass matching SassScript expressions when you call it.

Optional arguments

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

Keyword arguments

Pass by name: rem(8px, $base: 16px) or built-ins like color.scale($c, $lightness: 40%). 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 function with @return other($args...).

📚 Other Functions

Besides your own @function rules, Sass ships a large built-in library (math, color, string, list, map, meta, and more). Host-language custom functions are also possible in Sass implementations. And any unknown call that is not a Sass function compiles to a plain CSS function.

// Unknown names become CSS (unless they use Sass-only arg syntax)
.card {
  background: var(--main-bg-color);
  background-image: radial-gradient(#f2ece4, #e1d7d2);
}

📦 Functions With @use

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

// _units.scss
@use "sass:math";

@function rem($px, $base: 16px) {
  @return math.div($px, $base) * 1rem;
}

// style.scss
@use "units";

.title {
  font-size: units.rem(24px);
}

Examples Gallery

Each example defines and calls functions at compile time. Open View Compiled CSS for verified output.

@use "sass:list";

@function fibonacci($n) {
  $sequence: 0 1;
  @for $_ from 1 through $n {
    $new: list.nth($sequence, list.length($sequence))
      + list.nth($sequence, list.length($sequence) - 1);
    $sequence: list.append($sequence, $new);
  }
  @return list.nth($sequence, list.length($sequence));
}

.sidebar {
  float: left;
  margin-left: fibonacci(4) * 1px;
}

.sidebar {
  float: left;
  margin-left: 5px;
}

@use "sass:math";

@function rem($px, $base: 16px) {
  @return math.div($px, $base) * 1rem;
}

.title {
  font-size: rem(24px);
  padding: rem(8px, $base: 16px);
}

.title {
  font-size: 1.5rem;
  padding: 0.5rem;
}

@use "sass:color";

@function invert-hue($color, $amount: 100%) {
  $inverse: color.adjust($color, $hue: 180deg);
  @return color.mix($inverse, $color, $amount);
}

$primary-color: #036;

.header {
  background-color: invert-hue($primary-color, 80%);
}

.banner {
  color: color.scale($primary-color, $lightness: 40%);
}

.header {
  background-color: #523314;
}

.banner {
  color: #0a85ff;
}

@function sum($numbers...) {
  $sum: 0;
  @each $number in $numbers {
    $sum: $sum + $number;
  }
  @return $sum;
}

$widths: 50px, 30px, 100px;

.micro {
  width: sum(50px, 30px, 100px);
  min-width: sum($widths...);
}

.micro {
  width: 180px;
  min-width: 180px;
}

@use "sass:string";
@use "sass:meta";

@function str-insert($string, $insert, $index) {
  // Avoid extra work when the string is empty.
  @if string.length($string) == 0 {
    @return $insert;
  }

  $before: string.slice($string, 1, $index);
  $after: string.slice($string, $index + 1);
  @return $before + $insert + $after;
}

.probe {
  --early: #{meta.inspect(str-insert("", "Hi", 1))};
  --mid: #{meta.inspect(str-insert("Hello", "-", 3))};
}

.probe {
  --early: "Hi";
  --mid: "Hel-lo";
}

🚀 Real-World Use Cases

• Unit conversion — rem(), fluid clamp helpers.
• Design tokens — tint/shade, contrast, spacing scales.
• Math helpers — ratios, Fibonacci-style sequences, clamp math.
• String utilities — insert, strip, build class name fragments.
• Library APIs — ship pure helpers via @use / @forward.

⚠️ Common Pitfalls

• Expecting CSS output — a function alone emits nothing; you must use its return value.
• Side effects in functions — prefer mixins for writing styles or globals.
• Missing @return — every path through a function must return.
• Typo becomes CSS — unknown names pass through as plain CSS functions.
• Confusing with mixins — no @include and no @content for functions.

💡 Best Practices