Sass meta.load-css()

Intermediate
9 min read
Updated: Nov 2026
5 examples
Dart Sass 1.23+
Sass meta.load-css including another module CSS under a selector
Definition

Definition and Usage

meta.load-css($url, $with: null) is a mixin: it loads the module at $url and includes that module’s CSS only where you @include it. It does not expose variables, mixins, or functions. Dart Sass 1.23+. Load with @use "sass:meta".

Official sample idea.

Nest dark-theme code styles under body.dark and configure $border-contrast with $with: ("border-contrast": true).

Shorthand.

Official docs: meta.load-css is shorthand for meta.css(meta.load($url, $with)).

URL is a module string.

Pass a string like you would to @use—not a CSS url(). Relative paths are relative to the current file.

Syntax

Syntax

SCSS
@use "sass:meta";

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

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

// Mixin API — always @include (does not return a value)

Pattern: pick a module URL → optional $with map (bare names) → @include at the place CSS should appear (top level, nested selector, or media query).

Reference

load-css vs @use

Same modules idea, different jobs:

@usemeta.load-css
Exposes membersYesNo — CSS only
Where it can appearFile top (before styles)Anywhere you can @include
Nest under a selectorNoYes
Configure with map@use "…" with (…)$with: ("name": value)
Dynamic URL stringStatic stringCan use interpolation / variables
Use both when needed.

@use a module for its API; meta.load-css when you only need its CSS nested under a theme class or media query.

Code

SCSS Examples

Examples target Dart Sass 1.23+ with @use "sass:meta". Each sample shows a partial plus the including file. Open View Compiled CSS for verified output (matches official Sass docs samples where shown).

Example 1 — Include CSS from Another File

Load a partial’s CSS at the top level without importing its members.

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

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

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

How It Works

  1. load-css evaluates _button.scss.
  2. CSS is emitted at the include site.
  3. Members stay private to that module.
  4. Need mixins? Also @use the module.

Example 2 — Configure with $with (Official Docs)

Nest dark-theme code styles under body.dark and flip a !default flag.

SCSS
// 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)
  );
}

How It Works

  1. $with configures $border-contrast.
  2. Keys omit the $.
  3. Nesting under body.dark prefixes selectors.
  4. Matches the official Sass docs CSS output.

Example 3 — Nest Under a Theme Class

Reuse one card partial for light and dark wrappers without duplicating rules by hand.

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

How It Works

  1. Same partial is included twice.
  2. Each include nests under a different parent.
  3. Module evaluates once; CSS emits at each site.
  4. Handy for theme wrappers without copy-paste.

Example 4 — URL from a Variable / Interpolation

The module URL can come from a variable and include interpolation.

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

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

$theme: "ocean";

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

How It Works

  1. $theme builds the URL string.
  2. Interpolation becomes themes/ocean.
  3. CSS nests under .hero.
  4. Unlike @use, the path need not be a fixed literal.

Example 5 — Nest Inside a Media Query

Scope a print stylesheet partial under @media print.

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

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

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

How It Works

  1. Include can sit inside @media.
  2. Every rule from the partial is scoped to print.
  3. No members from print leak into the host file.
  4. Same idea works for other at-rules that wrap styles.

Edge Cases & Pitfalls

Most load-css bugs are expecting members, reconfiguring a loaded module, or using a CSS url().

members

CSS only — no API import

Variables / mixins / functions from the loaded file stay unavailable unless you also @use it.

config

Configure once

You cannot pass $with to a module that was already loaded (with or without config).

url

Not a CSS url()

Pass a module path string like "dark-theme/code", the same style as @use.

mixin

Always @include

It is a mixin, not a function—do not assign meta.load-css(...) to a variable.

Toolchain

Sass Support

Prefer the module form with Dart Sass 1.23+.

APIStatus
meta.load-css()Dart Sass 1.23+ via @use "sass:meta"
KindMixin (use @include)
Shorthand formeta.css(meta.load($url, $with))
LibSass / Ruby SassNot available

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • Includes another module’s CSS where you call the mixin.
  • No members — CSS only; use @use for the API.
  • $with configures !default variables with bare names.
  • Nestable under selectors, media queries, and more.

One line: when you need another file’s CSS in a specific place (with optional config), use @include meta.load-css($url, $with: null).

Practice

Compile Notes

Practical checklist:

checklist.txt
1. @use "sass:meta"
2. @include meta.load-css("path/to/module")
3. Optional $with: ("name": value) for !default vars
4. Nest under a selector / @media when needed
5. @use the module separately if you need its members

Frequently Asked Questions

meta.load-css($url, $with: null) loads the module at $url and includes its CSS as if that CSS were written where you include the mixin. It does not import variables, mixins, or functions into the current file.
@use loads a module and makes its members available (once, at the top). meta.load-css only pulls in CSS, can appear anywhere—even nested under a selector—and accepts a configurable $with map. It never exposes members.
An optional map from variable names (without $) to values. Those values configure !default variables in the loaded module, similar to @use "…" with (…).
The module is evaluated only once, like @use. You also cannot provide configuration to a module that was already loaded—configured or not.
It is a mixin from sass:meta. Always use @include meta.load-css(...). It emits CSS; it does not return a value. Official docs: shorthand for meta.css(meta.load($url, $with)).
Dart Sass 1.23+. LibSass and Ruby Sass do not provide this mixin. Prefer current Dart Sass.

Next: Sass meta.mixin-exists()

Check whether a mixin name is defined.

meta.mixin-exists() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

8 people found this page helpful

Sass meta.keywords Function Sass meta.mixin-exists Function