Sass selector.simple-selectors()

Beginner
8 min read
Updated: Nov 2026
5 examples
Dart Sass 1.23+
Sass selector.simple-selectors splitting a compound selector into simple parts
Definition

Definition and Usage

selector.simple-selectors($selector) returns a comma-separated list of the simple selectors inside a compound selector. The simples are unquoted strings. Load with @use "sass:selector".

Official sample idea.

simple-selectors("a.disabled") → a, .disabled; simple-selectors("main.blog:after") → main, .blog, :after.

Compound only.

$selector must be a single compound selector string—no combinators (including spaces) and no commas.

Need commas or spaces?

Use selector.parse() for full selector lists and complex selectors.

Syntax

Syntax

SCSS
@use "sass:selector";

selector.simple-selectors($selector) //=> list

selector.simple-selectors("a.disabled");
// a, .disabled

selector.simple-selectors("main.blog:after");
// main, .blog, :after

// Walk the list:
@each $simple in selector.simple-selectors("a.disabled") { ... }

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

Pattern: pass one compound string → get a comma list of simples → walk with sass:list or @each.

Reference

vs selector.parse

Different jobs for different selector shapes:

HelperInputUse when
simple-selectorsOne compound (a.disabled)Split tags, classes, and pseudos
parseFull lists / complexes (.a .b, .c)Walk commas and spaces
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 Simple-Selectors Samples

Split compounds into tags, classes, and pseudos.

SCSS
@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)};
}

How It Works

  1. inspect shows the comma list.
  2. a.disabled splits into two simples.
  3. main.blog:after splits into three.
  4. Matches the official Sass docs samples.

Example 2 — Read Each Part with list.nth

Pull tag, classes, and a pseudo out of one compound.

SCSS
@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))};
}

How It Works

  1. Order follows the compound left to right.
  2. Type selector comes first.
  3. Classes follow next.
  4. Pseudo is last in this sample.

Example 3 — Loop with @each

Emit one rule per simple selector.

SCSS
@use "sass:selector";

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

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

How It Works

  1. Comma list is directly usable in @each.
  2. First pass: the type selector a.
  3. Second pass: the class .disabled.
  4. Useful for logging or per-part transforms.

Example 4 — Count, Peek, and Rebuild

Inspect ends of the list, then glue the first two parts with append.

SCSS
@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))};
}

How It Works

  1. length counts the simple pieces.
  2. nth(-1) reads the last item.
  3. append glues pieces without a space.
  4. Rebuild keeps compounds compound.

Example 5 — Detect a Pseudo-Class

Scan the simple list for a specific piece.

SCSS
@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")};
}

How It Works

  1. Each simple is an unquoted string.
  2. Equality checks work for guards.
  3. :hover is present → true.
  4. :focus is absent → false.

Edge Cases & Pitfalls

Most simple-selectors bugs are passing spaces or commas.

input

No combinators or commas

"ul li" and "a, button" are invalid inputs—use parse.

list

Return is a comma list

Walk with @each, list.length, or list.nth.

glue

Rebuild with append

Put pieces back together with selector.append.

compile

Compile-time only

Browsers never see the list—only finished CSS.

Toolchain

Sass Support

Prefer the module form with current Dart Sass.

APIStatus
selector.simple-selectors()Dart Sass 1.23+ via @use "sass:selector"
Return typeComma-separated list of unquoted strings
InputOne compound selector (no spaces / commas)
Legacy globalsimple-selectors($selector)

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • Splits one compound into a comma list of simples.
  • No spaces or commas in the input string.
  • vs parse — parse handles full lists and complexes.
  • Prefer @use "sass:selector" (Dart Sass 1.23+).

One line: to split a compound selector into simples, use selector.simple-selectors($selector).

Practice

Compile Notes

Practical checklist:

checklist.txt
1. @use "sass:selector"
2. Pass one compound string (no spaces / commas)
3. Expect a comma list of unquoted simples
4. Walk with @each or sass:list
5. Use parse for full selector lists

Frequently Asked Questions

selector.simple-selectors($selector) returns a comma-separated list of the simple selectors inside a compound selector. Example: simple-selectors("a.disabled") becomes a, .disabled.
$selector must be a single string that contains a compound selector. It may not contain combinators (including spaces) or commas. So "a.disabled" is OK; "ul li" or "a, button" is not.
The returned list is comma-separated, and the simple selectors are unquoted strings. Example: simple-selectors("main.blog:after") becomes main, .blog, :after.
Yes. simple-selectors($selector) is also available as a legacy global name. Prefer selector.simple-selectors after @use "sass:selector".
parse handles full selector lists with commas and spaces (complex selectors). simple-selectors only splits one compound selector into its simple pieces.
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.unify()

Build a selector that matches only elements matched by both inputs.

selector.unify() →

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 selector.replace Function Sass selector.unify Function