Sass Selector Functions

The sass:selector module lets you inspect and manipulate CSS selectors as data, not just as literal text. This lesson covers its most useful functions and when advanced mixin or library authors reach for them.

What Is the sass:selector Module?

Most everyday Sass work never needs sass:selector, plain nesting and & cover nearly all use cases. But when writing advanced, reusable mixins (especially ones meant for a shared component library), these functions let you inspect and combine selectors programmatically instead of relying only on string interpolation.

@use 'sass:selector';

.btn {
  @if selector.is-superselector('.btn', '&') {
    // true: & is at least as specific as .btn here
  }
}

This is an advanced example; most projects will use sass:selector rarely, if ever, compared to everyday nesting and &.

Common sass:selector Functions

@use 'sass:selector';

selector.nest($a, $b);
selector.append($a, $b);
selector.unify($a, $b);
selector.parse($selector);

selector.nest() combines selectors the way normal Sass nesting would.
selector.append() combines selectors the way & suffixing would (no space).
selector.unify() merges two selectors that must both match the same element, returning null if impossible.
selector.parse() converts a selector string into a structured list Sass can inspect programmatically.

sass:selector Cheatsheet

The functions available in the sass:selector module.

Function	Purpose
`selector.nest()`	Combine selectors like nested rules would
`selector.append()`	Combine selectors like `&` suffixing would
`selector.extend()`	Simulate the effect of @extend programmatically
`selector.replace()`	Replace part of a selector with another
`selector.unify()`	Merge two selectors that must both match
`selector.is-superselector()`	Check whether one selector matches every element the other does
`selector.simple-selectors()`	Split a compound selector into its simple parts
`selector.parse()`	Parse a selector string into a structured list

When You Actually Need These Functions

These functions matter most when authoring a reusable Sass library or advanced mixin that needs to generate or validate selectors dynamically, rather than for typical application-level styling, where nesting and & are almost always sufficient.

Building a mixin that must safely combine a caller-provided selector with an internal one.
Writing tooling or lint rules that need to analyze selector structure.
Implementing selector-aware logic inside a shared design system's Sass utilities.

Combining Selectors Programmatically

selector.nest() and selector.append() mirror the two ways & behaves depending on whether it's used with a space (descendant nesting) or directly attached (compound suffixing).

@use 'sass:selector';

// Equivalent to writing ".parent .child" via nesting
$nested: selector.nest('.parent', '.child');

// Equivalent to writing "&.active" via & suffixing
$appended: selector.append('.btn', '.active');

Inspecting Selector Relationships

selector.is-superselector() checks whether every element matched by one selector would also be matched by another, useful for validating assumptions inside advanced, defensive mixin code.

@use 'sass:selector';

@debug selector.is-superselector('.btn', '.btn.is-active'); // true

Common Mistakes

Reaching for sass:selector functions in ordinary application styling where plain nesting and & would be far simpler.
Confusing selector.nest() (descendant combination) with selector.append() (compound suffixing); they produce very different selectors.
Forgetting that selector.unify() returns null when two selectors cannot logically match the same element.
Overengineering simple component styles with selector functions meant for library authors and tooling.

Key Takeaways

The sass:selector module treats selectors as structured data you can inspect and combine.
It matters mostly for advanced mixin and Sass library authors, not everyday component styling.
selector.nest() mirrors normal nesting; selector.append() mirrors & suffixing.
selector.is-superselector() and selector.unify() help validate selector relationships programmatically.

Pro Tip

Unless you're building a shared Sass library or authoring tooling, you can safely skip memorizing the sass:selector module in detail, plain nesting and the parent selector & will cover well over 95% of real project needs.