Sass @extend Rule

What You’ll Learn

Sass @extend lets one selector inherit the styles of another by merging selectors in the compiled CSS. This page covers how extend works, placeholder selectors, !optional, module scope, when to prefer mixins, limitations, and five compiled examples.

What Is @extend?

Official docs: there are often cases when one class should have all the styles of another class, plus its own. Writing both classes in HTML (class="error error--serious") is cluttered and easy to forget.

Sass’s @extend rule is written @extend <selector>. It tells Sass that one selector should inherit the styles of another. When .error--serious extends .error, you can write only class="error--serious" in HTML and still get the base error styles.

• Unlike mixins, extend does not copy properties into the current rule.
• It updates rules that already mention the extended selector, adding the extender to those selector lists.
• Sass extends everywhere the selector is used—including :hover and other compounds.
• Extends are resolved after the rest of the stylesheet (including parent selectors).

📝 Syntax

.error {
  border: 1px #f00;
  background-color: #fdd;

  &--serious {
    @extend .error;
    border-width: 3px;
  }
}

Compiled CSS shares the base rule between .error and .error--serious, then adds the modifier-only declaration separately.

⚙️ How It Works

Official docs: when extending selectors, Sass does intelligent unification. It never generates impossible selectors (like #main#footer), interleaves complex selectors safely, trims redundancy, and handles combinators and many pseudo-classes.

• Incompatible types are skipped (e.g. extending .info from nav will not touch p.info).
• Cascade order follows where the extended rule appears—not where @extend is written.
• Parent-selector nesting like .error { &__icon { … } } is not extended when you @extend .error (extends run after nesting is resolved).

🚫 Placeholder Selectors

Official docs: when a style rule is only meant to be extended, use a placeholder selector—a class-like name that starts with % instead of ..

• Selectors that include unused placeholders are omitted from CSS.
• Extenders appear in the output in place of the placeholder.
• Private placeholders start with - or _ and can only be extended in the same stylesheet (like private module members).

%message-shared {
  border: 1px solid #ccc;
  padding: 10px;
}

.message {
  @extend %message-shared;
}

🔒 Mandatory, Optional & Scope

Mandatory vs !optional

By default, if @extend matches nothing, Sass errors (protects against typos). Add !optional when a missing target should be ignored: @extend %theme-btn !optional.

Extension scope with @use

Official docs: when one stylesheet extends a selector, that extension only affects upstream modules loaded with @use / @forward (and their upstreams). That keeps extends predictable.

⚖️ Extends or Mixins?

Official rule of thumb: use @extend when you express a relationship between semantic classes (an .error--serious is an error). For non-semantic style chunks—or anything that needs arguments—prefer a mixin.

• Mixins can take arguments and @content; extends cannot.
• Mixins may emit more CSS, but gzip/brotli usually handle repetition well.
• Choose clarity over “smallest CSS” unless you have measured a problem.

🚫 Limitations

Only simple selectors

You can extend simple selectors like .info or a—not compounds like .message.info or descendants like .main .info. Write @extend .message, .info instead.

HTML heuristics

When interleaving complex selectors, Sass does not generate every possible ancestor combination (that would explode CSS size). It assumes each selector’s ancestors are mostly self-contained.

Inside @media

You may use @extend inside @media, but you cannot extend a selector that appears outside that at-rule. Keep both the extender and the extended rule in the same media context.

Examples Gallery

Each example uses @extend at compile time. Open View Compiled CSS for verified output.

.error {
  border: 1px #f00;
  background-color: #fdd;

  &--serious {
    @extend .error;
    border-width: 3px;
  }
}

.error, .error--serious {
  border: 1px #f00;
  background-color: #fdd;
}
.error--serious {
  border-width: 3px;
}

.error:hover {
  background-color: #fee;
}

.error--serious {
  @extend .error;
  border-width: 3px;
}

.error:hover, .error--serious:hover {
  background-color: #fee;
}

.error--serious {
  border-width: 3px;
}

%message-shared {
  border: 1px solid #ccc;
  padding: 10px;
  color: #333;
}

.message {
  @extend %message-shared;
}

.success {
  @extend %message-shared;
  border-color: green;
}

.warning {
  @extend %message-shared;
  border-color: yellow;
}

.warning, .success, .message {
  border: 1px solid #ccc;
  padding: 10px;
  color: #333;
}

.success {
  border-color: green;
}

.warning {
  border-color: yellow;
}

.content nav.sidebar {
  @extend .info;
}

// Not extended: `p` is incompatible with `nav`.
p.info {
  background-color: #dee9fc;
}

.guide .info {
  border: 1px solid rgba(#000, 0.8);
  border-radius: 2px;
}

main.content .info {
  font-size: 0.8em;
}

p.info {
  background-color: #dee9fc;
}

.guide .info, .guide .content nav.sidebar, .content .guide nav.sidebar {
  border: 1px solid rgba(0, 0, 0, 0.8);
  border-radius: 2px;
}

main.content .info, main.content nav.sidebar {
  font-size: 0.8em;
}

%btn {
  display: inline-block;
  padding: 0.5rem 1rem;
  border-radius: 4px;
}

.primary {
  @extend %btn;
  background: #036;
  color: #fff;
}

.ghost {
  @extend %btn !optional;
  border: 1px solid #036;
}

.missing-extender {
  @extend %does-not-exist !optional;
  opacity: 0.8;
}

.ghost, .primary {
  display: inline-block;
  padding: 0.5rem 1rem;
  border-radius: 4px;
}

.primary {
  background: #036;
  color: #fff;
}

.ghost {
  border: 1px solid #036;
}

.missing-extender {
  opacity: 0.8;
}

🚀 Real-World Use Cases

• BEM modifiers — .error--serious inherits .error.
• Silent utilities — %truncate, %btn shared bases.
• Theme variants — success / warning / info message shells.
• Design-system tokens as classes — semantic relationships, not config.
• Library internals — private %-internal placeholders.

⚠️ Common Pitfalls

• Cascade surprises — precedence follows the extended rule’s location, not the @extend line.
• Expecting nested & to extend — extends run after nesting is resolved.
• Compound extends — do not write @extend .a.b; extend simple selectors.
• Cross-media extends — cannot extend a selector defined outside the current @media.
• Overusing extend for utilities — mixins are often clearer for non-semantic chunks.

💡 Best Practices