Sass color.change() Function

What You’ll Learn

color.change() belongs to the built-in sass:color module. It sets one or more channels to the exact values you pass—make red exactly 100, lightness exactly 30%, opacity exactly 0.4—at compile time. This page covers channel keywords, mixing rules, the no-clamping rule, how it differs from adjust and scale, and five compiled examples.

What Is color.change()?

Change means “take this color and replace one or more channels with new absolute values.” You are not adding 15 to red—you are setting red to 100. Official docs describe it as using each keyword argument in place of the corresponding channel.

• color.change(#6b717f, $red: 100) → #64717f
• color.change(#336699, $lightness: 30%) → #264d73
• color.change(#4caf50, $alpha: 0.4) → rgba(76, 175, 80, 0.4)

📝 Syntax

Load the color module, then call the function with keyword channel arguments:

@use "sass:color";

color.change($color,
  $red: null, $green: null, $blue: null,
  $hue: null, $saturation: null, $lightness: null,
  $whiteness: null, $blackness: null,
  $alpha: null
  // Dart Sass 1.79+: also $space, $chroma, $x, $y, $z, ...
)

Common parameters

Return value

📦 Loading sass:color

Prefer the module API. Official docs also document a global name, change-color(), for older stylesheets.

// Recommended — namespaced
@use "sass:color";
$c: color.change(#6b717f, $red: 100);

// Optional — bring members into the current namespace
@use "sass:color" as *;
$c: change(#6b717f, $red: 100);

// Optional — custom namespace
@use "sass:color" as c;
$c: c.change(#6b717f, $red: 100);

// Legacy global name
$c: change-color(#6b717f, $red: 100);

🎨 Channel Mixing Rules

The same legacy rules as color.adjust() apply: do not mix RGB keywords with HSL keywords in the same call, or mix those with HWB keywords. Pick one family per call.

⚠️ No Clamping on change

Official docs call this out clearly: channels are never clamped for color.change(). That differs from color.adjust(), where several channels clamp if they leave their native range.

🛠 Compatibility

This is about Sass compilers, not browsers. Compiled CSS receives a finished color—no color.change() 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.change(#6b717f, $red: 100); // #64717f

.swatch {
  background: color.change(#6b717f, $red: 100);
}

.swatch {
  background: #64717f;
}

@use "sass:color";

$brand: #336699;

.surface {
  color: color.change($brand, $lightness: 30%);     // #264d73
  background: color.change($brand, $saturation: 40%); // #3d668f
}

.surface {
  color: #264d73;
  background: #3d668f;
}

@use "sass:color";

.overlay {
  color: color.change(#4caf50, $alpha: 0.4);
  outline-color: color.change(#c65353, $hue: 200deg);
}

.overlay {
  color: rgba(76, 175, 80, 0.4);
  outline-color: #53a0c6;
}

@use "sass:color";

$brand: #336699;

.card {
  background: color.change($brand, $lightness: 92%);
  border-color: color.change($brand, $lightness: 40%);
  color: color.change($brand, $lightness: 20%);
}

.card {
  background: #e0ebf5;
  border-color: #336699;
  color: #1a334d;
}

@use "sass:color";

.names {
  --module: #{color.change(#6b717f, $red: 100)};
  --global: #{change-color(#6b717f, $red: 100)};
}

.names {
  --module: #64717f;
  --global: #64717f;
}

🚀 Real-World Use Cases

• Design-token ladders — set known lightness steps for surface / text / border.
• Exact overlays — force alpha to 0.2, 0.4, or 0.8 for scrims and chips.
• Accent snaps — set hue to a fixed angle for info, success, or warning accents.
• Saturation resets — dial saturation to a brand percentage without math on the current value.
• Component themes — keep one brand hex and derive every role with absolute channels.
• Migration clarity — replace hand-picked hex tables with explicit change calls.

⚠️ Common Pitfalls

• Treating change like adjust — $red: 15 sets red to 15, it does not add 15.
• Mixing RGB and HSL keywords — causes a compile error; use one family per call.
• Assuming clamping — unlike adjust, change never clamps channel values.
• Using $space on older Dart Sass — needs 1.79+; HSL change on hex still works without it.
• Expecting relative darkening — for “20% of the way darker,” use color.scale().

💡 Best Practices