Sass selector.nest() Function

What You’ll Learn

selector.nest() belongs to the built-in sass:selector module. It combines selectors as if you nested them in a stylesheet—usually with a descendant space, or with & for compounds and BEM. This page covers lists, vs selector.append, and five compiled examples.

What Is selector.nest()?

Official docs: combines $selectors as though they were nested within one another in the stylesheet. Without &, that usually means a descendant combinator (a space): ul li, not ulli.

• Takes one or more selector arguments ($selectors...).
• Placeholder selectors are allowed.
• Unlike most selector functions, every argument except the first may contain parent selectors (&).
• See also selector.append() when you want no space between pieces.

📝 Syntax

@use "sass:selector";

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

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

Parameters

Return value

📦 Loading sass:selector

// Recommended — namespaced (Dart Sass 1.23+)
@use "sass:selector";
$sel: selector.nest("ul", "li"); // ul li

// Optional — bring members into scope
@use "sass:selector" as *;
$sel: nest(".alert", "&:hover"); // .alert:hover

// Legacy global
$sel: selector-nest("ul", "li");

🎨 Official Patterns

The last two show why & matters: without it, nesting would insert a space; with it, you get compounds and BEM-style names—the same way nested SCSS works.

⚖️ nest vs append

For BEM, both can produce .block__el: nest with &__el, or append with __el. Prefer the style that matches how you think about nesting.

🛠 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.nest at compile time (Dart Sass 1.23+). Open View Compiled CSS for verified output.

@use "sass:selector";

.probe {
  --ul: #{selector.nest("ul", "li")};
  --alert: #{selector.nest(".alert, .warning", "p")};
  --hover: #{selector.nest(".alert", "&:hover")};
  --bem: #{selector.nest(".accordion", "&__copy")};
}

.probe {
  --ul: ul li;
  --alert: .alert p, .warning p;
  --hover: .alert:hover;
  --bem: .accordion__copy;
}

@use "sass:selector";

#{selector.nest(".card", ".title")} {
  font-weight: 700;
}

#{selector.nest(".card, .panel", "p")} {
  margin: 0;
}

.card .title {
  font-weight: 700;
}

.card p, .panel p {
  margin: 0;
}

@use "sass:selector";

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

@include state(".btn", "&:hover");
@include state("a", "&:focus-visible");

.btn:hover {
  outline: 2px solid currentColor;
}

a:focus-visible {
  outline: 2px solid currentColor;
}

@use "sass:selector";

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

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

@use "sass:selector";

$block: ".nav";
$parts: "&__link", "&__icon", "&:hover";

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

.nav__link {
  display: inline-block;
}

.nav__icon {
  display: inline-block;
}

.nav:hover {
  display: inline-block;
}

🚀 Real-World Use Cases

• Programmatic nesting — build descendant selectors from string parts in mixins.
• State helpers — nest &:hover, &:focus-visible, or &.is-open.
• BEM tooling — nest &__el / &--mod onto a block name.
• List expansion — nest children under comma-separated parents in one call.
• Design-system APIs — accept a base selector and return nested variants at compile time.

⚠️ Common Pitfalls

• Expecting no space — without &, nest usually inserts a descendant space; use append or &.
• Putting & in the first argument — parent selectors belong in later arguments.
• Passing :hover without & — that nests as a descendant, not a compound.
• Forgetting interpolation — wrap results in #{…} to use them as rule selectors.
• Old compilers without modules — use Dart Sass 1.23+ for @use "sass:selector".

💡 Best Practices