Sass Placeholder Selectors

What You’ll Learn

Sass placeholder selectors start with %. They work like classes for @extend, but unused placeholders never appear in the CSS—perfect for optional library styles. Five compiled examples follow.

What Are Placeholder Selectors?

A placeholder looks and acts a lot like a class selector, but it starts with % (for example %toolbelt) and is not included in the CSS output by itself.

• Any complex selector (the parts between commas) that contains a placeholder is omitted.
• A whole style rule is omitted when every selector in its list contains a placeholder.
• Placeholders become useful when another selector @extends them.
• Unlike extending a class, unused placeholders do not leave dead CSS behind.

📝 Basic Syntax

.alert:hover, %strong-alert {
  font-weight: bold;
}

%strong-alert:hover {
  color: red;
}
// Only .alert:hover survives in CSS until something @extends %strong-alert

The second rule is dropped entirely because its only selector contains a placeholder. The first rule keeps .alert:hover and drops the %strong-alert branch.

🔗 Extending Placeholders

Placeholders exist to be extended. Library authors can ship reusable style chunks without requiring a fixed HTML class name. Consumers write their own classes and @extend %name.

%toolbelt {
  box-sizing: border-box;
  padding: 16px 0;
  width: 100%;

  &:hover { border: 2px solid rgba(#000, 0.5); }
}

.action-buttons {
  @extend %toolbelt;
  color: #4285f4;
}

⚖️ Placeholders vs Class Selectors

Examples Gallery

Each example is verified with Dart Sass. Open View Compiled CSS for output.

.alert:hover, %strong-alert {
  font-weight: bold;
}

%strong-alert:hover {
  color: red;
}

.alert:hover {
  font-weight: bold;
}

%toolbelt {
  box-sizing: border-box;
  border-top: 1px rgba(#000, .12) solid;
  padding: 16px 0;
  width: 100%;

  &:hover { border: 2px rgba(#000, .5) solid; }
}

.action-buttons {
  @extend %toolbelt;
  color: #4285f4;
}

.reset-buttons {
  @extend %toolbelt;
  color: #cddc39;
}

.reset-buttons, .action-buttons {
  box-sizing: border-box;
  border-top: 1px rgba(0, 0, 0, 0.12) solid;
  padding: 16px 0;
  width: 100%;
}
.reset-buttons:hover, .action-buttons:hover {
  border: 2px rgba(0, 0, 0, 0.5) solid;
}

.action-buttons {
  color: #4285f4;
}

.reset-buttons {
  color: #cddc39;
}

%center {
  display: flex;
  align-items: center;
  justify-content: center;
}

.hero {
  @extend %center;
  min-height: 40vh;
}

.modal {
  @extend %center;
  position: fixed;
  inset: 0;
}

.modal, .hero {
  display: flex;
  align-items: center;
  justify-content: center;
}

.hero {
  min-height: 40vh;
}

.modal {
  position: fixed;
  inset: 0;
}

%card {
  border-radius: 8px;
  padding: 1rem;
  background: #fff;
}

%card--shadow {
  @extend %card;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.12);
}

.product-card {
  @extend %card--shadow;
  border: 1px solid #e0e0e0;
}

.profile-card {
  @extend %card;
  border: 1px solid #90caf9;
}

.profile-card, .product-card {
  border-radius: 8px;
  padding: 1rem;
  background: #fff;
}

.product-card {
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.12);
}

.product-card {
  border: 1px solid #e0e0e0;
}

.profile-card {
  border: 1px solid #90caf9;
}

%unused-lib-style {
  outline: 2px dashed red;
}

.button {
  padding: 0.5rem 1rem;
  background: #036;
  color: #fff;
}

.button {
  padding: 0.5rem 1rem;
  background: #036;
  color: #fff;
}

🚀 Real-World Use Cases

• Component libraries — ship optional skins consumers @extend.
• Silent utilities — shared layout helpers without utility class spam in HTML.
• Design system tokens as rules — group borders, radii, and shadows under %.
• Theme packs — include many placeholders; only extended ones cost CSS weight.
• Avoiding API lock-in — let users choose their own class names in markup.

⚠️ Common Pitfalls

• Expecting % in HTML — placeholders are Sass-only; use real classes in markup.
• Overusing @extend — deep extend graphs can surprise you; mixins are often clearer for parameterized styles.
• Forgetting nothing extends it — then zero CSS is emitted (usually good—unless you meant to include it).
• Extending across media queries carelessly — @extend has limits across contexts; see the @extend page.
• Using placeholders for every app class — if the class is already in your HTML, a normal class may be simpler.

💡 Best Practices