Sass @if Rule

What You’ll Learn

Sass @if decides whether a block of styles (or other Sass statements) runs at compile time. This page focuses on @if itself: syntax, truthiness, boolean operators, and five examples. @else and @else if are covered on a separate page.

What Is @if?

Official docs: the @if rule is written @if <expression> { … } and controls whether or not its block gets evaluated (including emitting any styles as CSS). The expression usually returns true or false—if it returns true, the block is evaluated; if false, it is not.

• Runs at compile time—browsers never see @if.
• Skipped blocks emit no CSS for that branch.
• Common inside mixins and functions.
• Works with any truthy/falsey expression, not only booleans.

📝 Syntax

@use "sass:math";

@mixin avatar($size, $circle: false) {
  width: $size;
  height: $size;

  @if $circle {
    border-radius: math.div($size, 2);
  }
}

When $circle is true, the border-radius block runs. When it is false, that block is skipped entirely.

✅ Truthiness and Falsiness

Official docs: anywhere true or false are allowed, you can use other values too.

• Falsey — only false and null.
• Truthy — every other value (including 0, "", and empty lists).

Practical pattern: string.index($string, " ") returns null when the substring is missing (falsey) and a number when it is found (truthy)—so you can write @if string.index($text, " ") { … } without comparing to null.

⚖️ Boolean Operators With @if

Official docs: conditional expressions may contain boolean operators (and, or, not). See also Sass boolean operators.

@if $theme == dark and $density == compact { … }
@if $theme == light or $theme == dark { … }
@if not ($theme == light) { … }

📄 What About @else / @else if?

An @if can optionally be followed by @else when you need a two-way fallback, or by a chain of @else if branches for many outcomes. This page stays focused on single-branch @if—optional styles, flags, and truthiness.

Examples Gallery

Every example uses @if only (no @else chains). Open View Compiled CSS for verified output.

@use "sass:math";

@mixin avatar($size, $circle: false) {
  width: $size;
  height: $size;

  @if $circle {
    border-radius: math.div($size, 2);
  }
}

.square-av {
  @include avatar(100px, $circle: false);
}

.circle-av {
  @include avatar(100px, $circle: true);
}

.square-av {
  width: 100px;
  height: 100px;
}

.circle-av {
  width: 100px;
  height: 100px;
  border-radius: 50px;
}

$enable-shadows: true;
$is-rtl: false;

.card {
  padding: 1rem;

  @if $enable-shadows {
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12);
  }

  @if $is-rtl {
    margin-right: auto;
  }
}

@if $enable-shadows {
  .floating {
    filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.2));
  }
}

.card {
  padding: 1rem;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12);
}

.floating {
  filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.2));
}

@use "sass:string";

@mixin spaced-label($text) {
  content: $text;

  @if string.index($text, " ") {
    letter-spacing: 0.04em;
  }
}

.one-word {
  &::before {
    @include spaced-label("Hello");
  }
}

.two-words {
  &::before {
    @include spaced-label("Hello World");
  }
}

.one-word::before {
  content: "Hello";
}

.two-words::before {
  content: "Hello World";
  letter-spacing: 0.04em;
}

$theme: dark;
$density: compact;

.panel {
  padding: 1rem;

  @if $theme == dark and $density == compact {
    background: #111;
    color: #eee;
    padding: 0.5rem;
  }

  @if $theme == light or $theme == dark {
    border: 1px solid currentColor;
  }

  @if not ($theme == light) {
    box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.08);
  }
}

.panel {
  padding: 1rem;
  background: #111;
  color: #eee;
  padding: 0.5rem;
  border: 1px solid currentColor;
  box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.08);
}

@mixin truth-demo($value, $label) {
  @if $value {
    --#{$label}: on;
  }
}

.checks {
  @include truth-demo("", "empty-string");
  @include truth-demo(0, "zero");
  @include truth-demo((), "empty-list");
  @include truth-demo(false, "false");
  @include truth-demo(null, "null");
}

.checks {
  --empty-string: on;
  --zero: on;
  --empty-list: on;
}

🚀 Real-World Use Cases

• Optional mixin knobs — $circle, $border, $shadow.
• Build flags — enable debug outlines or reduced-motion helpers.
• Theme tokens — emit a block only for a matching theme name.
• Null-as-missing — treat null returns as “skip this style.”
• Guard clauses — pair with @error on a separate branch page when you need hard fails.

⚠️ Common Pitfalls

• Treating 0 or "" as false — they are truthy in Sass.
• Expecting runtime CSS conditions — @if cannot react to the browser.
• Forgetting keyword args — avatar(100px, true) vs $circle: true for clarity.
• Over-nesting flags — too many compile flags make stylesheets hard to reason about.
• Confusing with CSS if() — CSS has its own evolving if(); Sass @if is compile-time only.

💡 Best Practices