Sass color.blackness()

Definition and Usage

color.blackness($color) returns the HWB blackness of a legacy color as a percentage between 0% and 100% (Dart Sass 1.28+). Global alias: blackness($color).

In the HWB (Hue–Whiteness–Blackness) model, blackness is how much black is mixed into the pure hue. Official docs mark the helper deprecated — prefer color.channel($color, "blackness") on Dart Sass 1.79+.

Syntax

@use "sass:color";

// Deprecated reader (Dart Sass 1.28+)
color.blackness(#e1d7d2); // 11.7647058824%
color.blackness(white);   // 0%
color.blackness(black);   // 100%

// Prefer today (Dart Sass 1.79+)
color.channel(#e1d7d2, "blackness");
color.channel($c, "blackness", $space: hwb);

Pattern: recognize color.blackness in old files → rewrite with color.channel($c, "blackness").

Migrate to color.channel

Side-by-side mapping:

To change blackness, use writers like color.adjust / color.change with $blackness — not the reader.

Related Functions

Prefer color.channel(). Pair with color.whiteness(). Convert spaces with color.to-space(). Shift channels with color.adjust(). Load via @use "sass:color".

SCSS Examples

Examples use color.blackness() on Dart Sass 1.28+. Open View Compiled CSS for verified output (matches official Sass docs samples where noted).

@use "sass:color";

@debug color.blackness(#e1d7d2); // 11.7647058824%

.swatch {
  --blackness: #{color.blackness(#e1d7d2)};
}

.swatch {
  --blackness: 11.7647058824%;
}

@use "sass:color";

@debug color.blackness(white); // 0%
@debug color.blackness(black); // 100%

.extremes {
  --white: #{color.blackness(white)};
  --black: #{color.blackness(black)};
}

.extremes {
  --white: 0%;
  --black: 100%;
}

@use "sass:color";

$brand: #336699;

.brand {
  --blackness: #{color.blackness($brand)};
}

.brand {
  --blackness: 40%;
}

@use "sass:color";

$tone: #e1d7d2;

.hwb-report {
  --whiteness: #{color.whiteness($tone)};
  --blackness: #{color.blackness($tone)};
  --sum: #{color.whiteness($tone) + color.blackness($tone)};
}

.hwb-report {
  --whiteness: 82.3529411765%;
  --blackness: 11.7647058824%;
  --sum: 94.1176470588%;
}

@use "sass:color";

$grey: #6b717f;

.report {
  --blackness: #{color.blackness($grey)};
  --ink: #{if(color.blackness($grey) >= 50%, "inky", "open")};
}

.report {
  --blackness: 50.1960784314%;
  --ink: inky;
}

Sass Support

color.blackness() is a Dart Sass reader. Prefer color.channel when your toolchain allows.

Compile with the Dart Sass CLI.

Key Takeaways

Migrate Notes

Practical checklist:

1. Find color.blackness($c) in legacy SCSS
2. Confirm Dart Sass 1.28+ (reader) or 1.79+ (channel)
3. Replace with color.channel($c, "blackness")
4. Add $space: hwb when reading non-legacy colors
5. Use adjust/change when you need to write blackness