Just as some aspects ofSass’s color functions are being deprecated with theaddition of support forCSS Color 4, some corners of theJSAPI formanipulating colors are deprecated as well.

color.change() now requires aspace for cross-space changescolor.change() now requires a space for cross-space changes permalink

Previously, thecolor.change() method just took a set of channel names fromtheRGB,HSL, orHWB spaces. As long as those channels weren’t mixed acrossspaces (for example by changing bothred andhue at the same time), Sasscould figure out which space was intended.

With Color 4, color spaces are no longer unambiguous from their channel namesalone. Many spaces havered,green, andblue channels with differentranges; many spaces havehue channels which produce very different colorwheels. To fix this ambiguity,color.change() now takes aspace parameterwhich explicitly specifies the name of the color space you want to do thetransformation in:

const color=newsass.SassColor({red:0x66,green:0x33,blue:0x99});color.change({hue:270,space:"okclh"});

Specifying the color space is mandatory if the color in question isn’t in alegacy color space or if you’re changing a channel like chroma that onlyexists in non-legacy color spaces. It’s always optional if you’re changing achannel that exists in the color’s own space, socolor.change({red: 0.8})always refers to the native red channel of any color withred,green, andblue channels.

For backwards-compatibility, if you’re changing legacy channels for a legacycolor, Sass will still automatically convert the color for you. However, thisbehavior is deprecated. To be safe, you shouldalways pass thespaceparameter unless you’re sure the color is already in the color space whosechannel you want to change.

null channel valuesnull channel values permalink

One of the major changes inCSS Color 4 is the new concept of"missing"channels. For example,hsl(none 0% 40%) has a missing hue, which is treatedas 0 in most cases but doesn’t contribute to color interpolation so that agradient with this color won’t have a phantom red hue in the middle. Whenconstructing colors, Sass represents missing values as the valuenull.

Before adding support forCSS Color 4, the SassJSAPI’s TypeScript typesforbade the use ofnull in all places where it was relevant. However, the codeitself treatednull the same asundefined, and we don’t want to breakcompatibility with any plain JavaScript code that was relying on this behavior.For now, anull value is treated asundefined and emits a deprecationwarning when constructing a newlegacy color or callingcolor.change() for alegacy color. In either case, if you pass aspace parameter explicitly, you’llopt into the new behavior andnull will be treated as a missing channel.

Transition PeriodTransition Period permalink

Compatibility:

Dart Sass

since 1.79.0

LibSass

✗

Ruby Sass

✗

First, we’ll emit deprecation warnings for all uses of these APIs that areslated to be changed. In Dart Sass 2.0.0, the breaking changes will go intoeffect fully, and the old behavior will no longer work how it used to.

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

Sass provides a powerful suite of options for managing which deprecationwarnings 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 ofdeprecation warning five times before it silences additional warnings. Thishelps ensure that users know when they need to be aware of an upcoming breakingchange without creating an overwhelming amount of console noise.

If you run Sass in verbose mode instead, it will printevery deprecationwarning it encounters. This can be useful for tracking the remaining work to bedone when fixing deprecations. You can enable verbose mode usingtheverbose option in the JavaScript API.

Silencing Deprecations in DependenciesSilencing Deprecations in Dependencies permalink

Sometimes, your dependencies have deprecation warnings that you can’t doanything about. You can silence deprecation warnings from dependencies whilestill printing them for your app usingthequietDeps option in the JavaScript API.

For the purposes of this flag, a "dependency" is any stylesheet that’s not justa series of relative loads from the entrypoint stylesheet. This means anythingthat 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 cansilence warnings for that specific deprecation usingthesilenceDeprecations option in the JavaScript API.