Sass selector.unify() Function

What You’ll Learn

selector.unify() belongs to the built-in sass:selector module. It builds a selector that matches only elements matched by both inputs—or returns null when there is no expressible overlap. This page covers compounds, complex pairs, safe @if guards, and five compiled examples.

What Is selector.unify()?

Official docs: returns a selector that matches only elements matched by both $selector1 and $selector2. If the selectors do not overlap, or if Sass cannot express that overlap as a selector, the result is null.

• Simple compounds often merge: a + .disabled → a.disabled.
• Incompatible types return null: a + h1.
• Complex pairs can expand into multiple forms (similar ideas to @extend unification).
• Official caveat: when both sides are complex, the result is not guaranteed to match every element matched by both.

📝 Syntax

@use "sass:selector";

// Recommended
selector.unify($selector1, $selector2)

// Legacy global name
selector-unify($selector1, $selector2)

Parameters

Return value

📦 Loading sass:selector

// Recommended — namespaced (Dart Sass 1.23+)
@use "sass:selector";
$u: selector.unify("a", ".disabled"); // a.disabled

// Optional — bring members into scope
@use "sass:selector" as *;
$u: unify("a", ".disabled");

// Legacy global
$u: selector-unify("a", ".disabled");

🎨 Official Patterns

The last sample shows why complex unification can emit a comma list: ancestor order can vary, so Sass lists the sensible combinations.

⚖️ unify vs is-superselector

🛠 Compatibility

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

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

Examples Gallery

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

@use "sass:meta";
@use "sass:selector";

.probe {
  --compound: #{selector.unify("a", ".disabled")};
  --merge: #{selector.unify("a.disabled", "a.outgoing")};
  --null: #{meta.inspect(selector.unify("a", "h1"))};
  --complex: #{selector.unify(".warning a", "main a")};
}

.probe {
  --compound: a.disabled;
  --merge: a.disabled.outgoing;
  --null: null;
  --complex: .warning main a, main .warning a;
}

@use "sass:selector";

#{selector.unify(".btn", ".primary")} {
  background: teal;
}

.btn.primary {
  background: teal;
}

@use "sass:selector";

@mixin both($a, $b) {
  $u: selector.unify($a, $b);
  @if $u {
    #{$u} {
      outline: 2px solid currentColor;
    }
  }
}

@include both("a", ".disabled");
@include both("a", "h1");

a.disabled {
  outline: 2px solid currentColor;
}

@use "sass:selector";

.compare {
  --unify: #{selector.unify(".warning a", "main a")};
  --is-super: #{selector.is-superselector("a", ".warning a")};
}

.compare {
  --unify: .warning main a, main .warning a;
  --is-super: true;
}

@use "sass:selector";

@mixin try-unify($name, $a, $b) {
  $u: selector.unify($a, $b);
  @if $u {
    .ok-#{$name} {
      content: "#{$u}";
    }
  } @else {
    .no-#{$name} {
      content: "null";
    }
  }
}

@include try-unify("link", "a", ".link");
@include try-unify("featured", ".card", ".featured");
@include try-unify("lists", "ul", "ol");

.ok-link {
  content: "a.link";
}

.ok-featured {
  content: ".card.featured";
}

.no-lists {
  content: "null";
}

🚀 Real-World Use Cases

• Mixin APIs — combine a base selector with a modifier only when valid.
• Design-system guards — skip impossible pairs instead of emitting broken CSS.
• Compound builders — merge tag + class or class + class into one selector.
• Complex layout tooling — unify nested contexts like warning/main links.
• Debugging — print overlaps with meta.inspect, including null.

⚠️ Common Pitfalls

• Interpolating null — always guard with @if or print via meta.inspect.
• Assuming full coverage for complex pairs — official docs warn the result may not match every shared element.
• Confusing with append — append glues strings; unify computes overlap.
• Confusing with is-superselector — that returns a boolean, not a selector.
• Old compilers without modules — use Dart Sass 1.23+ for @use "sass:selector".

💡 Best Practices