Sass color.whiteness() Function

What You’ll Learn

color.whiteness() belongs to the built-in sass:color module (Deprecated Functions). It returns a legacy color’s HWB whiteness as a percentage from 0% to 100% at compile time. This page covers the HWB idea, the legacy-color rule, Dart Sass 1.28+ support, migration to color.channel(), and five compiled examples.

What Is color.whiteness()?

Whiteness is the “how much white paint?” channel in the HWB (Hue–Whiteness–Blackness) model. Official docs: color.whiteness() returns that channel as a number between 0% and 100%. Pure black has 0% whiteness; pure white has 100%.

• color.whiteness(#e1d7d2) → 82.3529411765%
• color.whiteness(white) → 100%
• color.whiteness(black) → 0%

📝 Syntax

Load the color module, then pass a legacy color:

@use "sass:color";

// Deprecated — Dart Sass 1.28+
color.whiteness($color)

// Optional — bring members into scope
@use "sass:color" as *;
whiteness($color)

// Recommended migration (Dart Sass 1.79+)
color.channel($color, "whiteness")

Parameters

Return value

📦 Loading sass:color & Migrating

Prefer the namespaced form. Bare whiteness() only works after @use "sass:color" as *;—otherwise CSS may keep the call as a plain string.

@use "sass:color";

// Old (deprecated, Dart Sass 1.28+)
$w: color.whiteness(#e1d7d2); // 82.3529411765%

// New — preferred on Dart Sass 1.79+
$w: color.channel(#e1d7d2, "whiteness");

// Optional global-style import
@use "sass:color" as *;
$w: whiteness(#e1d7d2);

🎨 HWB: Whiteness + Blackness

HWB describes a color as a hue mixed with white and black. For many everyday hex colors, whiteness and blackness percentages add up to less than 100%—the rest is the pure hue.

• Whiteness high → lighter, chalkier look
• Whiteness 0% → no white mix (black is the extreme opposite case)
• Whiteness 100% → pure white

📋 color.whiteness vs color.channel

🔍 Whiteness vs HSL Lightness

Beginners often mix up HWB whiteness with HSL lightness. They are related ideas, but different models:

🛠 Compatibility

This is about Sass compilers, not browsers. Compiled CSS receives a finished percentage—no color.whiteness() call remains at runtime.

Examples Gallery

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

@use "sass:color";

@debug color.whiteness(#e1d7d2); // 82.3529411765%

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

.swatch {
  --whiteness: 82.3529411765%;
}

@use "sass:color";

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

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

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

@use "sass:color";

$brand: #336699;

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

.brand {
  --whiteness: 20%;
}

@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";

$tone: #e1d7d2;

.report {
  --whiteness: #{color.whiteness($tone)};
  --look: #{if(color.whiteness($tone) >= 50%, "pale", "deep")};
}

.report {
  --whiteness: 82.3529411765%;
  --look: pale;
}

🚀 Real-World Use Cases

• Reading legacy SCSS — recognize color.whiteness in older HWB workflows.
• Safe migrations — replace with color.channel($c, "whiteness") on Dart Sass 1.79+.
• Token audits — flag colors that sit too far toward chalky white.
• HWB teaching — pair with blackness to explain the model.
• Conditional mixins — pick dark text when whiteness is high.

⚠️ Common Pitfalls

• Using it in new code — prefer color.channel($c, "whiteness").
• Bare whiteness() without as * — may compile as a CSS function string.
• Modern color spaces — $color must be legacy for color.whiteness.
• Confusing with HSL lightness — different models; use the matching channel reader.
• Expecting a color back — this helper reads a percentage; use adjust/change to write.

💡 Best Practices