Sass color.complement()

Beginner
11 min read
Updated: Nov 2026
5 examples
Compiled CSS
Sass color.complement rotating hue 180 degrees for complementary colors
Definition

Definition and Usage

color.complement() returns the complement of a color by rotating its hue 180deg in a polar color space. Load it with @use "sass:color". The global alias is complement().

$space must be polar: hsl, hwb, lch, or oklch (Dart Sass 1.79+). The result always stays in the original color’s space. For legacy hex/RGB colors without $space, Sass defaults to hsl — still pass $space explicitly when you can.

Official idea.

color.complement(#6b717f) → #7f796b (HSL hue 222deg → 42deg). In oklch the same hex lands on a different RGB result.

Round-trip.

Complement twice in the same space and you return to the starting hue: color.complement(color.complement($c)).

Polar spaces only.

$space cannot be rgb or lab. Those have no hue dial to flip.

Syntax

Syntax

SCSS
@use "sass:color";

// Legacy hex — defaults to hsl
color.complement(#6b717f); // #7f796b

// Explicit space (Dart Sass 1.79+)
color.complement($c, $space: hsl);
color.complement($c, $space: oklch);

// Already polar
color.complement(oklch(50% 0.12 70deg), $space: oklch);
// → oklch(50% 0.12 250deg)

Pattern: @use "sass:color" → pick a brand color → call color.complement → use the opposite hue as an accent.

Reference

vs adjust / invert

Related ways to invent a contrasting color:

FunctionWhat it doesUse when
color.complement()Hue +180deg in a polar spaceTrue complementary accent
color.adjust(..., $hue: 180deg)Manual hue nudgeSame idea, more verbose
color.invert()Inverts RGB channelsPhotographic / high-contrast invert
color.mix()Blends two colorsYou already know both endpoints
Code

SCSS Examples

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

Example 1 — Official Hex Complement

Rotate a muted blue-gray halfway around the HSL wheel.

SCSS
@use "sass:color";

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

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

How It Works

  1. Hex is legacy, so Sass defaults to HSL.
  2. Hue advances 180deg (222deg → 42deg).
  3. Other HSL channels stay related.
  4. Result matches the official sample #7f796b.

Example 2 — Accent Colors from Brand Hexes

Generate opposite accents for blue, green, and red tokens.

SCSS
@use "sass:color";

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

How It Works

  1. Intensity stays related; only hue flips.
  2. Blue becomes a warm brown-orange.
  3. Green becomes magenta; red becomes cyan.
  4. Classic complements for charts, tags, and outlines.

Example 3 — Brand + Complement Pair

Fill with the brand; contrast with its complement; prove the round-trip.

SCSS
@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));
}

How It Works

  1. One brand token drives fill and accent.
  2. Complement provides the opposite text color.
  3. Double complement restores the original opaque hex.
  4. Useful teaching pattern for hue rotation.

Example 4 — Complement in oklch (Dart Sass 1.79+)

Official docs: rotating in oklch yields a different RGB than HSL.

SCSS
@use "sass:color";

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

@debug color.complement(#6b717f, $space: oklch);
// rgb(118.8110604298, 112.5123650034, 98.1616586336)

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

.modern {
  color: color.complement(#6b717f, $space: oklch);
}

How It Works

  1. Same hex, different polar ruler.
  2. HSL and oklch both flip hue 180deg.
  3. RGB results differ — pick the space your system prefers.
  4. Needs Dart Sass 1.79+ for $space.

Example 5 — Module vs Global complement()

Both names perform the same HSL default complement on legacy colors.

SCSS
@use "sass:color";

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

How It Works

  1. Module and global HSL complements match.
  2. Prefer color.complement() so the module is obvious.
  3. Interpolation writes the colors into custom properties.
  4. Same result as Example 1’s official sample.

Edge Cases & Pitfalls

Most color.complement bugs are the wrong space, an old Dart Sass, or confusing invert with complement.

space

Only polar spaces

$space must be hsl, hwb, lch, or oklch — not rgb.

version

$space needs 1.79+

Bare color.complement($hex) works earlier; named $space needs Dart Sass 1.79+.

invert

Not the same as invert

invert flips RGB channels. complement only rotates hue.

grays

Near-gray colors barely shift

Low saturation means a 180deg flip looks almost the same. Check chroma before relying on the accent.

Toolchain

Sass Support

Module form needs Dart Sass. Prefer it for all new complement work.

FeatureStatus
@use "sass:color" / color.complementDart Sass 1.23+
$space argumentDart Sass 1.79+
Global complement()Older compilers / legacy SCSS
LibSass / Ruby SassNo modern module API

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • Hue +180deg in a polar space — that is the whole idea.
  • Load @use "sass:color" and prefer the module name.
  • Pass $space explicitly on Dart Sass 1.79+.
  • Twice restores the original hue in the same space.

One line: color.complement is the clearest way to ask Sass for the opposite hue.

Compile

Compile Notes

Conceptual flow:

flow.txt
1. @use "sass:color"
2. Resolve $color (and optional polar $space)
3. Rotate hue by 180deg
4. Return a new color in the original space
5. Emit a finished CSS color — no complement() left

Frequently Asked Questions

color.complement($color, $space: null) rotates the color’s hue by 180deg in a polar color space and returns the complementary color. Example: color.complement(#6b717f) is #7f796b.
Add @use "sass:color"; then call color.complement($brand). Prefer the module form in new SCSS. The global alias is complement().
Official docs require a polar space: hsl, hwb, lch, or oklch. The $space argument needs Dart Sass 1.79+. For legacy hex/RGB colors without $space, Sass defaults to hsl.
Yes for the same space. Rotating hue by 180deg twice returns you to the starting hue, so color.complement(color.complement($c)) matches $c for typical opaque colors.
complement is a convenience for a full opposite hue. You can also write color.adjust($c, $hue: 180deg) in HSL for a similar idea, but complement is clearer when you want the opposite color.
The module form needs Dart Sass with @use (about 1.23+). The $space parameter needs Dart Sass 1.79+. LibSass/Ruby Sass may expose a global complement() but lack the modern module API.

Next: Sass color.grayscale()

Turn a color into a gray by removing its saturation.

color.grayscale() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

8 people found this page helpful

Sass color.channel Function Sass color.grayscale Function