Sass color.to-gamut() Function

What You’ll Learn

color.to-gamut() belongs to the built-in sass:color module. It maps a color into the gamut (displayable range) of a target space while keeping a visually similar result. This page covers mandatory $method (local-minde vs clip), optional $space, the Dart Sass 1.79+ requirement, and five examples.

What Is color.to-gamut()?

Gamut means “the colors this space can actually show.” A vivid oklch accent can sit outside the smaller rgb (sRGB) gamut. Official docs: to-gamut returns a visually similar color that fits the gamut of $space. If the color is already in-gamut, it is returned unchanged. The result always stays in $color’s original space.

• color.to-gamut(#036, $method: local-minde) → #036 (already in-gamut)
• color.to-gamut(oklch(60% 70% 20deg), $space: rgb, $method: local-minde) → mapped oklch
• color.to-gamut(oklch(60% 70% 20deg), $space: rgb, $method: clip) → different mapped oklch

📝 Syntax

Load the color module, then pass a color, optional space, and a required method:

@use "sass:color";

// Dart Sass 1.79+
// $method is mandatory: local-minde | clip
color.to-gamut($color, $space: null, $method: null)

Parameters

Return value

📦 Loading sass:color

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

// Recommended — namespaced (Dart Sass 1.79+)
@use "sass:color";
$safe: color.to-gamut(#036, $method: local-minde);

// Optional — bring members into the current namespace
@use "sass:color" as *;
$safe: to-gamut(#036, $method: local-minde);

// Optional — custom namespace
@use "sass:color" as c;
$safe: c.to-gamut(#036, $method: local-minde);

⚖️ local-minde vs clip

Official docs describe two mapping strategies. Prefer local-minde for most design work unless you specifically want hard channel clamping.

📋 to-gamut vs to-space

These helpers often work together, but they do different jobs.

🛠 Compatibility

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

Examples Gallery

Examples target Dart Sass 1.79+. Compiled outputs below match the official Sass docs samples. Open View Compiled CSS to inspect them.

@use "sass:color";

@debug color.to-gamut(#036, $method: local-minde); // #036

.swatch {
  color: color.to-gamut(#036, $method: local-minde);
}

.swatch {
  color: #036;
}

@use "sass:color";

// Official docs sample (Dart Sass 1.79+)
@debug color.to-gamut(
  oklch(60% 70% 20deg),
  $space: rgb,
  $method: local-minde
);
// oklch(61.2058838235% 0.2466052584 22.0773325274deg)

.accent {
  color: color.to-gamut(
    oklch(60% 70% 20deg),
    $space: rgb,
    $method: local-minde
  );
}

.accent {
  color: oklch(61.2058838235% 0.2466052584 22.0773325274deg);
}

@use "sass:color";

@debug color.to-gamut(
  oklch(60% 70% 20deg),
  $space: rgb,
  $method: clip
);
// oklch(62.5026609544% 0.2528579741 24.1000466758deg)

.accent-clip {
  color: color.to-gamut(
    oklch(60% 70% 20deg),
    $space: rgb,
    $method: clip
  );
}

.accent-clip {
  color: oklch(62.5026609544% 0.2528579741 24.1000466758deg);
}

@use "sass:color";

$wide: oklch(60% 70% 20deg);

.compare {
  --local-minde: #{color.to-gamut($wide, $space: rgb, $method: local-minde)};
  --clip: #{color.to-gamut($wide, $space: rgb, $method: clip)};
}

.compare {
  --local-minde: oklch(61.2058838235% 0.2466052584 22.0773325274deg);
  --clip: oklch(62.5026609544% 0.2528579741 24.1000466758deg);
}

@use "sass:color";

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

.button {
  background: $accent-safe;
  border-color: color.to-gamut(#036, $method: local-minde);
  --source-space: #{color.space($accent-safe)};
}

.button {
  background: oklch(61.2058838235% 0.2466052584 22.0773325274deg);
  border-color: #036;
  --source-space: oklch;
}

🚀 Real-World Use Cases

• sRGB-safe brands — map wide oklch accents before shipping hex/rgb-first sites.
• Design-token pipelines — normalize out-of-gamut picks from Figma / display-p3 mockups.
• After to-space — convert, then gamut-map when the destination is narrower.
• Method A/B checks — compare local-minde vs clip for critical brand hues.
• Print / screen handoff — pull colors into a known gamut before export.
• Teaching color spaces — show that space conversion and gamut mapping are different steps.

⚠️ Common Pitfalls

• Omitting $method — it is mandatory; Sass will not guess until CSS settles a default.
• Expecting a space change — to-gamut keeps the input space; use to-space to convert.
• Assuming methods match — local-minde and clip can produce different mapped colors.
• Calling on older Dart Sass — needs 1.79+; expect Undefined function earlier.
• Looking for a global to-gamut() — there is none; use the module form.

💡 Best Practices