Sass selector.append() Function

What You’ll Learn

selector.append() belongs to the built-in sass:selector module. It glues selectors together without a descendant space—perfect for compound selectors and BEM-style suffixes. This page covers selector lists, vs selector.nest, and five compiled examples.

What Is selector.append()?

Official docs: combines $selectors without descendant combinators—that is, without whitespace between them. Use it when you want a.disabled or .accordion__copy, not a .disabled.

• Takes one or more selector arguments ($selectors...).
• If any argument is a selector list, each complex selector is combined separately.
• Placeholder selectors are allowed; parent selectors (&) are not.
• See also selector.nest() when you want nesting / descendant behavior.

📝 Syntax

@use "sass:selector";

// Recommended
selector.append($selectors...)

// Legacy global name
selector-append($selectors...)

Parameters

Return value

📦 Loading sass:selector

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

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

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

🎨 Official Patterns

The list case is the key detail: each side of the comma is appended separately to .accordion.

⚖️ append vs nest

🛠 Compatibility

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

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

Examples Gallery

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

@use "sass:selector";

.probe {
  --disabled: #{selector.append("a", ".disabled")};
  --bem: #{selector.append(".accordion", "__copy")};
  --list: #{selector.append(".accordion", "__copy, __image")};
}

.probe {
  --disabled: a.disabled;
  --bem: .accordion__copy;
  --list: .accordion__copy, .accordion__image;
}

@use "sass:selector";

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

#{selector.append(".btn", ".primary, .danger")} {
  font-weight: 700;
}

.btn.primary {
  background: teal;
}

.btn.primary, .btn.danger {
  font-weight: 700;
}

@use "sass:selector";

@mixin state($base, $mod) {
  #{selector.append($base, $mod)} {
    outline: 2px solid currentColor;
  }
}

@include state(".card", ".focus");
@include state("a", ":hover");

.card.focus {
  outline: 2px solid currentColor;
}

a:hover {
  outline: 2px solid currentColor;
}

@use "sass:selector";

$block: ".menu";
$parts: "__item", "__link", "__icon";

@each $part in $parts {
  #{selector.append($block, $part)} {
    display: block;
  }
}

.menu__item {
  display: block;
}

.menu__link {
  display: block;
}

.menu__icon {
  display: block;
}

@use "sass:selector";

.compare {
  --append: #{selector.append(".alert", ".warn")};
  --nest: #{selector.nest(".alert", ".warn")};
}

.compare {
  --append: .alert.warn;
  --nest: .alert .warn;
}

🚀 Real-World Use Cases

• BEM tooling — build block__element and block--mod names from parts.
• State helpers — append .is-active, :hover, or :focus-visible.
• Component APIs — accept a base selector string and glue modifiers in mixins.
• Selector lists — expand one prefix across several suffixes in one call.
• Design-system codegen — loop tokens into consistent class names at compile time.

⚠️ Common Pitfalls

• Expecting a space — use selector.nest for descendants.
• Parent selectors — & is not allowed in append arguments.
• Forgetting interpolation — wrap results in #{…} to use them as rule selectors.
• Accidental spaces in strings — " .mod" can produce odd compounds; keep pieces clean.
• Old compilers without modules — use Dart Sass 1.23+ for @use "sass:selector".

💡 Best Practices