Sass selector.extend() Function

What You’ll Learn

selector.extend() belongs to the built-in sass:selector module. It rewrites a selector the same way the @extend rule would—keeping the original and adding extended forms. This page covers the three arguments, vs selector.replace, and five compiled examples.

What Is selector.extend()?

Official docs: extends $selector as with the @extend rule. It returns a copy of $selector modified as if this ran:

#{$extender} {
  @extend #{$extendee};
}

In plain terms: wherever $extendee appears in $selector, Sass keeps that match and adds forms that use $extender instead. If $selector never contains $extendee, the value is returned unchanged.

• Three arguments: the selector to rewrite, what to extend from, and what extends it.
• Placeholder selectors are allowed; parent selectors (&) are not.
• See also selector.replace() when you want a swap instead of an add-on.

📝 Syntax

@use "sass:selector";

// Recommended
selector.extend($selector, $extendee, $extender)

// Legacy global name
selector-extend($selector, $extendee, $extender)

Parameters

Return value

📦 Loading sass:selector

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

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

// Legacy global
$sel: selector-extend("a.disabled", "a", ".link");

🎨 Official Patterns

The third sample shows intelligent unification: complex extenders can produce more than one new complex selector, not just a simple class swap. Dart Sass may print compound classes in a different simple-selector order (for example .disabled.link); matching is the same.

⚖️ extend vs replace

🛠 Compatibility

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

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

Examples Gallery

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

@use "sass:selector";

.probe {
  --link: #{selector.extend("a.disabled", "a", ".link")};
  --miss: #{selector.extend("a.disabled", "h1", "h2")};
  --guide: #{selector.extend(".guide .info", ".info", ".content nav.sidebar")};
}

.probe {
  --link: a.disabled, .disabled.link;
  --miss: a.disabled;
  --guide: .guide .info, .guide .content nav.sidebar, .content .guide nav.sidebar;
}

@use "sass:selector";

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

.btn.primary, .primary.cta {
  background: teal;
}

@use "sass:selector";

@mixin share-styles($selector, $extendee, $extender) {
  #{selector.extend($selector, $extendee, $extender)} {
    color: inherit;
  }
}

@include share-styles("a.disabled", "a", ".link");

a.disabled, .disabled.link {
  color: inherit;
}

@use "sass:selector";

.compare {
  --extend: #{selector.extend("a.disabled", "a", ".link")};
  --replace: #{selector.replace("a.disabled", "a", ".link")};
}

.compare {
  --extend: a.disabled, .disabled.link;
  --replace: .disabled.link;
}

@use "sass:selector";

$base: ".card.featured";
$alts: ".promo", ".highlight";

@each $alt in $alts {
  #{selector.extend($base, ".card", $alt)} {
    border-width: 2px;
  }
}

.card.featured, .featured.promo {
  border-width: 2px;
}

.card.featured, .featured.highlight {
  border-width: 2px;
}

🚀 Real-World Use Cases

• Shared state styles — let .link.disabled share rules with a.disabled.
• Design-system aliases — map alternate class names onto a canonical compound.
• Mixin APIs — accept selector strings and emit extended rule lists.
• Complex layouts — unify nested extenders like the official guide/info sample.
• Safe defaults — no-op when $extendee is absent (returns the original).

⚠️ Common Pitfalls

• Confusing with replace — extend keeps the original; replace swaps it out.
• Parent selectors — & is not allowed in these arguments.
• Wrong argument order — remember selector, then extendee, then extender.
• Forgetting interpolation — wrap results in #{…} to use them as rule selectors.
• Expecting CSS @extend — this is a Sass function result, not a browser feature.

💡 Best Practices