better-color-tools

better-color-tools

Better color manipulation for Sass and JavaScript/TypeScript. Fast (75,000 ops/s) and lightweight (3.7 kB gzip).

Supports:

• ✅ RGB / Hex
• ✅ HSL
• ✅ P3

👉 Playground: https://better-color-tools.pages.dev/

Installing

npm install better-color-tools

Mix

Not all mixing algorithms are created equal. A proper color mixer requires gamma correction, something most libraries omit (even including Sass, CSS, and SVG). Compare this library’s gamma-corrected results (top) with most libraries’ default mix function:

Notice all the bottom gradients have muddy/grayed-out colors in the middle as well as clumping (colors bunch up around certain shades or hues). But fear not! better-color-utils will always give you those beautiful, perfect color transitions you deserve.

// Sass
@use 'better-color-tools' as color;

$mix: color.mix(#1a7f37, #cf222e, 0); // 100% color 1, 0% color 2
$mix: color.mix(#1a7f37, #cf222e, 0.25); // 75%, 25%
$mix: color.mix(#1a7f37, #cf222e, 0.5); // 50%, 50%
$mix: color.mix(#1a7f37, #cf222e, 0.75); // 25%, 75%
$mix: color.mix(#1a7f37, #cf222e, 1); // 0%, 100%

// JavaScript / TypeScript
import color from 'better-color-tools';

const mix = color.mix(0x1a7f37, 0xcf222e, 0); // 100% color 1, 0% color 2
const mix = color.mix(0x1a7f37, 0xcf222e, 0.25); // 75%, 25%
const mix = color.mix(0x1a7f37, 0xcf222e, 0.5); // 50%, 50%
const mix = color.mix(0x1a7f37, 0xcf222e, 0.75); // 25%, 75%
const mix = color.mix(0x1a7f37, 0xcf222e, 1); // 0%, 100%

Note: 0xcf222e in JS is just another way of writing '#cf222e' (replacing the # with 0x). Either are valid; use whichever you prefer!

Advanced: gamma adjustment

To change the gamma adjustment, you can pass in an optional 4th parameter. The default gamma is 2.2, but you may adjust it to achieve different results (if unsure, best to always omit this option).

// Sass
$gamma: 2.2; // default
$mix: color.mix(#1a7f37, #cf222e, 0, $gamma);

// JavaScript / TypeScript
const gamma = 2.2; // default
const mix = color.mix(0x1a7f37, 0xcf222e, 0, gamma);

Lighten / Darken

Top: better-color-utils / Bottom: RGB averaging

The lighten and darken methods also use gamma correction for improved results (also better than Sass’ color.lighten() and color.darken()). This method is relative, so no matter what color you start with, darken(…, 0.5) will always be halfway to black, and lighten(…, 0.5) will always be halfway to white.

// Sass
@use 'better-color-tools' as color;

$lighter: color.lighten(#cf222e, 0); // 0% lighter (original color)
$lighter: color.lighten(#cf222e, 0.25); // 25% lighter
$lighter: color.lighten(#cf222e, 1); // 100% lighter (pure white)

$darker: color.darken(#cf222e, 0); // 0% darker (original color)
$darker: color.darken(#cf222e, 0.25); // 25% darker
$darker: color.darken(#cf222e, 1); // 100% darker (pure black)

// JavaScript / TypeScript
import color from 'better-color-tools';

color.lighten(0xcf222e, 0); // 0% lighter (original color)
color.lighten(0xcf222e, 0.25); // 25% lighter
color.lighten(0xcf222e, 1); // 100% lighter (pure white)

color.darken(0xcf222e, 0); // 0% darker (original color)
color.darken(0xcf222e, 0.25); // 25% darker
color.darken(0xcf222e, 1); // 100% darker (pure black)

Gradient

Top: better-color-utils / Bottom: standard CSS gradient

CSS gradients and SVG gradients are, sadly, not gamma-optimized. But you can fix that with color.gammaGradient(). While there’s no perfect fix for this, this solution drastically improves gradients without bloating filesize.

// JavaScript/TypeScript
ipmort color from 'better-color-tools';

const badGradient = 'linear-gradient(90deg, red, lime)';
const awesomeGradient = color.gammaGradient(badGradient); // linear-gradient(90deg,#ff0000,#e08800,#baba00,#88e000,#00ff00)
const awesomeP3Gradient = color.gammaGradient(badGradient, true); // linear-gradient(90deg,color(display-p3 0 0 1), … )

color.gradient() takes any valid CSS gradient as its first parameter. Also specify true as the 2nd parameter to generate a P3 gradient instead of hex.

⚠️ Note: unfortunately there’s not a generator function for Sass (and may not ever be) as it’s quite hard to manipulate strings. Please try the sandbox to generate a gradient and copy/paste into Sass for now (which will also let you modify it / improve it).

Conversion

Sass

Sass already has many built-in converters, so this library only extends what’s there. Here are a few helpers:

P3

The p3() function can convert any Sass-readable color into P3:

$green: #00ff00;
$blue: #0000ff;

color: $green; // #00ff00
color: p3($green); // color(display-p3 0 1 0)

background: linear-gradient(135deg, $green, $blue); // linear-gradient(135deg, #00ff00, #0000ff)
background: linear-gradient(135deg, p3($green), p3($blue)); // linear-gradient(135deg, color(display-p3 0 1 0), color(dipslay-p3 0 0 1)))

⚠️ Be sure to always include fallback colors when using P3

JavaScript / TypeScript

color.from() takes any valid CSS string, hex number, or RGBA array (values normalized to 1) as an input, and can generate any desired output as a result:

import color from 'better-color-tools';

color.from('rgb(196, 67, 43)').hex; // '#c4432b'
color.from('rebeccapurple').hsl; // 'hsl(270, 50%, 40%)'

Output	Type	Example
hex	string	"#ffffff"
hexVal	number	0xffffff
rgb	string	"rgb(255, 255, 255)"
rgbVal	number[]	[1, 1, 1, 1]
rgba	string	"rgba(255, 255, 255, 1)"
hsl	string	"hsl(360, 0%, 100%)"
hslVal	number[]	[360, 0, 1, 1]"
p3	string	"color(display-p3 1 1 1)"

A note on HSL

HSL is lossy when rounding to integers, so better-color-tools will yield better results than any library that rounds HSL, or rounds HSL by default.

A note on CSS color names

This library can convert FROM a CSS color name, but can’t convert INTO one (as over 99% of colors have no standardized name). However, you may import better-color-tools/dist/css-names.js for an easy-to-use map for your purposes._

A note on P3

When converting to or from P3, this library converts “lazily,” meaning the R/G/B channels are converted 1:1. This differs from some conversions which attempt to simulate hardware differences. Compare this library to colorjs.io:

P3 Color	better-color-tools	colorjs.io
1 0 0	255 0 0	250 0 0

For the most part, this approach makes P3 much more usable for web and is even recommended by Apple for Safari.

TODO / Roadmap

• Planned: Adding color spaces like Adobe and Rec 709 to allow color mixing and lightening/darkening to use different perceptual color algorithms
• Planned: Generate nice, gamma-corrected CSS gradients (with P3 enhancements for Safari)

Changelog

0.3.0

Minor Changes

• 61062ac: Add gradient tool
• 9256660: Add Sass p3() function, improve gradient tool