Sass selector.is-superselector()

Beginner
8 min read
Updated: Nov 2026
5 examples
Dart Sass 1.23+
Sass selector.is-superselector checking whether one selector covers another
Definition

Definition and Usage

selector.is-superselector($super, $sub) returns a boolean: whether $super matches all elements that $sub matches. It can still be true when $super also matches extra elements. Load with @use "sass:selector".

Official sample idea.

is-superselector("a", "a.disabled") is true (every disabled link is an a); swap the arguments and it is false.

Broader first.

Pass the covering selector as $super and the narrower one as $sub. Argument order matters.

No parent selectors.

Placeholders are allowed; & is not. Need intersection instead of coverage? See selector.unify().

Syntax

Syntax

SCSS
@use "sass:selector";

selector.is-superselector($super, $sub) //=> boolean

selector.is-superselector("a", "a.disabled"); // true
selector.is-superselector("a.disabled", "a"); // false
selector.is-superselector("a", "sidebar a"); // true
selector.is-superselector("sidebar a", "a"); // false
selector.is-superselector("a", "a"); // true

// Branch at compile time:
@if selector.is-superselector($base, $specific) { ... }

// Global alias (legacy): is-superselector($super, $sub)
// Prefer selector.is-superselector after @use "sass:selector"

Pattern: ask “does $super cover every match of $sub?” → get true/false → branch with @if.

Reference

$super vs $sub

Official coverage checks at a glance:

CallResultWhy
is-superselector("a", "a.disabled")trueEvery disabled link is an a
is-superselector("a.disabled", "a")falseNot every a is disabled
is-superselector("a", "sidebar a")trueEvery sidebar link is still an a
is-superselector("sidebar a", "a")falseNot every a is in a sidebar
is-superselector("a", "a")trueA selector covers itself
Code

SCSS Examples

Examples use @use "sass:selector". Open View Compiled CSS for verified Dart Sass output (matches official Sass docs samples where shown).

Example 1 — Official Link Checks

Reproduce the Sass docs samples as CSS custom properties.

SCSS
@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")};
}

How It Works

  1. Broader first returns true.
  2. Swap arguments and one-way coverage becomes false.
  3. Descendants of a are still covered by a.
  4. Equals always cover themselves.

Example 2 — Class vs Modifier

A base class covers a more specific compound selector.

SCSS
@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")};
}

How It Works

  1. .btn covers every .btn.primary.
  2. .btn.primary does not cover every .btn.
  3. Equal selectors cover each other.
  4. Same idea as the official link samples.

Example 3 — Branch on Coverage

Emit different rules depending on whether the base covers the specific selector.

SCSS
@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");

How It Works

  1. First include: a covers a.disabled.
  2. Second include: a.disabled cannot cover every a.
  3. @if picks the teal or tomato branch.
  4. Useful for validating mixin APIs at compile time.

Example 4 — Element vs Descendant

An element selector covers a descendant form of itself; the reverse does not.

SCSS
@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")};
}

How It Works

  1. Every main h1 is still an h1.
  2. Not every h1 lives inside main.
  3. Same selector covers itself.
  4. Matches the official sidebar a pattern.

Example 5 — Nav Coverage Helper

Wrap the check in a small function for reusable reports.

SCSS
@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)};
}

How It Works

  1. .nav a covers its active state.
  2. Footer links are outside that coverage.
  3. Active is too narrow to cover every nav link.
  4. @function keeps the check reusable.

Edge Cases & Pitfalls

Most is-superselector bugs are swapped arguments or passing &.

order

Broader selector first

$super must be the covering selector; order is not symmetric.

&

Parent selectors forbidden

Placeholders are fine; do not pass &.

extra

Extra matches are OK

$super may match more elements than $sub and still return true.

compile

Compile-time only

Browsers never see the check—only finished CSS.

Toolchain

Sass Support

Prefer the module form with current Dart Sass.

APIStatus
selector.is-superselector()Dart Sass 1.23+ via @use "sass:selector"
Return typeBoolean
Parent selectorsNot allowed
Legacy globalis-superselector($super, $sub)

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • Returns true/false for whether $super covers $sub.
  • Broader first — argument order is not symmetric.
  • Extra matches OK — $super may match more than $sub.
  • Prefer @use "sass:selector" (Dart Sass 1.23+).

One line: to ask whether one selector covers another, use selector.is-superselector($super, $sub).

Practice

Compile Notes

Practical checklist:

checklist.txt
1. @use "sass:selector"
2. Pass broader selector as $super
3. Pass narrower selector as $sub
4. Branch with @if on the boolean
5. Do not pass parent selectors (&)

Frequently Asked Questions

selector.is-superselector($super, $sub) returns true if $super matches every element that $sub matches. It can still be true when $super matches extra elements beyond $sub.
Pass the broader (covering) selector as $super and the narrower one as $sub. Example: is-superselector("a", "a.disabled") is true because every a.disabled is also an a.
No. $super and $sub may contain placeholder selectors, but not parent selectors.
Yes. is-superselector("a.disabled", "a") is false—a.disabled does not match every a.
Yes. is-superselector($super, $sub) is the legacy global name. Prefer selector.is-superselector after @use "sass:selector".
Dart Sass 1.23+. LibSass and Ruby Sass do not load sass:selector with @use; they may still offer the legacy global name.

Next: Sass selector.nest()

Combine selectors as if they were nested in the stylesheet.

selector.nest() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

8 people found this page helpful

Sass selector.extend Function Sass selector.nest Function