Sass @forward Rule

What You’ll Learn

The Sass @forward rule re-exports another module’s public API through your stylesheet. Library authors split code across files while users load one entrypoint with @use. This page covers prefixes, show/hide, configuration, and five compiled examples.

What Is @forward?

Official docs: the @forward rule loads a Sass stylesheet and makes its mixins, functions, and variables available when your stylesheet is loaded with @use. It organizes libraries across many files while letting users load a single entrypoint.

• Written @forward "url"—loads like @use, but for re-export.
• Public members look as if they were defined in your module.
• Those members are not available inside the forwarding file unless you also @use it.
• Sass still loads the module only once if you write both @forward and @use.
• Forwarded CSS is included in the output (same as @use for CSS).

📝 Syntax

@forward "url";
@forward "url" as prefix-*;
@forward "url" hide member, $variable;
@forward "url" show member, $variable;
@forward "url" with (
  $variable: value !default
);

Parts of the rule

📦 Basic Re-Export

Official pattern: a library file forwards internal modules; the app loads only the library.

// src/_list.scss
@mixin list-reset {
  margin: 0;
  padding: 0;
  list-style: none;
}

// bootstrap.scss
@forward "src/list";

// styles.scss
@use "bootstrap";

li {
  @include bootstrap.list-reset;
}

🏷️ Adding a Prefix

Official docs: module members are usually used with a namespace, so short names are readable inside a file—but outside they may need context. @forward "…" as list-* prefixes every forwarded mixin, function, and variable.

🔒 Controlling Visibility

Official docs: use hide or show to control exactly which members get forwarded. List mixin/function names and variables (including $).

• hide a, $b — forward everything except these.
• show a, $b — forward only these.
• Useful for keeping package-private helpers out of the public API.

// bootstrap.scss
@forward "src/list" hide list-reset, $horizontal-list-gap;

⚙️ Configuring Modules

Official docs: @forward can load a module with configuration (Dart Sass 1.24+). It mostly matches @use … with, with one addition: configuration values may use !default so downstream stylesheets can still override them.

// _opinionated.scss
@forward "library" with (
  $black: #222 !default,
  $border-radius: 0.1rem !default
);

// style.scss
@use "opinionated" with ($black: #333);

Here the opinionated package sets new defaults; the app still overrides $black to #333.

🔁 @forward vs @use

🛠 Compatibility

This is about Sass compilers, not browsers. Module rules resolve at compile time.

Examples Gallery

Multi-file samples show the source module, the forwarding entrypoint, and the consumer (as in the official docs). Open View Compiled CSS for verified output.

// src/_list.scss
@mixin list-reset {
  margin: 0;
  padding: 0;
  list-style: none;
}

// bootstrap.scss
@forward "src/list";

// styles.scss
@use "bootstrap";

li {
  @include bootstrap.list-reset;
}

li {
  margin: 0;
  padding: 0;
  list-style: none;
}

// src/_list.scss
@mixin reset {
  margin: 0;
  padding: 0;
  list-style: none;
}

// bootstrap.scss
@forward "src/list" as list-*;

// styles.scss
@use "bootstrap";

li {
  @include bootstrap.list-reset;
}

li {
  margin: 0;
  padding: 0;
  list-style: none;
}

// src/_list.scss
$horizontal-list-gap: 2em;

@mixin list-reset {
  margin: 0;
  padding: 0;
  list-style: none;
}

@mixin list-horizontal {
  @include list-reset;

  li {
    display: inline-block;
    margin: {
      left: -2px;
      right: $horizontal-list-gap;
    }
  }
}

// bootstrap.scss
@forward "src/list" hide list-reset, $horizontal-list-gap;

// styles.scss
@use "bootstrap";

.nav {
  @include bootstrap.list-horizontal;
}

.nav {
  margin: 0;
  padding: 0;
  list-style: none;
}
.nav li {
  display: inline-block;
  margin-left: -2px;
  margin-right: 2em;
}

// _library.scss
$black: #000 !default;
$border-radius: 0.25rem !default;
$box-shadow: 0 0.5rem 1rem rgba($black, 0.15) !default;

code {
  border-radius: $border-radius;
  box-shadow: $box-shadow;
}

// _opinionated.scss
@forward "library" with (
  $black: #222 !default,
  $border-radius: 0.1rem !default
);

// style.scss
@use "opinionated" with ($black: #333);

code {
  border-radius: 0.1rem;
  box-shadow: 0 0.5rem 1rem rgba(51, 51, 51, 0.15);
}

// src/_list.scss
@mixin list-reset {
  margin: 0;
  padding: 0;
  list-style: none;
}

// entry.scss — forward first, then use
@forward "src/list";
@use "src/list";

.local {
  @include list.list-reset;
}

// app.scss
@use "entry";

.remote {
  @include entry.list-reset;
}

.local {
  margin: 0;
  padding: 0;
  list-style: none;
}

.remote {
  margin: 0;
  padding: 0;
  list-style: none;
}

🚀 Real-World Use Cases

• Library entrypoints — one @use "my-lib" for many partials.
• Public API shaping — prefix or hide members before shipping a package.
• Opinionated themes — forward a base library with new !default values.
• Monorepo design systems — forward tokens, mixins, and components from index files.
• Gradual modularization — keep a stable import path while splitting internals.

⚠️ Common Pitfalls

• Expecting local access — @forward alone does not give you the members in that file.
• @use before @forward — can block consumer configuration; forward first.
• Forgetting $ in hide/show — variables need the dollar sign in the list.
• Prefix confusion — as list-* changes the member name, not only the namespace.
• Old compilers — LibSass does not support @forward.

💡 Best Practices