Configuring Modules with
Override a module's !default variables when you load it.
Syntax
@use 'library' with ($primary: blue, $radius: 8px);Modules can be configured at load time using @use ... with (...). This overrides any variables in the loaded module that were declared with the !default flag.
This is the modern, explicit replacement for the old trick of setting variables before an @import. It makes libraries themeable in a controlled way.
Example
// _theme.scss
$primary: #CC6699 !default;
$font-size: 16px !default;
body { color: $primary; font-size: $font-size; }
// main.scss — override the defaults
@use 'theme' with (
$primary: #6699CC,
$font-size: 18px
);
/* body { color: #6699CC; font-size: 18px; } */When to use it
- An agency creates a white-label UI kit and lets each client project override the brand color and font via @use 'ui-kit' with ($brand: #e74c3c).
- A developer ships a reusable grid module with a configurable column count so projects can use 12 or 16 columns without editing the library source.
- A team creates a spacing scale module with a configurable base unit so every project can set $space-unit: 10px and get a consistently scaled system.
More examples
Configuring a module on load
Overrides the grid module's default column count and gutter size at load time using the with () configuration syntax.
// _grid.scss
$columns: 12 !default;
$gutter: 1rem !default;
// main.scss
@use 'grid' with (
$columns: 16,
$gutter: 1.5rem
);
.row { gap: grid.$gutter; }Theming a UI kit for a client
A client project configures the shared UI kit's brand tokens without touching the library source, enabling per-project theming.
// client-a/main.scss
@use 'ui-kit' with (
$primary: #dc2626,
$font-sans: 'Roboto, sans-serif',
$radius: 0
);
.page { font-family: ui-kit.$font-sans; }Forwarding configuration downstream
Demonstrates how a dependent variable (!default) re-derives its value from the configured base variable when the module is loaded.
// _theme.scss
@use 'sass:color';
@use 'tokens' as t;
$primary: t.$primary !default;
$hover: color.adjust($primary, $lightness: -10%) !default;
// Downstream: @use 'theme' with ($primary: #7c3aed)
// $hover is automatically recalculated from the new $primary.
Discussion