Sass color.grayscale() Function

What You’ll Learn

color.grayscale() belongs to the built-in sass:color module. It turns a color into gray while keeping the same lightness—at compile time. This page covers legacy HSL desaturation vs Oklch chroma removal, how it differs from CSS filter: grayscale(), related helpers, and five compiled examples.

What Is color.grayscale()?

Grayscale means “keep this color’s lightness, remove its chroma / saturation.” Official docs say it returns a gray with the same lightness as $color. You still get a real CSS color value—just without hue punch.

• color.grayscale(#6b717f) → #757575
• color.grayscale(#336699) → #666666
• color.grayscale(#4caf50) → #7e7e7e

📝 Syntax

Load the color module, then pass one color:

@use "sass:color";

color.grayscale($color)
// Global alias:
// grayscale($color)

Parameters

Return value

📦 Loading sass:color

Prefer the module API. Official docs also document the global name grayscale() for older stylesheets.

// Recommended — namespaced
@use "sass:color";
$muted: color.grayscale(#6b717f);

// Optional — bring members into the current namespace
@use "sass:color" as *;
$muted: grayscale(#6b717f);

// Optional — custom namespace
@use "sass:color" as c;
$muted: c.grayscale(#6b717f);

// Legacy global name
$muted: grayscale(#6b717f);

🎨 How Sass Removes Color

Official docs split behavior by whether the color is in a legacy space:

@use "sass:color";

@debug color.grayscale(#6b717f); // #757575

// Modern spaces (needs a Dart Sass build that understands them)
@debug color.grayscale(oklch(50% 80% 270deg)); // oklch(50% 0% 270deg)

📋 Sass grayscale() vs CSS filter: grayscale()

Same English word, different jobs. Mixing them up is a common beginner mistake.

🛠 Compatibility

This is about Sass compilers, not browsers. Compiled CSS receives a finished gray color—no color.grayscale() call remains.

Examples Gallery

Each example uses @use "sass:color". Open View Compiled CSS to see what Dart Sass emits.

@use "sass:color";

@debug color.grayscale(#6b717f); // #757575

.swatch {
  background: color.grayscale(#6b717f);
}

.swatch {
  background: #757575;
}

@use "sass:color";

.muted {
  color: color.grayscale(#336699);         // #666666
  background: color.grayscale(#4caf50);    // #7e7e7e
  outline-color: color.grayscale(#c65353); // #8d8d8d
}

.muted {
  color: #666666;
  background: #7e7e7e;
  outline-color: #8d8d8d;
}

@use "sass:color";

$brand: #336699;
$brand-muted: color.grayscale($brand);

.button {
  background: $brand;
  color: #fff;
}

.button:disabled {
  background: $brand-muted; // #666666
  color: #fff;
  border-color: color.grayscale(#2196f3); // #8a8a8a
}

.button {
  background: #336699;
  color: #fff;
}

.button:disabled {
  background: #666666;
  color: #fff;
  border-color: #8a8a8a;
}

@use "sass:color";

.chip {
  // Sass: compile-time gray color value
  color: color.grayscale(#336699);
}

.photo.is-muted {
  // CSS: runtime filter on the element (not a Sass color helper)
  filter: grayscale(1);
}

.chip {
  color: #666666;
}

.photo.is-muted {
  filter: grayscale(1);
}

@use "sass:color";

.names {
  --module: #{color.grayscale(#6b717f)};
  --global: #{grayscale(#6b717f)};
}

.names {
  --module: #757575;
  --global: #757575;
}

🚀 Real-World Use Cases

• Disabled buttons — mute brand fills without inventing new hexes.
• Secondary text / icons — derive neutral tones from brand colors.
• Skeleton / empty states — gray placeholders that match brand lightness.
• Print / mono themes — build a grayscale ladder from your palette.
• Data viz neutrals — gray unused series while keeping relative brightness.
• Design tokens — store $brand and $brand-muted together.

⚠️ Common Pitfalls

• Confusing CSS filter — filter: grayscale() does not produce a Sass color token.
• Expecting identical RGB for every space — legacy HSL path and Oklch chroma path can differ for modern colors.
• Assuming contrast is fine — gray text on gray backgrounds can fail accessibility checks.
• Using the bare global near filters — prefer color.grayscale() for clarity.
• Already-gray inputs — nearly neutral colors barely change (saturation was already low).

💡 Best Practices