Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 39 ยท Modules and Architecture

Module Configuration, Defaults and load-css

Configure Sass modules with !default and @use with, pass configuration through @forward, share placeholders across files, and load CSS dynamically with meta.load-css.

A reusable stylesheet is much more useful when the person using it can change a few decisions: the brand color, the base font size, the breakpoint where the layout switches. In Sass those decisions are configurable variables. A module declares them with !default, and the file that loads the module overrides them with with (...). This is the mechanism every well-built Sass library uses, and it is how you should build your own shared styles.

If you have not read it yet, start with @use and @forward, because everything here builds on namespaces and re-exporting.

!default: a variable with a fallback

A variable marked !default is only assigned if it does not already have a value (or has the value null):

SCSS
$radius: 4px !default;
$radius: 20px !default;   // ignored, $radius already has a value

Alone this looks pointless. It becomes useful when the value can come from outside the file, which is exactly what configuration does.

@use ... with (...)

The loading file passes values in a parenthesized map-like list. Keys are variable names without the $:

SCSS
// _buttons.scss
$radius: 4px !default;
$brand: #4f46e5 !default;

.button {
  border-radius: $radius;
  background: $brand;
}

// main.scss
@use "buttons" with ($radius: 999px, $brand: #0f766e);

The configured values replace the !default ones before the module's code runs, so the CSS the module emits already reflects them.

Configuring a module with `with`

Delete the with (...) block to see the defaults. Add $pad: 1rem 2.5rem to the configuration.

Rules and errors

  • You can only configure variables that exist in the module and are marked !default. Anything else is an error, which catches typos like $brnad.
  • You can configure a module only the first time it is loaded. If _a.scss already did @use "buttons" with no configuration, a later @use "buttons" with (...) fails with "This module was already loaded, so it can't be configured using with". Load and configure in the entry file first.
  • A module's own $var: value !default sees the configured value, so derived defaults work: $hover: darken($brand, 8%) !default is computed from the configured brand. (Use color.adjust rather than darken in new code, see built-in modules.)

Configuring through an index file

A library often has an _index.scss that forwards several partials. To let users configure variables of the forwarded modules, forward them with with, or use @forward ... with to set library defaults that users may still override:

SCSS
// library/_index.scss
@forward "buttons" with ($radius: 8px !default, $brand: #4f46e5 !default);

!default inside the @forward ... with list means "use this unless the person loading me passes something else". Without !default, the value is fixed and cannot be changed by consumers.

SCSS
// main.scss
@use "library" with ($brand: crimson);   // radius stays 8px
Library defaults with @forward ... with

The library changed the default radius to a pill shape, and the page changed only the color.

Privacy and the public surface

Configuration only makes sense for public variables. Keep implementation details private with a leading - or _:

SCSS
$gap: 1rem !default;          // public, configurable
$-gap-double: $gap * 2;       // private, derived

Document your configurable variables in a comment at the top of the file, as you would document function arguments. Nothing else about the module is a contract.

Placeholders across files

A placeholder selector (%name) is private to its module unless you forward the module, and @extend works across files when both are loaded in the same compilation:

SCSS
// _base.scss
%visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  overflow: hidden;
  clip-path: inset(50%);
}

// _forms.scss
@use "base";
.field-hint-sr { @extend %visually-hidden; }

For @extend to find a placeholder, the file that defines it must be in the module graph of the file that extends it. A mixin is often the safer choice for anything that takes arguments or must work across independent entry points.

meta.load-css: include a stylesheet's CSS

Sometimes you do not want a module's members; you want its CSS, perhaps inside a selector, perhaps several times. meta.load-css() is a mixin that loads a stylesheet and emits its CSS where you include it:

SCSS
@use "sass:meta";

.dark-mode {
  @include meta.load-css("themes/dark");
}

The module is evaluated with its CSS nested under .dark-mode. You can also pass configuration as a map whose keys are variable names (strings, no $):

SCSS
@include meta.load-css("button", $with: ("radius": 2px, "brand": navy));

Differences from @use:

  • load-css can be called more than once, so the CSS can be emitted more than once, for example once globally and once nested. A module loaded by @use is emitted only once. The module itself is still evaluated once: configuration given on the first load applies to every later load, and trying to configure it again is an error.
  • It does not give you access to the module's variables, mixins or functions.
  • The URL is a string you can build dynamically, but it must still be resolvable by the compiler.
Loading CSS inside a selector

Read the compiled CSS: the second copy is .sidebar .tag, a scoped copy of the same rules with the same configuration. Try configuring the module in the second include instead and read the error.

Inspecting a module

The sass:meta module can look inside a loaded module:

SCSS
@use "sass:meta";
@use "theme";

$vars: meta.module-variables("theme");   // map of name: value
$fns: meta.module-functions("theme");

This is handy for generating CSS custom properties from every variable in a tokens module, as you will do in design tokens and theming.

Common mistakes

  • Configuring too late. with must be on the first @use of that module anywhere in the compilation.
  • Forgetting !default. A variable without it cannot be configured; Sass reports an error naming the variable.
  • Putting $ in a load-css key. Map keys are plain strings: "brand", not "$brand".
  • Expecting @use twice to emit CSS twice. Use meta.load-css when you really want repeated output.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does $gap: 1rem !default; do?

    !default assigns only when the variable is undefined or null, which lets configuration win.
  2. 2. How do you override a module's $brand when loading it?

    The with clause takes variable names (with the dollar sign) and values.
  3. 3. A file runs @use "lib" and later another file runs @use "lib" with ($x: 1). What happens?

    Configuration is only possible on the first load of a module.
  4. 4. What does !default inside @forward "x" with ($a: 1 !default) mean?

    Without !default the forwarded configuration is fixed; with it, users can still configure the value.
  5. 5. Which tool can emit a stylesheet's CSS several times, possibly nested in a selector?

    load-css is a mixin, so each include emits the module's CSS at that spot.

Summary

  • Mark configurable variables !default; keep everything else private.
  • Pass overrides with @use "x" with ($var: value) on the first load of the module.
  • @forward "x" with (... !default) ships library defaults that users can still override.
  • meta.load-css emits a stylesheet's CSS where you include it, as often as you like, optionally configured with $with.
  • meta.module-variables and meta.module-functions let code inspect a module.

Next: Built-in Modules