Sass selector.replace() Function

What You’ll Learn

selector.replace() belongs to the built-in sass:selector module. It returns a copy of a selector with one piece swapped for another, using the same intelligent unification as @extend. This page covers the three arguments, vs selector.extend, and five compiled examples.

What Is selector.replace()?

Official docs: returns a copy of $selector with all instances of $original replaced by $replacement. It uses the @extend rule’s intelligent unification so the replacement fits into the surrounding selector. If $selector never contains $original, the value is returned unchanged.

• Three arguments: the selector to rewrite, what to find, and what to put instead.
• Placeholder selectors are allowed; parent selectors (&) are not.
• See also selector.extend() when you want to keep the original and add a form.

📝 Syntax

@use "sass:selector";

// Recommended
selector.replace($selector, $original, $replacement)

// Legacy global name
selector-replace($selector, $original, $replacement)

Parameters

Return value

📦 Loading sass:selector

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

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

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

🎨 Official Patterns

Unlike extend, the first sample does not keep a.disabled—only the replaced form remains. Dart Sass may print compound classes in a different simple-selector order (for example .disabled.link); matching is the same as .link.disabled.

⚖️ replace vs extend

🛠 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.replace at compile time (Dart Sass 1.23+). Open View Compiled CSS for verified output.

@use "sass:selector";

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

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

@use "sass:selector";

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

.primary.cta {
  background: teal;
}

@use "sass:selector";

@mixin swap-base($selector, $original, $replacement) {
  #{selector.replace($selector, $original, $replacement)} {
    color: inherit;
  }
}

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

.disabled.link {
  color: inherit;
}

@use "sass:selector";

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

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

@use "sass:selector";

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

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

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

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

🚀 Real-World Use Cases

• Class aliases — map .btn.primary styles onto .cta.primary only.
• Theme swaps — replace a brand base class without leaving the old selector.
• Mixin APIs — accept selector strings and emit swapped rule lists.
• Complex layouts — unify nested replacements like the official guide/info sample.
• Safe defaults — no-op when $original is absent (returns the original).

⚠️ Common Pitfalls

• Confusing with extend — replace drops the original; extend keeps it.
• Parent selectors — & is not allowed in these arguments.
• Wrong argument order — remember selector, then original, then replacement.
• Forgetting interpolation — wrap results in #{…} to use them as rule selectors.
• Expecting plain string replace — this is selector unification, not text search.

💡 Best Practices