Sass meta.content-exists() Function

What You’ll Learn

meta.content-exists() belongs to the built-in sass:meta module. It tells you whether the current mixin was given a @content block. This page covers safe defaults, vs meta.accepts-content, the “inside a mixin only” rule, and five compiled examples.

What Is meta.content-exists()?

Mixins can optionally receive a block of styles with @content:

@include card;                 // no content block
@include card { color: navy; } // content block passed

Official docs: meta.content-exists() returns whether the current mixin was passed a @content block. Use that boolean in @if to change padding, wrappers, or fallback styles when callers omit the block.

📝 Syntax

@use "sass:meta";

// Recommended — no parameters
meta.content-exists()

// Legacy global name
content-exists()

Parameters

None. The function inspects the mixin that is currently running.

Return value

Errors

Official docs: throws an error if called outside of a mixin. Keep it inside @mixin … { … }.

📦 Loading sass:meta

// Recommended — namespaced
@use "sass:meta";

@mixin demo {
  @if meta.content-exists() {
    @content;
  }
}

// Optional — bring members into scope
@use "sass:meta" as *;

@mixin demo {
  @if content-exists() {
    @content;
  }
}

// Legacy global
@mixin demo {
  @if content-exists() {
    @content;
  }
}

🔗 How @content Fits In

1. Define a mixin that may include @content.
2. Callers either @include it bare, or with a { … } block.
3. Inside the mixin, meta.content-exists() reports which form was used.
4. Emit @content when you want the caller’s styles inserted.

@use "sass:meta";

@mixin panel {
  border: 1px solid #ddd;
  @if meta.content-exists() {
    padding: 1rem;
    @content;
  }
}

📋 content-exists vs accepts-content

🛠 Compatibility

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

Prefer current Dart Sass and the namespaced meta. form.

Examples Gallery

Each example calls meta.content-exists() inside a mixin. Open View Compiled CSS for verified Dart Sass output.

@use "sass:meta";

@mixin status {
  @if meta.content-exists() {
    --has-content: true;
    @content;
  } @else {
    --has-content: false;
  }
}

.bare {
  @include status;
}

.filled {
  @include status {
    color: teal;
  }
}

.bare {
  --has-content: false;
}

.filled {
  --has-content: true;
  color: teal;
}

@use "sass:meta";

@mixin alert {
  border-left: 4px solid #f59e0b;
  padding: 0.75rem 1rem;
  @if meta.content-exists() {
    @content;
  } @else {
    color: #92400e;
    font-weight: 600;
  }
}

.custom {
  @include alert {
    color: #1e3a8a;
  }
}

.fallback {
  @include alert;
}

.custom {
  border-left: 4px solid #f59e0b;
  padding: 0.75rem 1rem;
  color: #1e3a8a;
}

.fallback {
  border-left: 4px solid #f59e0b;
  padding: 0.75rem 1rem;
  color: #92400e;
  font-weight: 600;
}

@use "sass:meta";

@mixin card {
  background: #fff;
  border-radius: 8px;
  @if meta.content-exists() {
    .card__body {
      padding: 1.25rem;
      @content;
    }
  }
}

.shell {
  @include card;
}

.body {
  @include card {
    font-size: 1rem;
  }
}

.shell {
  background: #fff;
  border-radius: 8px;
}

.body {
  background: #fff;
  border-radius: 8px;
}
.body .card__body {
  padding: 1.25rem;
  font-size: 1rem;
}

@use "sass:meta";

@mixin section {
  display: block;
  --mode: #{if(meta.content-exists(), "rich", "plain")};
  @content;
}

.plain {
  @include section;
}

.rich {
  @include section {
    margin-block: 2rem;
  }
}

.plain {
  display: block;
  --mode: plain;
}

.rich {
  display: block;
  --mode: rich;
  margin-block: 2rem;
}

@use "sass:meta";

@mixin flag {
  --passed: #{meta.content-exists()};
  @content;
}

.none {
  @include flag;
}

.empty {
  @include flag {
  }
}

.none {
  --passed: false;
}

.empty {
  --passed: true;
}

🚀 Real-World Use Cases

• Optional layout chrome — padding, wrappers, or gaps only when content exists.
• Fallback copy styles — default color/weight when callers skip the block.
• Debug / theme flags — set custom properties like --has-content for tooling.
• Component APIs — one mixin that works as a shell or as a filled component.
• Safer @content — branch before nesting content into deep selectors.

⚠️ Common Pitfalls

• Calling outside a mixin — official docs: this throws an error.
• Confusing with accepts-content — that checks capability on a mixin value, not this include.
• Empty braces surprise — @include m { } still counts as content passed.
• Forgetting @content — detecting content is useless if you never insert it.
• Expecting runtime checks — everything resolves when Sass compiles.

💡 Best Practices