Sass meta.variable-exists() Function

What You’ll Learn

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

What Is meta.variable-exists()?

Official docs: returns whether a variable named $name (without the $) exists in the current scope. That includes globals you can see from here and locals declared in the current rule, mixin, or function.

• Pass the bare name: "var1" checks $var1.
• Missing names return false—they do not throw.
• There is no $module argument (unlike global-variable-exists).
• See also meta.global-variable-exists() when you only want file-level globals.

📝 Syntax

@use "sass:meta";

// Recommended
meta.variable-exists($name)

// Legacy global name
variable-exists($name)

Parameters

Return value

📦 Loading sass:meta

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

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

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

🏢 Locals vs Globals

Official sample: a root $var1 is global; a $var2 inside h1 { … } is local. variable-exists finds both when you ask from a scope that can see them.

📋 Related Meta Helpers

🛠 Compatibility

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

Prefer current Dart Sass and the namespaced meta.* API.

Examples Gallery

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

@use "sass:meta";

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

$var1: value;

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

.before {
  --var1: false;
}

.after {
  --var1: true;
}

@use "sass:meta";

$brand: #0d9488;

.card {
  $accent: #f59e0b;
  --brand: #{meta.variable-exists("brand")};
  --accent: #{meta.variable-exists("accent")};
  --missing: #{meta.variable-exists("nope")};
}

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

@use "sass:meta";

$brand: #0d9488;

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

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

@use "sass:meta";

$brand: teal;

.box {
  color: if(meta.variable-exists("brand"), $brand, gray);
  border-color: if(meta.variable-exists("accent"), $accent, silver);
}

.box {
  color: teal;
  border-color: silver;
}

@use "sass:meta";

@mixin chip {
  $label: "chip";
  .chip {
    --has-label: #{meta.variable-exists("label")};
    --has-ghost: #{meta.variable-exists("ghost")};
    content: $label;
  }
}

@include chip;

.chip {
  --has-label: true;
  --has-ghost: false;
  content: "chip";
}

🚀 Real-World Use Cases

• Optional theme hooks — use $brand only when the caller defined it.
• Local overrides — detect a rule-level $accent without requiring a global.
• Safer if() defaults — avoid reading names that might not exist.
• Mixin internals — branch on locals created inside the mixin.
• Migration aid — pair with global-variable-exists to understand scope bugs.

⚠️ Common Pitfalls

• Including $ in the name — check "brand", not "$brand".
• Wrong helper for globals-only — use global-variable-exists when locals must not count.
• Expecting $module — this function has no module argument.
• Reading the variable before the guard — use if() so the missing branch never evaluates $missing.
• Expecting runtime checks — everything resolves when Sass compiles.

💡 Best Practices