Sass color.adjust() Function

What You’ll Learn

color.adjust() belongs to the built-in sass:color module. It nudges a color by fixed channel amounts—more red, less lightness, a bit more transparency—at compile time. This page covers channel keywords, mixing rules, how it replaces old lighten/darken calls, how it differs from scale and change, and five compiled examples.

What Is color.adjust()?

Adjust means “take this color and add or subtract from one or more channels.” Positive values push a channel up; negative values pull it down. Official docs describe it as increasing or decreasing channels by fixed amounts.

• color.adjust(#6b717f, $red: 15) → #7a717f
• color.adjust(#336699, $lightness: 10%) → #4080bf
• color.adjust(#336699, $alpha: -0.2) → rgba(51, 102, 153, 0.8)

📝 Syntax

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

@use "sass:color";

color.adjust($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, adjust-color(), for older stylesheets.

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

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

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

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

🎨 Channel Mixing Rules

Official docs warn that for legacy colors you must not mix RGB keywords with HSL keywords in the same call, or mix those with HWB keywords. Pick one family per call.

🛠 Compatibility

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

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

.swatch {
  background: #7a717f;
}

@use "sass:color";

$brand: #336699;

.light {
  color: color.adjust($brand, $lightness: 10%);  // #4080bf
}

.dark {
  color: color.adjust($brand, $lightness: -10%); // #264d73
}

.light {
  color: #4080bf;
}

.dark {
  color: #264d73;
}

@use "sass:color";

$brand: #336699;

.panel {
  background: color.adjust($brand, $alpha: -0.2); // rgba(..., 0.8)
  border-color: color.adjust($brand, $alpha: -0.3);
}

.panel {
  background: rgba(51, 102, 153, 0.8);
  border-color: rgba(51, 102, 153, 0.7);
}

@use "sass:color";

$brand: #4caf50;

.chip {
  background: color.adjust($brand, $lightness: -12%);
  color: #fff;
  box-shadow: 0 0 0 4px color.adjust($brand, $alpha: -0.7);
}

.chip:hover {
  background: color.adjust($brand, $lightness: -18%);
  outline-color: color.adjust(#c65353, $hue: -20deg);
}

.chip {
  background: #39843c;
  color: #fff;
  box-shadow: 0 0 0 4px rgba(76, 175, 80, 0.3);
}

.chip:hover {
  background: #306f33;
  outline-color: #c65379;
}

@use "sass:color";

.names {
  --module: #{color.adjust(#6b717f, $red: 15)};
  --global: #{adjust-color(#6b717f, $red: 15)};
  --muted: #{color.adjust(#c65353, $saturation: -20%)};
}

.names {
  --module: #7a717f;
  --global: #7a717f;
  --muted: #af6a6a;
}

🚀 Real-World Use Cases

• Hover / active states — darken or lighten a brand color by a fixed step.
• Muted variants — reduce saturation for secondary text or chips.
• Overlays — drop alpha for scrims, focus rings, and shadows.
• Hue families — rotate hue to invent related accents from one token.
• Migrating legacy SCSS — replace lighten/darken with module calls.
• Design systems — generate tints and shades without maintaining a huge hex table.

⚠️ Common Pitfalls

• Mixing RGB and HSL keywords — causes a compile error; use one family per call.
• Expecting relative scaling — adjust is fixed amounts; use color.scale() for proportional moves.
• Using $space on older Dart Sass — needs 1.79+; HSL adjust on hex still works without it.
• Assuming no clamping — several channels clamp when pushed out of range (RGB, lightness in lab/oklab, alpha, …).
• Staying on lighten/darken — prefer color.adjust in new module-based SCSS.

💡 Best Practices