meta.global-variable-exists($name, $module: null) returns a boolean: whether a global variable named $name exists. Pass the name without the $. Load it with @use "sass:meta".
meta.global-variable-exists("var1") is false until you declare $var1 at the root; a $var2 inside a rule stays local and still returns false.
$module for namespaces.After @use "sass:math", check module members with $module: "math". The value can also be a module value.
Variables declared inside a selector, mixin, or function are local. Use meta.variable-exists when the current scope matters.
@use "sass:meta";
meta.global-variable-exists($name, $module: null); //=> boolean
meta.global-variable-exists("var1"); // false until $var1 is defined
$var1: value;
meta.global-variable-exists("var1"); // true
// Global alias (legacy): global-variable-exists($name, $module: null)
// Prefer meta.global-variable-exists after @use "sass:meta"Pattern: pass a bare name (and optional module) → get true/false → branch with @if for optional config.
Same name, different helpers:
| Where declared | global-variable-exists | variable-exists |
|---|---|---|
| File root / global scope | true | true |
| Inside a rule / mixin / function | false | true (in that scope) |
| Never declared | false | false |
In a @use module | Use $module: "…" | N/A (no $module) |
Prefer meta.function-exists, meta.mixin-exists, and this helper over deprecated meta.feature-exists.
Examples use @use "sass:meta". Open View Compiled CSS for verified Dart Sass output (matches official Sass docs samples where shown).
A name is missing until you declare it at the root.
@use "sass:meta";
.before {
--var1: #{meta.global-variable-exists("var1")};
}
$var1: value;
.after {
--var1: #{meta.global-variable-exists("var1")};
}"var1" looks for $var1.false.true.A variable inside a rule does not count as a global.
@use "sass:meta";
$brand: #0ea5e9;
.card {
$accent: #f59e0b; // local
--brand-global: #{meta.global-variable-exists("brand")};
--accent-global: #{meta.global-variable-exists("accent")};
}true..card.Pick a configured global when present; otherwise use a fallback.
@use "sass:meta";
// App / theme provided this global
$brand: #2563eb;
.btn {
@if meta.global-variable-exists("brand") {
background: $brand;
} @else {
background: #64748b;
}
}
.chip {
@if meta.global-variable-exists("accent") {
background: #f59e0b;
} @else {
background: #94a3b8;
}
}.btn uses it.$brand: … !default; is often enough.Use $module for a @use namespace such as sass:math.
@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")};
}math namespace.false.variable-existsSame local name: global check fails, scoped check succeeds.
@use "sass:meta";
.panel {
$gap: 1rem; // local
--global-gap: #{meta.global-variable-exists("gap")};
--any-gap: #{meta.variable-exists("gap")};
}.panel.false.true in that scope.Most mistakes are including $, expecting locals, or forgetting $module.
Pass "brand", not "$brand".
Use meta.variable-exists for variables inside rules.
$moduleMatch the @use namespace string, or pass a module value.
Browsers never see the check—only the finished CSS values.
Prefer the module form with current Dart Sass.
| API | Status |
|---|---|
meta.global-variable-exists() | Dart Sass via @use "sass:meta" |
| Return type | Boolean |
| Name argument | String without $ |
| Legacy global | global-variable-exists($name, $module: null) |
Compile with the Dart Sass CLI.
@use namespace.One line: to ask whether a root-level variable is defined, use meta.global-variable-exists($name, $module: null).
Practical checklist:
1. @use "sass:meta"
2. Pass bare name without $
3. Optional $module for @use namespaces
4. Branch with @if for optional config
5. Use variable-exists when locals matterGet a debug string for any Sass value.
8 people found this page helpful