Sass selector.simple-selectors() Function

What You’ll Learn

selector.simple-selectors() belongs to the built-in sass:selector module. It splits one compound selector into its simple pieces—tags, classes, IDs, and pseudos. This page covers the compound-only rule, list helpers, and five compiled examples.

What Is selector.simple-selectors()?

Official docs: returns a list of simple selectors in $selector. The argument must be a single string that contains a compound selector—no combinators (including spaces) and no commas.

• The returned list is comma-separated.
• Each simple selector is an unquoted string (a, .disabled, :after).
• Use sass:list / @each to walk the parts.
• For full selector lists with spaces or commas, use selector.parse() instead.

📝 Syntax

@use "sass:selector";

// Recommended
selector.simple-selectors($selector)

// Legacy global name
simple-selectors($selector)

Parameters

Return value

📦 Loading sass:selector

// Recommended — namespaced (Dart Sass 1.23+)
@use "sass:selector";
$parts: selector.simple-selectors("a.disabled"); // a, .disabled

// Optional — bring members into scope
@use "sass:selector" as *;
$parts: simple-selectors("main.blog:after");

// Legacy global
$parts: simple-selectors("a.disabled");

🎨 Official Patterns

Tags, classes, and pseudo-elements/classes all count as separate simple selectors when they sit in the same compound.

⚖️ simple-selectors vs parse

🛠 Compatibility

This is about Sass compilers, not browsers. Splitting happens at compile time.

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

Examples Gallery

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

@use "sass:list";
@use "sass:meta";
@use "sass:selector";

$parts: selector.simple-selectors("a.disabled");
$parts2: selector.simple-selectors("main.blog:after");

.probe {
  --disabled: #{meta.inspect($parts)};
  --blog: #{meta.inspect($parts2)};
  --len: #{list.length($parts2)};
}

.probe {
  --disabled: a, .disabled;
  --blog: main, .blog, :after;
  --len: 3;
}

@use "sass:list";
@use "sass:meta";
@use "sass:selector";

$parts: selector.simple-selectors("button.btn.primary:hover");

.probe {
  --1: #{meta.inspect(list.nth($parts, 1))};
  --2: #{meta.inspect(list.nth($parts, 2))};
  --3: #{meta.inspect(list.nth($parts, 3))};
  --4: #{meta.inspect(list.nth($parts, 4))};
}

.probe {
  --1: button;
  --2: .btn;
  --3: .primary;
  --4: :hover;
}

@use "sass:selector";

@mixin each-simple($compound) {
  @each $simple in selector.simple-selectors($compound) {
    .part {
      content: "#{$simple}";
    }
  }
}

@include each-simple("a.disabled");

.part {
  content: "a";
}

.part {
  content: ".disabled";
}

@use "sass:list";
@use "sass:meta";
@use "sass:selector";

$parts: selector.simple-selectors(".card.featured.is-active");

.probe {
  --count: #{list.length($parts)};
  --first: #{meta.inspect(list.nth($parts, 1))};
  --last: #{meta.inspect(list.nth($parts, -1))};
  --rebuilt: #{selector.append(list.nth($parts, 1), list.nth($parts, 2))};
}

.probe {
  --count: 3;
  --first: .card;
  --last: .is-active;
  --rebuilt: .card.featured;
}

@use "sass:selector";

@function has-pseudo($compound, $pseudo) {
  @each $simple in selector.simple-selectors($compound) {
    @if $simple == $pseudo {
      @return true;
    }
  }
  @return false;
}

.check {
  --hover: #{has-pseudo("a.link:hover", ":hover")};
  --focus: #{has-pseudo("a.link:hover", ":focus")};
}

.check {
  --hover: true;
  --focus: false;
}

🚀 Real-World Use Cases

• Validation — require a type selector or forbid certain pseudos.
• Design-system APIs — accept a compound string and branch on its parts.
• Debugging — print each simple piece with meta.inspect.
• Rebuild helpers — drop or swap one simple selector, then append again.
• Teaching CSS — show beginners what lives inside a compound selector.

⚠️ Common Pitfalls

• Passing descendants — "ul li" has a space; use parse, not simple-selectors.
• Passing selector lists — commas are not allowed in the input.
• Expecting nested lists — you get a flat comma list of strings.
• Confusing with parse — parse handles full selector structure; this helper is compound-only.
• Old compilers without modules — use Dart Sass 1.23+ for @use "sass:selector".

💡 Best Practices