Sass meta.load-css() Function

What You’ll Learn

meta.load-css() belongs to the built-in sass:meta module. It loads another stylesheet module and includes only its CSS where you write the include—even nested under a selector. This page covers $with configuration, vs @use, nesting, dynamic URLs, Dart Sass 1.23+, and five examples.

What Is meta.load-css()?

@use is the usual way to load a Sass module: you get its CSS and its members (variables, mixins, functions). Sometimes you only want the CSS, or you want that CSS nested under body.dark or a media query. Official docs: meta.load-css loads the module at $url and includes its CSS as though it were written as the contents of this mixin.

• Use it with @include (it is a meta mixin)
• Optional $with configures !default variables in the loaded file
• Members from the loaded module are not available in the current file
• Can appear anywhere—including nested inside style rules

📝 Syntax

Load the meta module, then include the mixin:

@use "sass:meta";

@include meta.load-css($url);
@include meta.load-css($url, $with: null);
@include meta.load-css($url, $with: ("var-name": value));

Parameters

Return value

📦 Loading sass:meta

There is no legacy global load-css(). Load the meta module and include meta.load-css.

// Recommended — namespaced
@use "sass:meta";
@include meta.load-css("components/button");

// Optional — bring members into scope
@use "sass:meta" as *;
@include load-css("components/button");

// Optional — custom namespace
@use "sass:meta" as m;
@include m.load-css("components/button");

📋 Like @use / Unlike @use

Official docs split the rules this way:

⚙️ Configuring with $with

Pass a map whose keys are variable names without the $ prefix. Those values configure matching !default variables in the loaded module.

@use "sass:meta";

// Loaded file has: $border-contrast: false !default;
@include meta.load-css(
  "dark-theme/code",
  $with: ("border-contrast": true)
);

🛠 Compatibility

This is about Sass compilers, not browsers. The mixin runs at compile time; browsers only see the nested CSS it produces.

Examples Gallery

Examples show both the loaded partial and the including file (as in the official docs). Open View Compiled CSS for the finished output.

// _button.scss
.btn {
  padding: 0.5rem 1rem;
  border-radius: 6px;
}

// style.scss
@use "sass:meta";

@include meta.load-css("button");

.btn {
  padding: 0.5rem 1rem;
  border-radius: 6px;
}

// dark-theme/_code.scss
$border-contrast: false !default;

code {
  background-color: #6b717f;
  color: #d2e1dd;
  @if $border-contrast {
    border-color: #dadbdf;
  }
}

// style.scss
@use "sass:meta";

body.dark {
  @include meta.load-css(
    "dark-theme/code",
    $with: ("border-contrast": true)
  );
}

body.dark code {
  background-color: #6b717f;
  color: #d2e1dd;
  border-color: #dadbdf;
}

// _card.scss
.card {
  padding: 1rem;
  border-radius: 8px;
}

// style.scss
@use "sass:meta";

.theme-light {
  @include meta.load-css("card");
}

.theme-dark {
  @include meta.load-css("card");
}

.theme-light .card {
  padding: 1rem;
  border-radius: 8px;
}

.theme-dark .card {
  padding: 1rem;
  border-radius: 8px;
}

// themes/_ocean.scss
.banner { background: #0ea5e9; }

// style.scss
@use "sass:meta";

$theme: "ocean";

.hero {
  @include meta.load-css("themes/#{$theme}");
}

.hero .banner {
  background: #0ea5e9;
}

// _print.scss
a { color: #000; text-decoration: underline; }
nav { display: none; }

// style.scss
@use "sass:meta";

@media print {
  @include meta.load-css("print");
}

@media print {
  a {
    color: #000;
    text-decoration: underline;
  }

  nav {
    display: none;
  }
}

🚀 Real-World Use Cases

• Theme wrappers — nest the same component CSS under .theme-dark / .theme-light.
• Configurable partials — flip !default flags with $with (official dark-theme sample).
• Dynamic theme paths — build the module URL from a variable or interpolation.
• Media-scoped sheets — load print or reduced-motion CSS inside the matching query.
• CSS-only composition — pull styles without exposing another file’s mixins into your namespace.

⚠️ Common Pitfalls

• Expecting members — variables/mixins from the loaded file are not available; use @use when you need them.
• CSS url() as $url — pass a module string like "dark-theme/code", not url(...).
• Reconfiguring a loaded module — first load wins; later $with cannot reconfigure it.
• Forgetting !default — $with configures defaulted variables; non-default variables may not accept overrides the same way.
• Using it as a value — always @include; do not assign the mixin call.

💡 Best Practices