Sass - Function Directives

Sass - Function Directives (@function)

Sass allows you to define your own custom functions using the @function directive. These functions encapsulate reusable logic, perform calculations, or manipulate Sass values (like colors, strings, numbers, lists, maps), and return a single value. They are essential for creating more sophisticated and maintainable stylesheets.

Defining a Function

You define a function using @function, followed by the function name, an argument list in parentheses (), and a block {} containing the function’s logic. The function must end with a @return directive specifying the value to be returned.

Syntax:

@function function-name($arg1, $arg2: default-value) {
  // SassScript logic using arguments
  $result: ...; // Perform calculations or manipulations

  @return $result; // Must return a value
}

Key aspects:

• Naming: Function names follow the same rules as variables (can use hyphens and underscores interchangeably). It’s good practice to use prefixes (e.g., my-prefix-func-name) or namespaces (@use) to avoid conflicts.
• Arguments: Functions can accept zero or more arguments. Arguments can have default values, making them optional.
• Return Value: A function MUST return a single value using @return. This value can be of any Sass data type (number, string, color, list, map, boolean, null).
• Scope: Variables defined inside a function are local to that function unless explicitly declared global (using !global, which is generally discouraged).

Example: Calculating aspect ratio padding

@use 'sass:math';

// Calculates the percentage padding-top/bottom for a fixed aspect ratio container
@function aspect-ratio-padding($width, $height) {
  @return math.div($height, $width) * 100%;
}

.aspect-ratio-16-9 {
  position: relative;
  height: 0;
  padding-bottom: aspect-ratio-padding(16, 9); // e.g., 56.25%

  > * { // Direct child fills the container
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
  }
}

Using Functions

You call a function just like built-in Sass functions, using its name followed by parentheses containing any required arguments.

.element {
  // Call function and use its return value
  width: calculate-width(100px, 2);
  color: adjust-color($base-color, $lightness: 10%);
}

Functions can be used anywhere a SassScript expression is allowed, such as in property values, variable assignments, or within control directives (@if, @each, etc.).

Functions vs. Mixins

It’s important to understand the difference between functions (@function) and mixins (@mixin):

• Functions (@function): Compute and return a single value. They are used for calculations, transformations, and logic that results in a value usable within CSS properties or other SassScript expressions.
• Mixins (@mixin): Define reusable blocks of styles (CSS declarations). They are included using @include and generate CSS rules directly. They don’t return values but output style declarations.

Use a function when you need to compute a value (e.g., a color, a size, a string). Use a mixin when you need to apply a set of styles.

Built-in Modules

Sass provides powerful built-in modules (like sass:math, sass:color, sass:string, sass:list, sass:map) that offer many useful functions. You should leverage these whenever possible before writing your own custom functions.

@use 'sass:color';

$adjusted-color: color.scale(blue, $lightness: -20%, $saturation: 15%);

.button {
  background-color: $adjusted-color;
}

Refer to the official Sass documentation for a complete list of built-in modules and functions: https://sass-lang.com/documentation/modules