Sass Functions — Creating Custom Functions with @function

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

Sass @function directive creates custom functions that compute and return single values, enabling reusable calculations, string manipulation, and value transformations.

What You'll Learn

You will learn how to define custom functions with @function, return values with @return, use functions in property values, and combine functions with mixins.

Why It Matters

Functions compute values dynamically. DodaTech uses custom functions for fluid typography calculations, color transformations, and spacing scale generation.

Real-World Use

Durga Antivirus Pro uses a fluid-size function that calculates clamp() values for responsive typography based on min/max sizes and viewport ranges.

flowchart LR
    A[Mixin Content] --> B[Functions]
    B --> C[@function]
    B --> D[@return]
    B --> E[Parameters]
    B --> F[Usage]
    style B fill:#c69,stroke:#c69,color:#fff
    style C fill:#22c55e,stroke:#16a34a,color:#fff

Basic Function

@function px-to-rem($px) {
  @return ($px / 16px) * 1rem;
}

.card {
  padding: px-to-rem(24px); // 1.5rem
  font-size: px-to-rem(16px); // 1rem
  margin-bottom: px-to-rem(32px); // 2rem
}

Expected output: The compiled CSS uses rem values calculated from px inputs.

Functions with Multiple Parameters

@function fluid-size($min-size, $max-size, $min-vw: 320px, $max-vw: 1200px) {
  $slope: ($max-size - $min-size) / ($max-vw - $min-vw);
  $intercept: $min-size - $slope * $min-vw;
  @return clamp(#{$min-size}, #{$slope * 100vw + $intercept}, #{$max-size});
}

h1 {
  font-size: fluid-size(1.5rem, 3rem);
}

p {
  font-size: fluid-size(1rem, 1.25rem);
}

Expected output: Fluid typography using clamp() with calculated slope and intercept.

Color Functions

@function tint($color, $percentage) {
  @return mix(white, $color, $percentage);
}

@function shade($color, $percentage) {
  @return mix(black, $color, $percentage);
}

.button {
  background: #7c3aed;

  &:hover {
    background: shade(#7c3aed, 10%); // Darker
  }

  &:active {
    background: shade(#7c3aed, 20%); // Even darker
  }
}

.alert-info {
  background: tint(#3b82f6, 90%); // Light blue
  border-color: tint(#3b82f6, 60%);
}

Expected output: Button hover has darker shade, alert uses light tinted background.

Spacing Scale Function

$base-spacing: 1rem;
$scale-ratio: 1.5;

@function space($level) {
  @if $level == 0 {
    @return 0;
  }
  @return $base-spacing * pow($scale-ratio, $level);
}

.card {
  padding: space(1);  // 1.5rem
  margin-bottom: space(2); // 2.25rem
}

.section {
  padding: space(3); // 3.375rem
}

Expected output: Spacing values follow a geometric scale based on the ratio.

Z-Index Function

$z-layers: (
  "modal": 1000,
  "dropdown": 500,
  "navbar": 100,
  "content": 1,
  "background": -1,
);

@function z($layer) {
  @if map-has-key($z-layers, $layer) {
    @return map-get($z-layers, $layer);
  }
  @warn "Unknown layer `#{$layer}` in $z-layers map.";
  @return 0;
}

.modal {
  z-index: z("modal");    // 1000
}

.navbar {
  z-index: z("navbar");   // 100
}

Expected output: Named z-index layers with a single source of truth.

Function vs Mixin

// Function returns a value
@function rem($px) {
  @return ($px / 16px) * 1rem;
}

// Mixin outputs declarations
@mixin rem($property, $px) {
  #{$property}: ($px / 16px) * 1rem;
}

// Using function
.card {
  padding: rem(24px); // Use in any value position
}

// Using mixin
.card {
  @include rem(padding, 24px); // Only for declarations
}

Expected output: Both approaches work, but functions are more flexible (can be used in any value context).

Common Mistakes

1. Using @return Outside of Functions

@return is only valid inside @function blocks. Using it in mixins causes an error.

2. Functions That Output Declarations

Functions return a single value. For multiple declarations, use a mixin instead.

3. Infinite Recursion

A function calling itself without a base case causes infinite recursion and a stack overflow.

4. Not Using @warn for Edge Cases

Use @warn to alert developers when a function receives unexpected inputs.

5. Over-Complicating Simple Operations

If a simple operation like $value / 2 works, you do not need a function. Use functions for complex or repeated logic.

Practice Questions

1. What directive creates a custom function? @function name($params) { ... } creates a custom function.

2. What directive returns a value from a function? @return returns a single value from a function.

3. Can functions call other functions? Yes. Functions can call built-in and custom functions.

4. What is the difference between a function and a mixin? Functions return single values. Mixins output CSS declarations. Functions are used in value positions.

5. How do you handle errors in functions? Use @error to stop compilation or @warn to show a warning.

Challenge

Create a map-deep-get function that safely retrieves values from nested maps. Create a palette($color, $shade) function that returns specific shades from a color palette map.

FAQ

Mini Project

Build a utility library with functions for: rem conversion, fluid sizing (clamp), color tint/shade, spacing scale, and z-index management. Use them in a complete page layout.

What's Next

Learn Sass Built-in Functions for the standard function library. Then explore Sass Color Functions for color manipulation.