sass:selector
- Dart Sass
- since 1.23.0
- LibSass
- ✗
- Ruby Sass
- ✗
Selector Values permalinkSelector Values
The functions in this module inspect and manipulate selectors. Whenever they return a selector, it’s 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, the selector .main aside:hover, .sidebar p would be returned as:
@debug ((unquote(".main") unquote("aside:hover")),
(unquote(".sidebar") unquote("p")));
// .main aside:hover, .sidebar p
Selector arguments to these functions may be in the same format, but they can also just be normal strings (quoted or unquoted), or a combination. For example, ".main aside:hover, .sidebar p" is a valid selector argument.
selector.is-superselector($super, $sub)
is-superselector($super, $sub) //=> boolean Returns whether the selector $super matches all the elements that the selector $sub matches.
Still returns true even if $super matches more elements than $sub.
The $super and $sub selectors may contain placeholder selectors, but not parent selectors.
selector.append($selectors...)
selector-append($selectors...) //=> selector Combines $selectors without descendant combinators—that is, without whitespace between them.
If any selector in $selectors is a selector list, each complex selector is combined separately.
The $selectors may contain placeholder selectors, but not parent selectors.
See also selector.nest().
selector.extend($selector, $extendee, $extender)
selector-extend($selector, $extendee, $extender) //=> selector Extends $selector as with the @extend rule.
Returns a copy of $selector modified with the following @extend rule:
#{$extender} {
@extend #{$extendee};
}
In other words, replaces all instances of $extendee in $selector with $extendee, $extender. If $selector doesn’t contain $extendee, returns it as-is.
The $selector, $extendee, and $extender selectors may contain placeholder selectors, but not parent selectors.
See also selector.replace().
selector.nest($selectors...)
selector-nest($selectors...) //=> selector Combines $selectors as though they were nested within one another in the stylesheet.
The $selectors may contain placeholder selectors. Unlike other selector functions, all of them except the first may also contain parent selectors.
See also selector.append().
selector.parse($selector)
selector-parse($selector) //=> selector Returns $selector in the selector value format.
selector.replace($selector, $original, $replacement)
selector-replace($selector, $original, $replacement) //=> selector Returns a copy of $selector with all instances of $original replaced by $replacement.
This uses the @extend rule’s intelligent unification to make sure $replacement is seamlessly integrated into $selector. If $selector doesn’t contain $original, returns it as-is.
The $selector, $original, and $replacement selectors may contain placeholder selectors, but not parent selectors.
See also selector.extend().
selector.unify($selector1, $selector2)
selector-unify($selector1, $selector2) //=> selector | null Returns a selector that matches only elements matched by both $selector1 and $selector2.
Returns null if $selector1 and $selector2 don’t match any of the same elements, or if there’s no selector that can express their overlap.
Like selectors generated by the @extend rule, the returned selector isn’t guaranteed to match all the elements matched by both $selector1 and $selector2 if they’re both complex selectors.
selector.simple-selectors($selector)
simple-selectors($selector) //=> list Returns a list of simple selectors in $selector.
The $selector must be a single string that contains a compound selector. This means it may not contain combinators (including spaces) or commas.
The returned list is comma-separated, and the simple selectors are unquoted strings.