Default Values (!default)
Let users override a variable while providing a fallback.
$variable: value !default;The !default flag assigns a value to a variable only if it is not already defined (or is null). This makes libraries and modules configurable.
When another file configures your module with @use ... with (...), the configured value wins; otherwise your !default value is used. This is the standard pattern for themeable Sass libraries.
Example
// _config.scss
$primary: #CC6699 !default;
$radius: 4px !default;
// Because these use !default, a consumer can override them:
// @use 'config' with ($primary: #6699CC, $radius: 8px);
.btn {
background: $primary;
border-radius: $radius;
}When to use it
- A UI library defines $primary-color: #2563eb !default so any project can override the brand color before @use-ing the library without forking its source.
- A mixin library provides sensible spacing defaults with !default variables, letting consumers tweak them via @use 'library' with ($space-unit: 10px).
- A theming package exposes all its config variables as !default so downstream projects only need to set the variables they want to change.
More examples
Basic !default declaration
Marks three config variables with !default so consumers can override any of them before loading this file.
// _config.scss
$primary: #2563eb !default;
$font-size: 1rem !default;
$radius: 4px !default;Overriding !default via @use with
Uses the @use ... with () syntax to override only the variables that differ from the library defaults, leaving the rest unchanged.
// styles.scss
@use 'config' with (
$primary: #e74c3c,
$radius: 0
);
.btn {
background: config.$primary;
border-radius: config.$radius;
}Conditional default from another variable
Computes a default value from another variable so overriding $base-size automatically scales the heading unless explicitly set.
$base-size: 16px;
$heading-size: $base-size * 2 !default;
h1 { font-size: $heading-size; }
Discussion