Sass @use Rule

What You’ll Learn

The Sass @use rule loads other stylesheets as modules. You get their CSS once, plus namespaced variables, functions, and mixins. This page covers namespaces, as *, with configuration, private members, partials, and five compiled examples.

What Is @use?

Official docs: the @use rule loads mixins, functions, and variables from other Sass stylesheets, and combines CSS from multiple stylesheets together. Stylesheets loaded by @use are called modules. Sass also provides built-in modules like sass:math and sass:string.

• CSS from a module is included exactly once, no matter how often it is loaded.
• Members are namespaced by default—easy to see where $radius came from.
• @use rules must come before other rules (except @forward).
• You may declare variables before @use to help configure modules.
• Requires Dart Sass 1.23+ (not LibSass / Ruby Sass).

📝 Syntax

@use "url";
@use "url" as alias;
@use "url" as *;
@use "url" with (
  $variable: value
);
@use "url" as alias with (
  $variable: value
);

Parts of the rule

📦 Loading Members

Official docs: access variables, functions, and mixins with namespace.$var, namespace.fn(), or @include namespace.mixin. By default, the namespace is the last component of the module’s URL.

// src/_corners.scss
$radius: 3px;

@mixin rounded {
  border-radius: $radius;
}

// style.scss
@use "src/corners";

.button {
  @include corners.rounded;
  padding: 5px + corners.$radius;
}

• Members loaded with @use are only visible in the file that loads them.
• Other files must write their own @use if they need the same members.
• To re-export many modules from one entry file, use @forward.

🏷️ Choosing a Namespace

Official docs: use as * mainly for stylesheets you control. Third-party modules may add members later and cause name conflicts.

🔒 Private Members

Official docs: start a name with - or _ to keep it private. Private members work inside the defining file but are not part of the module’s public API.

// src/_corners.scss
$-radius: 3px;

@mixin rounded {
  border-radius: $-radius;
}

// style.scss
@use "src/corners";

.button {
  @include corners.rounded;
  // Error: corners.$-radius is not visible outside _corners.scss
}

⚙️ Configuration With with

Official docs: define variables with the !default flag, then load the module with @use "…" with ($name: value). Configured values override the defaults.

• A module keeps the same configuration even if loaded again.
• @use … with can only be used once per module—the first load.
• If you also need a custom namespace: @use "…" as alias with (…) (as before with).

🔍 Finding the Module

• Extensions are optional: @use "variables" loads .scss, .sass, or .css.
• Use forward slashes in URLs (even on Windows).
• URLs are case-sensitive.
• Relative paths are checked first; load paths are a fallback.
• Partials start with _ (as in _code.scss); omit the underscore when loading.
• A folder’s _index.scss loads when you @use "folder".

🔁 @use vs @import

🛠 Compatibility

This is about Sass compilers, not browsers. @use is resolved at compile time.

Examples Gallery

Multi-file samples show both the module and the loading file (as in the official docs). Open View Compiled CSS for verified output.

// src/_corners.scss
$radius: 3px;

@mixin rounded {
  border-radius: $radius;
}

// style.scss
@use "src/corners";

.button {
  @include corners.rounded;
  padding: 5px + corners.$radius;
}

.button {
  border-radius: 3px;
  padding: 8px;
}

// src/_corners.scss
$radius: 3px;

@mixin rounded {
  border-radius: $radius;
}

// style.scss
@use "src/corners" as c;

.button {
  @include c.rounded;
  padding: 5px + c.$radius;
}

.button {
  border-radius: 3px;
  padding: 8px;
}

// src/_corners.scss
$radius: 3px;

@mixin rounded {
  border-radius: $radius;
}

// style.scss
@use "src/corners" as *;

.button {
  @include rounded;
  padding: 5px + $radius;
}

.button {
  border-radius: 3px;
  padding: 8px;
}

// _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;
}

// style.scss
@use "library" with (
  $black: #222,
  $border-radius: 0.1rem
);

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

// foundation/_code.scss
code {
  padding: .25em;
  line-height: 0;
}

// foundation/_lists.scss
ul, ol {
  text-align: left;

  & & {
    padding: {
      bottom: 0;
      left: 0;
    }
  }
}

// style.scss
@use "foundation/code";
@use "foundation/lists";

code {
  padding: 0.25em;
  line-height: 0;
}

ul, ol {
  text-align: left;
}
ul ul, ul ol, ol ul, ol ol {
  padding-bottom: 0;
  padding-left: 0;
}

🚀 Real-World Use Cases

• Design tokens — @use "tokens" for colors, spacing, and type.
• Component libraries — load mixins like button.primary with clear namespaces.
• Built-in helpers — @use "sass:math", sass:string, sass:color.
• Theming — configure !default variables once at the entry file.
• Foundation CSS — split reset/base partials and compose them with @use.

⚠️ Common Pitfalls

• Using @use after CSS rules — it must come first (with @forward / config vars as exceptions).
• Forgetting the namespace — write math.abs(), not bare abs(), after @use "sass:math".
• Configuring twice — with only works on the first load of a module.
• as * collisions — limit star loads to your own files.
• Backslashes on Windows — always use / in module URLs.

💡 Best Practices