Sass meta.module-variables() Function

What You’ll Learn

meta.module-variables() belongs to the built-in sass:meta module. It returns every variable in a @used module as a map of names (without $) to values. This page covers the official color-token example, map.get usage, and five compiled examples.

What Is meta.module-variables()?

Official docs: returns all the variables defined in a module, as a map from variable names (without $) to the values of those variables. Think of it as dumping a module’s token sheet into one map you can inspect, loop, or read with map.get.

• $module must be a string matching a @use namespace in the current file.
• Map keys omit $—$hopbush becomes "hopbush".
• Map values are the actual Sass values (colors, lengths, strings, and so on)—ready for CSS.
• Dart Sass 1.23+ only—LibSass and Ruby Sass do not support it.

📝 Syntax

@use "sass:meta";

// Dart Sass 1.23+ (no legacy global name)
meta.module-variables($module)

Parameters

Return value

📦 Loading sass:meta

@use "sass:map";
@use "sass:meta";
@use "variables";

$vars: meta.module-variables("variables");
$pink: map.get($vars, "hopbush"); // #c69

There is no legacy global module-variables(). Always load sass:meta and call meta.module-variables.

🎨 The Official Color Tokens Pattern

Docs load a variables partial and inspect the returned map:

// _variables.scss
$hopbush: #c69;
$midnight-blue: #036;
$wafer: #e1d7d2;

// styles.scss
@use "sass:meta";
@use "variables";

@debug meta.module-variables("variables");
// (
//   "hopbush": #c69,
//   "midnight-blue": #036,
//   "wafer": #e1d7d2
// )

If you wrote @use "variables" as tokens, pass "tokens" as $module.

📋 Related Meta Helpers

🛠 Compatibility

This is about Sass compilers, not browsers. The map is built at compile time.

Prefer current Dart Sass. Only Dart Sass supports this function.

Examples Gallery

Each example uses meta.module-variables at compile time (Dart Sass 1.23+). Open View Compiled CSS for verified output.

$hopbush: #c69;
$midnight-blue: #036;
$wafer: #e1d7d2;

@use "sass:meta";
@use "variables";

.probe {
  --vars: #{meta.inspect(meta.module-variables("variables"))};
}

.probe {
  --vars: ("hopbush": #c69, "midnight-blue": #036, "wafer": #e1d7d2);
}

@use "sass:map";
@use "sass:meta";
@use "variables";

$vars: meta.module-variables("variables");

.swatch {
  color: map.get($vars, "hopbush");
  background: map.get($vars, "wafer");
  border-color: map.get($vars, "midnight-blue");
}

.swatch {
  color: #c69;
  background: #e1d7d2;
  border-color: #036;
}

@use "sass:list";
@use "sass:map";
@use "sass:meta";
@use "variables";

$vars: meta.module-variables("variables");

.probe {
  --keys: #{meta.inspect(map.keys($vars))};
  --n: #{list.length(map.keys($vars))};
  --has-hopbush: #{map.has-key($vars, "hopbush")};
  --has-nope: #{map.has-key($vars, "nope")};
}

.probe {
  --keys: "hopbush", "midnight-blue", "wafer";
  --n: 3;
  --has-hopbush: true;
  --has-nope: false;
}

$radius: 8px;
$pad: 1rem;
$ink: #123;

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

$theme: meta.module-variables("theme");

.card {
  padding: map.get($theme, "pad");
  border-radius: map.get($theme, "radius");
  color: map.get($theme, "ink");
}

.card {
  padding: 1rem;
  border-radius: 8px;
  color: #123;
}

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

$theme: meta.module-variables("theme");
$name: "radius";

.box {
  @if map.has-key($theme, $name) {
    border-radius: map.get($theme, $name);
  } @else {
    border-radius: 0;
  }
  padding: 1rem;
}

.box {
  border-radius: 8px;
  padding: 1rem;
}

🚀 Real-World Use Cases

• Design-token dumps — load a colors or spacing module and read tokens by name.
• Theme packs — swap which module you @use, then rebuild styles from its map.
• Documentation / debug peeks — print keys or the full map with meta.inspect.
• Safe optional tokens — map.has-key before map.get.
• Code generation — loop @each $name, $value in … to emit CSS custom properties.

⚠️ Common Pitfalls

• Including $ in keys — look up "hopbush", not "$hopbush".
• Wrong namespace string — must match this file’s @use … as name exactly.
• Module not loaded here — only @use rules in the current file count.
• Confusing with function/mixin maps — these values are ready to use; no meta.call / apply.
• Expecting LibSass — this API is Dart Sass only (1.23+).

💡 Best Practices