Sass selector.is-superselector() Function

What You’ll Learn

selector.is-superselector() belongs to the built-in sass:selector module. It asks: does selector A match every element that selector B matches? This page covers $super vs $sub, official link examples, branching helpers, and five compiled examples.

What Is selector.is-superselector()?

Official docs: returns whether the selector $super matches all the elements that the selector $sub matches. It still returns true when $super matches more elements than $sub.

• $super is the broader / covering selector; $sub is the narrower one.
• Equal selectors return true (a selector covers itself).
• Arguments may be strings or selector values; placeholders are allowed.
• Parent selectors (&) are not allowed in either argument.

📝 Syntax

@use "sass:selector";

// Recommended
selector.is-superselector($super, $sub)

// Legacy global name
is-superselector($super, $sub)

Parameters

Return value

📦 Loading sass:selector

// Recommended — namespaced (Dart Sass 1.23+)
@use "sass:selector";
$ok: selector.is-superselector("a", "a.disabled");

// Optional — bring members into scope
@use "sass:selector" as *;
$ok: is-superselector("a", "a.disabled");

// Legacy global
$ok: is-superselector("a", "a.disabled");

⚖️ Reading $super vs $sub

Official examples make the direction clear:

📋 Related Selector Helpers

🛠 Compatibility

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

Prefer current Dart Sass so the module API matches the official docs.

Examples Gallery

Each example uses selector.is-superselector at compile time (Dart Sass 1.23+). Open View Compiled CSS for verified output.

@use "sass:selector";

.probe {
  --a-over-disabled: #{selector.is-superselector("a", "a.disabled")};
  --disabled-over-a: #{selector.is-superselector("a.disabled", "a")};
  --a-over-sidebar: #{selector.is-superselector("a", "sidebar a")};
  --sidebar-over-a: #{selector.is-superselector("sidebar a", "a")};
  --same: #{selector.is-superselector("a", "a")};
}

.probe {
  --a-over-disabled: true;
  --disabled-over-a: false;
  --a-over-sidebar: true;
  --sidebar-over-a: false;
  --same: true;
}

@use "sass:selector";

.probe {
  --btn-over-primary: #{selector.is-superselector(".btn", ".btn.primary")};
  --primary-over-btn: #{selector.is-superselector(".btn.primary", ".btn")};
  --equal: #{selector.is-superselector(".btn", ".btn")};
}

.probe {
  --btn-over-primary: true;
  --primary-over-btn: false;
  --equal: true;
}

@use "sass:selector";

@mixin maybe-base($base, $specific) {
  @if selector.is-superselector($base, $specific) {
    #{$base} {
      --covers: true;
      color: teal;
    }
  } @else {
    #{$base} {
      --covers: false;
      color: tomato;
    }
  }
}

@include maybe-base("a", "a.disabled");
@include maybe-base("a.disabled", "a");

a {
  --covers: true;
  color: teal;
}

a.disabled {
  --covers: false;
  color: tomato;
}

@use "sass:selector";

.flags {
  --descendant: #{selector.is-superselector("h1", "main h1")};
  --too-narrow: #{selector.is-superselector("main h1", "h1")};
  --same: #{selector.is-superselector(".card", ".card")};
}

.flags {
  --descendant: true;
  --too-narrow: false;
  --same: true;
}

@use "sass:selector";

@function covers($super, $sub) {
  @return selector.is-superselector($super, $sub);
}

$base: ".nav a";
$item: ".nav a.active";
$other: "footer a";

.report {
  --nav-covers-active: #{covers($base, $item)};
  --nav-covers-footer: #{covers($base, $other)};
  --active-covers-nav: #{covers($item, $base)};
}

.report {
  --nav-covers-active: true;
  --nav-covers-footer: false;
  --active-covers-nav: false;
}

🚀 Real-World Use Cases

• API validation — ensure a “base” selector really covers a more specific one.
• Mixin guards — skip redundant nesting when a selector already covers another.
• Design-system checks — confirm BEM modifiers stay under their block class.
• Selector tooling — build compile-time reports for theme or layout packs.
• Safer abstractions — fail early when callers invert broad and narrow selectors.

⚠️ Common Pitfalls

• Swapping arguments — broader selector must be $super, not $sub.
• Parent selectors — & is not allowed in either argument.
• Thinking “contains string” — this is about matched elements, not substring checks.
• Expecting runtime — everything resolves when Sass compiles.
• Old compilers without modules — use Dart Sass 1.23+ for @use "sass:selector".

💡 Best Practices