Sass color.to-space()

Intermediate
12 min read
Updated: Nov 2026
5 examples
Dart Sass 1.79+
Sass color.to-space converting colors between writing spaces like oklch and display-p3
Definition

Definition and Usage

color.to-space($color, $space) converts a color into another writing space. $space must be an unquoted name such as oklch, hsl, or display-p3. Load it with @use "sass:color" on Dart Sass 1.79+.

Official fun fact: this is the only Sass color function that returns a color in a different space than the one passed in. Paint usually stays the same — check with color.same().

Official samples.

color.to-space(grey, lch) → lch(~53.6% 0 none) (powerless hue). color.to-space(#036, display-p3) → color(display-p3 …).

Out-of-gamut possible.

If the destination gamut is narrower, the result can sit outside that gamut. Pair with color.to-gamut() when you need an in-gamut neighbor.

Syntax

Syntax

SCSS
@use "sass:color";

// Dart Sass 1.79+ — $space is an unquoted name
color.to-space(#036, oklch);
color.to-space(#036, display-p3);
color.to-space(#036, hsl);
color.to-space(grey, lch);

// Module only — no separate global to-space()

Pattern: convert with to-space for a preferred writing format → map with to-gamut when the destination gamut is too small.

Reference

Space & Gamut

How conversion behaves:

IdeaMeaning
$spaceUnquoted destination name (oklch, rgb, display-p3, …)
Return spaceAlways the requested $space — unlike to-gamut
Missing channelsMay appear when source is missing or destination channel is powerless
Legacy destinationsNever invent a new missing channel (older-browser-safe)
Narrower gamutResult can be out-of-gamut — follow with to-gamut if needed
to-space vs to-gamut.

to-space rewrites the space name. to-gamut keeps the writing space and only pulls values into a chosen gamut.

Code

SCSS Examples

Examples target Dart Sass 1.79+. Open View Compiled CSS for verified output.

Example 1 — Hex → oklch

Rewrite a classic navy into a modern perceptual space.

SCSS
@use "sass:color";

@debug color.to-space(#036, oklch);
// oklch(~32.3% ~0.103 ~253.9deg)

.navy {
  color: color.to-space(#036, oklch);
}

How It Works

  1. #036 starts in a legacy rgb-like space.
  2. oklch is the unquoted destination.
  3. Channels rewrite while paint stays equivalent.
  4. Useful before relative writers like scale / adjust.

Example 2 — Hex → display-p3

Emit a wide-gamut CSS color() value for P3 screens.

SCSS
@use "sass:color";

@debug color.to-space(#036, display-p3);
// color(display-p3 ~0.069 ~0.196 ~0.386)

.navy {
  color: color.to-space(#036, display-p3);
}

How It Works

  1. Same navy, different writing space.
  2. Output uses the CSS color(display-p3 …) form.
  3. Space name is unquoted display-p3.
  4. Pair with media queries when shipping dual sRGB / P3 tokens.

Example 3 — Visual Equality with color.same()

Official pattern: converted colors still match visually.

SCSS
@use "sass:color";

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

.guard {
  --match: #{color.same($hex, $oklch)};
  --space: #{color.space($oklch)};
  color: $oklch;
}

How It Works

  1. same() compares appearance across spaces.
  2. space() confirms the writing space changed.
  3. Hex vs oklch still report true.
  4. Good regression check after conversions.

Example 4 — Missing / Powerless Channels (Official Docs)

Grey has no hue; converting into lch keeps hue missing (none).

SCSS
@use "sass:color";

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

@debug color.to-space(lch(none 10% 30deg), oklch);
// oklch(none ~0.378 ~11.2deg)

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

How It Works

  1. Powerless hue on grey becomes none in lch.
  2. Missing lightness can carry into oklch.
  3. Legacy destinations never invent a brand-new missing channel.
  4. Inspect with color.is-missing() when debugging.

Example 5 — Gamut-Map, Then Rewrite Space

When a wide token must fit sRGB and emit as rgb.

SCSS
@use "sass:color";

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

.safe {
  --oklch: #{$mapped};
  --rgb: #{$as-rgb};
}

How It Works

  1. First pull into the rgb gamut while staying in oklch.
  2. Then rewrite with to-space(..., rgb).
  3. Order matters when shipping legacy-friendly CSS.
  4. Requires Dart Sass 1.79+ for both helpers.

Edge Cases & Pitfalls

Most to-space bugs are quoted space names, confusing it with to-gamut, or ignoring out-of-gamut results.

string

Pass unquoted space names

Write oklch / display-p3 — not "oklch".

gamut

Conversion is not gamut mapping

Narrower destinations can leave out-of-gamut channels. Use to-gamut when you need an in-gamut neighbor.

missing

Expect none on powerless channels

Greys and analogous missing channels can serialize with none.

module

No global to-space()

Always @use "sass:color" on Dart Sass 1.79+.

Toolchain

Sass Support

color.to-space() is a modern module helper. Prefer Dart Sass 1.79+ with @use "sass:color".

APIStatus
color.to-space()Dart Sass 1.79+
$spaceRequired unquoted space name
Global to-space()Not provided
LibSass / Ruby SassUnsupported

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • Rewrites the writing space — the only Sass color helper that changes space.
  • Pass unquoted names like oklch and display-p3.
  • Use to-gamut when a narrower gamut leaves values out of range.
  • Module only on Dart Sass 1.79+ — no global to-space().

One line: when you need a color stored in another space, call color.to-space($color, $space).

Practice

Compile Notes

Practical checklist:

checklist.txt
1. Require Dart Sass 1.79+
2. @use "sass:color"
3. Pass an unquoted $space (oklch, hsl, display-p3, …)
4. Verify paint with color.same() when needed
5. Follow with color.to-gamut() if the destination gamut is too narrow

Frequently Asked Questions

color.to-space($color, $space) converts a color into another color space. $space must be an unquoted name like oklch or display-p3. Example: color.to-space(#036, oklch) returns an oklch color that paints like #036.
Usually the color looks the same, just stored differently. color.same(#036, color.to-space(#036, oklch)) is true. A narrower destination gamut can leave values out-of-gamut — use color.to-gamut() afterward if needed.
to-space changes the writing space. to-gamut keeps the writing space and maps channels into a chosen gamut. Official fun fact: to-space is the only Sass color function that returns a color in a different space than the one passed in.
to-space can produce missing channels when a channel is missing on the source or powerless in the destination. Converting into a legacy space never invents a new missing channel.
color.to-space() needs Dart Sass 1.79+. Older compilers report Undefined function.
No. Use the module form color.to-space() after @use "sass:color".

Next: Sass color.whiteness()

Read the HWB whiteness channel of a color.

color.whiteness() →

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.to-gamut Function Sass color.whiteness Function