Sass color.complement() Function

What You’ll Learn

color.complement() belongs to the built-in sass:color module. It builds a complementary color by rotating hue 180deg in a polar color space—at compile time. This page covers the default HSL behavior for hex/RGB, optional $space (Dart Sass 1.79+), how it differs from adjust / change, and five compiled examples.

What Is color.complement()?

Complement means “spin this color halfway around the hue wheel.” Official docs describe it as rotating $color’s hue by 180deg in a polar space. Saturation and lightness stay related to the original—you get a strong opposite accent, not a random new palette color.

• color.complement(#6b717f) → #7f796b (HSL hue 222deg → 42deg)
• color.complement(#336699) → #996633
• color.complement(#c65353) → #53c6c6

📝 Syntax

Load the color module, then pass a color and an optional polar space:

@use "sass:color";

color.complement($color, $space: null)
// Global alias:
// complement($color, $space: null)

Parameters

Return value

📦 Loading sass:color

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

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

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

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

// Legacy global name
$accent: complement(#6b717f);

🎨 Polar Spaces Only

Official docs require a polar color space for the rotation. RGB is not a valid $space here—you need a space that has a hue angle.

🛠 Compatibility

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

Examples Gallery

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

@use "sass:color";

// HSL hue 222deg becomes 42deg.
@debug color.complement(#6b717f); // #7f796b

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

.swatch {
  background: #7f796b;
}

@use "sass:color";

.accents {
  color: color.complement(#336699);        // #996633
  background: color.complement(#4caf50);   // #af4cab
  outline-color: color.complement(#c65353); // #53c6c6
}

.accents {
  color: #996633;
  background: #af4cab;
  outline-color: #53c6c6;
}

@use "sass:color";

$brand: #336699;

.card {
  background: $brand;
  color: color.complement($brand);
  // 180deg twice → back to the brand hue
  border-color: color.complement(color.complement($brand));
}

.card {
  background: #336699;
  color: #996633;
  border-color: #336699;
}

@use "sass:color";

// Default HSL complement
@debug color.complement(#6b717f); // #7f796b

// Oklch hue ~267deg becomes ~87deg (Dart Sass 1.79+)
@debug color.complement(#6b717f, $space: oklch);
// rgb(118.8110604298, 112.5123650034, 98.1616586336)

// Polar color already in oklch
@debug color.complement(oklch(50% 0.12 70deg), $space: oklch);
// oklch(50% 0.12 250deg)

.modern {
  // Requires Dart Sass 1.79+
  color: color.complement(#6b717f, $space: oklch);
}

.modern {
  color: rgb(118.8110604298, 112.5123650034, 98.1616586336);
}

@use "sass:color";

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

.names {
  --module: #7f796b;
  --global: #7f796b;
}

🚀 Real-World Use Cases

• Accent pairs — derive a secondary brand color from one hex token.
• Charts & tags — give series or badges opposite hues that still feel related.
• Alert styling — invent a contrasting outline or icon color quickly.
• Design exploration — preview complements before locking a palette.
• Theme kits — store $brand and $brand-complement together.
• Space experiments — compare HSL vs oklch complements on Dart Sass 1.79+.

⚠️ Common Pitfalls

• Expecting RGB $space — only polar spaces (hsl, hwb, lch, oklch) are valid.
• Using $space on older Dart Sass — needs 1.79+; bare color.complement($hex) still works earlier.
• Assuming HSL and oklch match — same hex can yield different complements per space.
• Low-saturation colors — complements stay muted when the original is nearly gray.
• Confusing with invert — complement flips hue; it is not the same as photographic invert.

💡 Best Practices