Sass meta.global-variable-exists() Function

What You’ll Learn

meta.global-variable-exists() belongs to the built-in sass:meta module. It answers: is there a global variable named X? This page covers the no-$ name rule, locals vs globals, $module, vs meta.variable-exists, and five compiled examples.

What Is meta.global-variable-exists()?

Official docs: returns whether a global variable named $name exists (without the $). Use it for optional theme tokens, safe defaults, and library APIs that only care about root-level configuration.

• Without $module, checks for an un-namespaced global in the current file’s context.
• With $module, checks a variable inside a @use namespace.
• Variables declared inside a selector / mixin / function are local—this helper returns false for them.

📝 Syntax

@use "sass:meta";

// Recommended
meta.global-variable-exists($name, $module: null)

// Legacy global name
global-variable-exists($name, $module: null)

Parameters

Return value

📦 Loading sass:meta

// Recommended — namespaced
@use "sass:meta";
$ok: meta.global-variable-exists("brand");

// Optional — bring members into scope
@use "sass:meta" as *;
$ok: global-variable-exists("brand");

// Legacy global
$ok: global-variable-exists("brand");

🔗 Global vs Local Variables

Official sample: a root $var1 is global; a $var2 inside h1 { … } is local. Only the global is found by this helper.

📦 Using the $module Argument

After @use "./tokens" as tokens, check that module’s globals with $module: "tokens". The string must match the namespace used in this file.

@use "sass:meta";
@use "sass:math";

// Built-in modules expose members; $e is a known math constant in sass:math
$has-e: meta.global-variable-exists("e", $module: "math");

🛠 Compatibility

This is about Sass compilers, not browsers. The check runs at compile time.

Prefer current Dart Sass so @use + $module work as documented.

Examples Gallery

Each example uses meta.global-variable-exists at compile time. Open View Compiled CSS for verified Dart Sass output.

@use "sass:meta";

.before {
  --var1: #{meta.global-variable-exists("var1")};
}

$var1: value;

.after {
  --var1: #{meta.global-variable-exists("var1")};
}

.before {
  --var1: false;
}

.after {
  --var1: true;
}

@use "sass:meta";

$brand: #0ea5e9;

.card {
  $accent: #f59e0b; // local
  --brand-global: #{meta.global-variable-exists("brand")};
  --accent-global: #{meta.global-variable-exists("accent")};
}

.card {
  --brand-global: true;
  --accent-global: false;
}

@use "sass:meta";

// App / theme provided this global
$brand: #2563eb;

.btn {
  background: if(
    meta.global-variable-exists("brand"),
    $brand,
    #64748b
  );
}

.chip {
  background: if(
    meta.global-variable-exists("accent"),
    #f59e0b,
    #94a3b8
  );
}

.btn {
  background: #2563eb;
}

.chip {
  background: #94a3b8;
}

@use "sass:meta";
@use "sass:math";

.probe {
  --math-e: #{meta.global-variable-exists("e", $module: "math")};
  --math-missing: #{meta.global-variable-exists("nope", $module: "math")};
  --bare-e: #{meta.global-variable-exists("e")};
}

.probe {
  --math-e: true;
  --math-missing: false;
  --bare-e: false;
}

@use "sass:meta";

.panel {
  $gap: 1rem; // local
  --global-gap: #{meta.global-variable-exists("gap")};
  --any-gap: #{meta.variable-exists("gap")};
}

.panel {
  --global-gap: false;
  --any-gap: true;
}

🚀 Real-World Use Cases

• Optional theme tokens — apply fallbacks only when a global is missing.
• Library configuration — detect whether the consumer set root options.
• Module-aware tools — query another file’s globals via $module.
• Migration helpers — preferred modern check vs deprecated feature-exists.
• Debug / assert — fail early if a required global was never defined.

⚠️ Common Pitfalls

• Including $ in the name — pass "brand", not "$brand".
• Expecting locals — use meta.variable-exists for scoped variables.
• Forgetting $module — namespaced members will not match a bare check.
• Wrong namespace string — must match this file’s @use … as name.
• Expecting runtime checks — everything resolves when Sass compiles.

💡 Best Practices