Sass selector.replace()

Beginner
8 min read
Updated: Nov 2026
5 examples
Dart Sass 1.23+
Sass selector.replace swapping a selector piece with @extend-style unification
Definition

Definition and Usage

selector.replace($selector, $original, $replacement) returns a copy of $selector with all instances of $original swapped for $replacement, using the @extend rule’s intelligent unification. Load with @use "sass:selector".

Official sample idea.

replace("a.disabled", "a", ".link") → .disabled.link (the original a match is dropped).

Miss = unchanged.

If $selector does not contain $original, the function returns $selector as-is.

No parent selectors.

Placeholders are allowed; & is not. Need keep-and-add instead of a swap? Use selector.extend().

Syntax

Syntax

SCSS
@use "sass:selector";

selector.replace($selector, $original, $replacement) //=> selector

selector.replace("a.disabled", "a", ".link");
// .disabled.link

selector.replace("a.disabled", "h1", "h2");
// a.disabled  (unchanged — no match)

selector.replace(".guide .info", ".info", ".content nav.sidebar");
// .guide .content nav.sidebar, .content .guide nav.sidebar

// Use as a rule selector:
#{selector.replace(".btn.primary", ".btn", ".cta")} { ... }

// Global alias (legacy): selector-replace($selector, $original, $replacement)
// Prefer selector.replace after @use "sass:selector"

Pattern: pick what to swap → Sass unifies the replacement → interpolate with #{…} for CSS rules.

Reference

Replace vs Extend

Same arguments, different intent:

HelperTypical resultUse when
selector.replace.disabled.linkSwap $original for $replacement
selector.extenda.disabled, .disabled.linkKeep original and share styles with extender
Official contrast.

Docs point to selector.extend() when you want keep-and-add instead of substitution.

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 Replace Samples

Match found, no match, and complex unification.

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

How It Works

  1. Hit: a is swapped for .link.
  2. Miss: no h1 → return unchanged.
  3. Complex: replacement can expand into multiple selectors.
  4. Matches the official Sass docs samples.

Example 2 — Build Rule Selectors

Interpolate the replaced result into a real style rule.

SCSS
@use "sass:selector";

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

How It Works

  1. .btn is the piece to replace.
  2. .cta takes its place.
  3. .primary is kept through unification.
  4. Original dropped: no .btn.primary in the CSS.

Example 3 — Swap Base Mixin

Wrap replace so callers pass selector, original, and replacement.

SCSS
@use "sass:selector";

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

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

How It Works

  1. Mixin packages the three arguments.
  2. Same result as the official first sample.
  3. Reusable for class-alias helpers.
  4. Compile-time only — browsers see finished selectors.

Example 4 — Replace vs Extend

Same arguments, different intent.

SCSS
@use "sass:selector";

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

How It Works

  1. replace drops a.disabled.
  2. extend keeps the original match.
  3. Both produce .disabled.link.
  4. Choose replace when you want substitution only.

Example 5 — Alternate Class Loop

Replace one base class with several alternate names.

SCSS
@use "sass:selector";

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

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

How It Works

  1. $base is the selector to rewrite.
  2. @each supplies alternate replacements.
  3. .featured stays; .card is gone.
  4. Unlike extend, the original base is not kept.

Edge Cases & Pitfalls

Most replace bugs are confusing it with extend or passing &.

swap

Original is dropped

Need keep-and-add? Use selector.extend.

miss

No match = no change

If $original is absent, the selector returns unchanged.

&

Parent selectors forbidden

Placeholders are fine; do not pass &.

#{}

Interpolate for rules

Wrap results in #{…} to emit CSS selectors.

Toolchain

Sass Support

Prefer the module form with current Dart Sass.

APIStatus
selector.replace()Dart Sass 1.23+ via @use "sass:selector"
Return typeSelector
Parent selectorsNot allowed
Legacy globalselector-replace($selector, $original, $replacement)

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • Swaps $original for $replacement with @extend-style unification.
  • Miss stays unchanged when $original is absent.
  • vs extend — extend keeps the original match.
  • Prefer @use "sass:selector" (Dart Sass 1.23+).

One line: to swap a selector piece, use selector.replace($selector, $original, $replacement).

Practice

Compile Notes

Practical checklist:

checklist.txt
1. @use "sass:selector"
2. Pass $selector, $original, $replacement
3. Expect a swap (original is dropped)
4. Interpolate with #{} for CSS rules
5. Use extend when you want keep-and-add

Frequently Asked Questions

selector.replace($selector, $original, $replacement) returns a copy of $selector with all instances of $original replaced by $replacement, using @extend-style intelligent unification. Example: replace("a.disabled", "a", ".link") becomes .disabled.link.
replace swaps the original out. extend keeps the original and adds the extender form. Same args: replace → .disabled.link; extend → a.disabled, .disabled.link.
If $selector does not contain $original, the function returns $selector unchanged.
No. Arguments may contain placeholder selectors, but not parent selectors.
Yes. selector-replace($selector, $original, $replacement) is the legacy global name. Prefer selector.replace 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.simple-selectors()

Split a compound selector into its simple selector parts.

simple-selectors() →

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.parse Function Sass selector.simple-selectors Function