color.to-gamut() returns a visually similar color that fits the gamut of $space (defaults to $color’s own space). If the color is already in-gamut, it is returned as-is. The result always stays in $color’s original space. Load it with @use "sass:color" on Dart Sass 1.79+.
Official docs: $method is mandatory (local-minde or clip) until CSS settles a default algorithm. There is no separate global alias.
color.to-gamut(#036, $method: local-minde) → #036 (already in gamut). Wide oklch(60% 70% 20deg) mapped into the rgb gamut differs for local-minde vs clip.
$method.Omitting it is an error on purpose so Sass can later default to whatever CSS chooses.
@use "sass:color";
// Dart Sass 1.79+ — $method is required
color.to-gamut(#036, $method: local-minde);
color.to-gamut(
oklch(60% 70% 20deg),
$space: rgb,
$method: local-minde
);
color.to-gamut(
oklch(60% 70% 20deg),
$space: rgb,
$method: clip
);
// Module only — no separate global to-gamut()Pattern: convert wide-gamut tokens with color.to-space() when needed → map into a display gamut with to-gamut.
$spaceOfficial method choices:
| Argument | Meaning |
|---|---|
$method: local-minde | CSS Colors 4 recommended path — search Oklch chroma for a close in-gamut color |
$method: clip | Clamp each channel to the gamut min/max |
$space | Unquoted space whose gamut you map into (default: the color’s own space) |
| Return space | Always $color’s original space — not necessarily $space |
to-space changes the writing space (and may leave values out-of-gamut). to-gamut keeps the writing space and pulls channels into a chosen gamut.
Examples target Dart Sass 1.79+. Open View Compiled CSS for verified output (matches official Sass docs samples where noted).
A normal hex navy needs no mapping.
@use "sass:color";
@debug color.to-gamut(#036, $method: local-minde); // #036
.navy {
color: color.to-gamut(#036, $method: local-minde);
}$method is still required even when nothing changes.local-mindeOfficial docs sample: map extreme chroma into the rgb gamut.
@use "sass:color";
@debug color.to-gamut(oklch(60% 70% 20deg), $space: rgb, $method: local-minde);
// oklch(~61.2% ~0.247 ~22deg)
.accent {
color: color.to-gamut(oklch(60% 70% 20deg), $space: rgb, $method: local-minde);
}oklch with huge chroma.$space: rgb chooses the sRGB gamut to fit.local-minde searches for a close in-gamut color.clip (Official Docs)Clipping is simpler and can look different from local-minde.
@use "sass:color";
@debug color.to-gamut(oklch(60% 70% 20deg), $space: rgb, $method: clip);
// oklch(~62.5% ~0.253 ~24deg)
.accent {
color: color.to-gamut(oklch(60% 70% 20deg), $space: rgb, $method: clip);
}clip clamps channels to the gamut bounds.local-minde.local-minde when following CSS Colors 4 guidance.Store both mappings so design review can pick a look.
@use "sass:color";
$wide: oklch(60% 70% 20deg);
.report {
--minde: #{color.to-gamut($wide, $space: rgb, $method: local-minde)};
--clip: #{color.to-gamut($wide, $space: rgb, $method: clip)};
}oklch).Pair with to-space when you need a different writing space too.
@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};
}to-space(..., rgb).Most to-gamut bugs are missing $method, confusing $space with return space, or expecting to-space behavior.
Always pass local-minde or clip. Leaving it out errors by design.
The returned color stays in the original space. Use to-space when you need a different writing format.
Write $space: rgb / display-p3 — unquoted, matching CSS.
Always @use "sass:color" on Dart Sass 1.79+.
color.to-gamut() is a modern module helper. Prefer Dart Sass 1.79+ with @use "sass:color".
| API | Status |
|---|---|
color.to-gamut() | Dart Sass 1.79+ |
$method | Required: local-minde or clip |
Global to-gamut() | Not provided |
| LibSass / Ruby Sass | Unsupported |
Compile with the Dart Sass CLI.
local-minde for CSS Colors 4 guidance.to-gamut().One line: when a wide-gamut token must fit a display gamut, call color.to-gamut with an explicit method.
Practical checklist:
1. Require Dart Sass 1.79+
2. @use "sass:color"
3. Always pass $method: local-minde or clip
4. Pass $space for the target gamut (unquoted)
5. Use color.to-space() only when you also need a new writing spaceConvert a color into another writing space.
8 people found this page helpful