Sass selector.parse() Function

What You’ll Learn

selector.parse() belongs to the built-in sass:selector module. It turns a selector string into Sass’s selector value format—a nested list you can inspect, loop, and pass to other selector helpers. This page covers that structure and five compiled examples.

What Is selector.parse()?

Official docs: returns $selector in the selector value format. Whenever sass:selector returns a selector, it is always a comma-separated list (the selector list) that contains space-separated lists (the complex selectors) that contain unquoted strings (the compound selectors).

For example, .main aside:hover, .sidebar p becomes two complex selectors: .main aside:hover and .sidebar p. The first complex selector has two compounds: .main and aside:hover.

• Input may already be a string or another selector value—parse normalizes it.
• Other selector functions often accept strings directly; parse shines for inspection and loops.
• Interpolating the result usually prints a normal CSS selector string again.

📝 Syntax

@use "sass:selector";

// Recommended
selector.parse($selector)

// Legacy global name
selector-parse($selector)

Parameters

Return value

📦 Loading sass:selector

// Recommended — namespaced (Dart Sass 1.23+)
@use "sass:selector";
$parsed: selector.parse(".main aside:hover, .sidebar p");

// Optional — bring members into scope
@use "sass:selector" as *;
$parsed: parse(".card .title");

// Legacy global
$parsed: selector-parse(".card .title");

🎨 Official Pattern & Structure

@use "sass:selector";

// Conceptual shape from the docs:
// ((unquote(".main") unquote("aside:hover")),
//  (unquote(".sidebar") unquote("p")))
$parsed: selector.parse(".main aside:hover, .sidebar p");

⚖️ When Do You Need parse?

🛠 Compatibility

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

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

Examples Gallery

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

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

$parsed: selector.parse(".main aside:hover, .sidebar p");

.probe {
  --inspect: #{meta.inspect($parsed)};
  --type: #{meta.type-of($parsed)};
}

.probe {
  --inspect: .main aside:hover, .sidebar p;
  --type: list;
}

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

$parsed: selector.parse(".main aside:hover, .sidebar p");
$first: list.nth($parsed, 1);

.probe {
  --complex-count: #{list.length($parsed)};
  --compounds-in-first: #{list.length($first)};
  --compound-1: #{meta.inspect(list.nth($first, 1))};
  --compound-2: #{meta.inspect(list.nth($first, 2))};
}

.probe {
  --complex-count: 2;
  --compounds-in-first: 2;
  --compound-1: .main;
  --compound-2: aside:hover;
}

@use "sass:selector";

$parsed: selector.parse(".card .title");

#{selector.nest($parsed, "&:hover")} {
  color: teal;
}

.card .title:hover {
  color: teal;
}

@use "sass:selector";

.compare {
  --from-string: #{selector.append(".btn", ".primary")};
  --from-parsed: #{selector.append(selector.parse(".btn"), ".primary")};
}

.compare {
  --from-string: .btn.primary;
  --from-parsed: .btn.primary;
}

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

@mixin dump-complex($selector) {
  $parsed: selector.parse($selector);
  @each $complex in $parsed {
    .dump {
      content: meta.inspect($complex);
    }
  }
}

@include dump-complex(".hero h1, .hero p");

.dump {
  content: .hero h1;
}

.dump {
  content: .hero p;
}

🚀 Real-World Use Cases

• Mixin APIs — accept a selector string, parse once, then branch on structure.
• Validation — count complex selectors or compounds before generating CSS.
• Codegen loops — @each over complexes to emit per-branch rules.
• Debugging — pair with meta.inspect / meta.type-of.
• Pipeline helpers — normalize input before nest, append, or extend.

⚠️ Common Pitfalls

• Expecting a plain string type — meta.type-of reports list.
• Parsing only to call nest/append — those helpers already accept strings.
• Confusing commas and spaces — commas split complexes; spaces split compounds.
• Printing structure with inspect — inspect often looks like CSS text; use list.nth to see parts.
• Old compilers without modules — use Dart Sass 1.23+ for @use "sass:selector".

💡 Best Practices