Sass color.to-space() Function

What You’ll Learn

color.to-space() belongs to the built-in sass:color module. It converts a color into another color space. This page covers unquoted $space names, missing channels, how it differs from to-gamut, the Dart Sass 1.79+ requirement, and five examples.

What Is color.to-space()?

To-space means “rewrite this color in another coordinate system.” Official docs: converts $color into the given $space. A hex brand can become oklch, hsl, or display-p3 while usually keeping the same paint. Official fun fact: this is the only Sass color function that returns a color in a different space than the one passed in.

• color.to-space(#036, oklch) → an oklch(...) twin
• color.to-space(#036, display-p3) → color(display-p3 …)
• color.to-space(grey, lch) → lch(… 0 none) (missing hue)

📝 Syntax

Load the color module, then pass a color and an unquoted destination space:

@use "sass:color";

// Dart Sass 1.79+
color.to-space($color, $space)

Parameters

Return value

📦 Loading sass:color

There is no separate global to-space() built-in. Use the module form on Dart Sass 1.79+.

// Recommended — namespaced (Dart Sass 1.79+)
@use "sass:color";
$ok: color.to-space(#036, oklch);

// Optional — bring members into the current namespace
@use "sass:color" as *;
$ok: to-space(#036, oklch);

// Optional — custom namespace
@use "sass:color" as c;
$ok: c.to-space(#036, oklch);

🎨 Missing Channels & Legacy Destinations

Official docs call out two important behaviors:

• Conversion can produce missing channels when the source already has a missing analogous channel, or when a channel is powerless in the destination (for example grey → lch with hue none).
• When $space is a legacy space (rgb / hsl / hwb), Sass never invents a new missing channel—so the result stays compatible with older browsers.

📋 to-space vs to-gamut

These helpers often travel together, but they answer different needs.

🛠 Compatibility

This is about Sass compilers, not browsers. Compiled CSS receives a finished color in the destination space—no color.to-space() call remains.

Examples Gallery

Examples target Dart Sass 1.79+. Open View Compiled CSS to see converted colors (verified against modern Dart Sass; official docs samples noted).

@use "sass:color";

$brand: #036;

.tokens {
  --oklch: #{color.to-space($brand, oklch)};
  --hsl: #{color.to-space($brand, hsl)};
  --p3: #{color.to-space($brand, display-p3)};
}

.tokens {
  --oklch: oklch(32.333781389% 0.1025438139 253.8851819964deg);
  --hsl: hsl(210, 100%, 20%);
  --p3: color(display-p3 0.0690923275 0.196438359 0.3861624224);
}

@use "sass:color";

@debug color.to-space(grey, lch); // lch(53.5850134522% 0 none)

.grey {
  color: color.to-space(grey, lch);
}

.grey {
  color: lch(53.5850134522% 0 none);
}

@use "sass:color";

@debug color.to-space(lch(none 10% 30deg), oklch);
// oklch(none 0.3782382557 11.1889157942deg)

.carry {
  color: color.to-space(lch(none 10% 30deg), oklch);
}

.carry {
  color: oklch(none 0.3782382557 11.1889157942deg);
}

@use "sass:color";

$brand: #036;
$brand-oklch: color.to-space($brand, oklch);

.report {
  --before: #{color.space($brand)};
  --after: #{color.space($brand-oklch)};
  --same-paint: #{color.same($brand, $brand-oklch)};
}

.report {
  --before: rgb;
  --after: oklch;
  --same-paint: true;
}

@use "sass:color";

$wide: oklch(60% 70% 20deg);
$as-rgb: color.to-space($wide, rgb);
$safe: color.to-gamut($wide, $space: rgb, $method: local-minde);

.pipeline {
  --converted-space: #{color.space($as-rgb)};
  --safe-oklch: #{$safe};
}

.pipeline {
  --converted-space: rgb;
  --safe-oklch: oklch(61.2058838235% 0.2466052584 22.0773325274deg);
}

🚀 Real-World Use Cases

• Token migrations — move hex brands into oklch for perceptual edits.
• Wide-gamut export — convert into display-p3 for modern displays.
• Legacy output — convert into rgb / hsl before emitting older CSS.
• Audit pipelines — pair with space and same after conversion.
• Missing-channel workflows — preserve or detect none after space changes.
• Teaching color spaces — show that space conversion is not gamut mapping.

⚠️ Common Pitfalls

• Quoting the space name — pass oklch, not "oklch".
• Confusing with to-gamut — conversion changes space; gamut mapping keeps the input space.
• Assuming every conversion is in-gamut — narrower destinations may need to-gamut.
• Surprise none channels — greys and powerless channels can become missing.
• Calling on older Dart Sass — needs 1.79+; expect Undefined function earlier.

💡 Best Practices