Breaking Change: Plain-CSS if()

Sass’s legacy if() function is being deprecated in favor of the official CSS if() function syntax. This syntax allows Sass and CSS conditions to be mixed freely.

Compatibility:
Dart Sass
since 1.95.0
LibSass
✗
Ruby Sass
✗

In 2010, shortly after adding the boolean value type, Sass added the global if() function as a way to easily use booleans in a single expression without having to write out an entire @if rule. This function had the signature if($condition, $if-true, $if-false) and returned $if-true if $condition was truthy and $if-false otherwise.

At the time, browsers didn’t even support @media queries and we never imagined that CSS might support its own if() function someday. But fifteen years later, support for the CSS if() function began landing in browsers and we had to do so as well in order to remain fully CSS-compatible.

Sass now supports the plain-CSS if() syntax, as well as a special sass(...) condition that evaluates Sass expressions. In order to avoid redundancy and standardize on the most CSS-compatible option, we plan to eventually remove the legacy if() function from the language.

You can use the Sass migrator to automatically migrate from the legacy if() function to the CSS if() syntax.

Playground

SCSS Syntax

@use 'sass:meta';

// Instead of if(true, 10px, 15px)
@debug if(sass(true): 10px; else: 15px);

// Instead of if(meta.variable-defined($var), $var, null)
@debug if(sass(meta.variable-defined($var)): $var);
Playground

Sass Syntax

@use 'sass:meta'

// Instead of if(true, 10px, 15px)
@debug if(sass(true): 10px; else: 15px)

// Instead of if(meta.variable-defined($var), $var, null)
@debug if(sass(meta.variable-defined($var)): $var)

Can I Silence the Warnings?Can I Silence the Warnings? permalink

Sass provides a powerful suite of options for managing which deprecation warnings you see and when.

Terse and Verbose ModeTerse and Verbose Mode permalink

By default, Sass runs in terse mode, where it will only print each type of deprecation warning five times before it silences additional warnings. This helps ensure that users know when they need to be aware of an upcoming breaking change without creating an overwhelming amount of console noise.

If you run Sass in verbose mode instead, it will print every deprecation warning it encounters. This can be useful for tracking the remaining work to be done when fixing deprecations. You can enable verbose mode using the --verbose flag on the command line, or the verbose option in the JavaScript API.

⚠️ Heads up!

When running from the JS API, Sass doesn’t share any information across compilations, so by default it’ll print five warnings for each stylesheet that’s compiled. However, you can fix this by writing (or asking the author of your favorite framework’s Sass plugin to write) a custom Logger that only prints five errors per deprecation and can be shared across multiple compilations.

Silencing Deprecations in DependenciesSilencing Deprecations in Dependencies permalink

Sometimes, your dependencies have deprecation warnings that you can’t do anything about. You can silence deprecation warnings from dependencies while still printing them for your app using the --quiet-deps flag on the command line, or the quietDeps option in the JavaScript API.

For the purposes of this flag, a "dependency" is any stylesheet that’s not just a series of relative loads from the entrypoint stylesheet. This means anything that comes from a load path, and most stylesheets loaded through custom importers.

Silencing Specific DeprecationsSilencing Specific Deprecations permalink

If you know that one particular deprecation isn’t a problem for you, you can silence warnings for that specific deprecation using the --silence-deprecation flag on the command line, or the silenceDeprecations option in the JavaScript API.