Sass selector.append()

Beginner
8 min read
Updated: Nov 2026
5 examples
Dart Sass 1.23+
Sass selector.append combining selectors without descendant spaces
Definition

Definition and Usage

selector.append($selectors...) combines selectors without descendant combinators—no whitespace between them. You get compounds like a.disabled or BEM names like .accordion__copy. Load with @use "sass:selector".

Official sample idea.

selector.append("a", ".disabled") → a.disabled; append(".accordion", "__copy") → .accordion__copy.

Selector lists expand.

If any argument is a comma list, each complex selector is combined separately: append(".accordion", "__copy, __image") → .accordion__copy, .accordion__image.

No parent selectors.

Placeholders are allowed; & is not. Need nesting or &? Use selector.nest().

Syntax

Syntax

SCSS
@use "sass:selector";

selector.append($selectors...) //=> selector

selector.append("a", ".disabled"); // a.disabled
selector.append(".accordion", "__copy"); // .accordion__copy
selector.append(".accordion", "__copy, __image");
// .accordion__copy, .accordion__image

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

// Global alias (legacy): selector-append($selectors...)
// Prefer selector.append after @use "sass:selector"

Pattern: pass pieces → get a glued selector → interpolate with #{…} when you need a CSS rule.

Reference

Append vs Nest

Same arguments, different combinators:

HelperTypical resultUse when
selector.append.alert.warn (no space)Same element, BEM suffix, compound class
selector.nest.alert .warn or .alert:hover with &Nested stylesheet behavior / parent selectors
Official contrast.

Docs point you to selector.nest() when you want nesting instead of glue.

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

Compound class, BEM suffix, and a suffix list from the docs.

SCSS
@use "sass:selector";

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

How It Works

  1. No spaces are inserted between pieces.
  2. a + .disabled becomes one compound selector.
  3. __copy glues onto .accordion as BEM.
  4. List suffixes each get the same prefix.

Example 2 — Build Rule Selectors

Interpolate the result to create real style rules.

SCSS
@use "sass:selector";

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

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

How It Works

  1. #{…} turns the selector value into a rule.
  2. .btn.primary is one compound class.
  3. The list expands to two rules sharing styles.
  4. Still no descendant spaces.

Example 3 — State / Pseudo Mixin

Append a modifier or pseudo-class onto a base selector.

SCSS
@use "sass:selector";

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

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

How It Works

  1. Mixin accepts any base + modifier strings.
  2. .focus becomes a compound class on .card.
  3. :hover appends as a pseudo-class on a.
  4. Same helper covers classes and pseudos.

Example 4 — BEM Elements Loop

Build several block__element selectors from one block name.

SCSS
@use "sass:selector";

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

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

How It Works

  1. $block holds the BEM block class.
  2. @each walks element suffixes.
  3. append glues each __* onto the block.
  4. Scales the official accordion sample.

Example 5 — Append vs Nest Side by Side

Same arguments, different combinators.

SCSS
@use "sass:selector";

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

How It Works

  1. append keeps one compound selector.
  2. nest inserts a descendant space.
  3. Choose append for same-element modifiers.
  4. Choose nest for nesting / &.

Edge Cases & Pitfalls

Most append bugs are expecting a space or passing &.

space

No descendant combinator

Need .alert .warn? Use selector.nest.

&

Parent selectors forbidden

Placeholders are fine; pass & only to nest.

#{}

Interpolate for rules

Wrap results in #{…} to use them as CSS selectors.

strings

Keep pieces clean

Leading spaces in strings can produce odd compounds.

Toolchain

Sass Support

Prefer the module form with current Dart Sass.

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

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • Glues selectors with no descendant whitespace.
  • Lists expand so each complex selector gets the prefix.
  • No & — use nest for parent selectors and descendants.
  • Prefer @use "sass:selector" (Dart Sass 1.23+).

One line: to stick selectors onto the same element, use selector.append($selectors...).

Practice

Compile Notes

Practical checklist:

checklist.txt
1. @use "sass:selector"
2. Pass clean selector pieces (no leading spaces)
3. Expect compounds / BEM glue — not descendant spaces
4. Interpolate with #{} for CSS rules
5. Use nest when you need & or nesting

Frequently Asked Questions

selector.append($selectors...) combines selectors without descendant combinators—no whitespace between them. Example: append("a", ".disabled") becomes a.disabled.
append glues pieces together (a.disabled, .block__el). nest combines as if nested in the stylesheet, usually with a descendant space (ul li) unless you use &.
If any argument is a selector list, each complex selector is combined separately. append(".accordion", "__copy, __image") becomes .accordion__copy, .accordion__image.
No. Arguments may contain placeholder selectors, but not parent selectors. Use selector.nest when you need &.
Yes. selector-append($selectors...) is the legacy global name. Prefer selector.append 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.extend()

Extend a selector the same way the @extend rule does.

selector.extend() →

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 meta.variable-exists Function Sass selector.extend Function