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 better;

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

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

const mix = better.mix(0x1a7f37, 0xcf222e, 0); // 100% color 1, 0% color 2
const mix = better.mix(0x1a7f37, 0xcf222e, 0.25); // 75%, 25%
const mix = better.mix(0x1a7f37, 0xcf222e, 0.5); // 50%, 50%
const mix = better.mix(0x1a7f37, 0xcf222e, 0.75); // 25%, 75%
const mix = better.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: better.mix(#1a7f37, #cf222e, 0, $gamma);

// JavaScript / TypeScript
const gamma = 2.2; // default
const mix = better.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 better;

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

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

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

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

better.darken(0xcf222e, 0); // 0% darker (original color)
better.darken(0xcf222e, 0.25); // 25% darker
better.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 better.gradient(). While there’s no perfect fix for this, this solution drastically improves gradients without bloating filesize.

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

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

better.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).

Perceived Lightness

HSL’s lightness is basically worthless as it’s distorted by the RGB colorspace and has no bearing in actual color brightness or human perception. Don’t use HSL for lightness! Instead, use the following:

import better from 'better-color-tools;

const DARK_PURPLE = '#542be9'

// lightness: get human-perceived brightness of a color (blues will appear darker than reds and yellows, e.g.)
const lightness = better.lightness(DARK_PURPLE); // 0.3635 (~36% lightness)

// luminance: get absolute brightness of a color (this may not be what you want!)
const luminance = better.luminance(DARK_PURPLE); // 0.0919 (~9% luminance)

// HSL (for comparison)
const hsl = color.from(DARK_PURPLE).hslVal[3]; // 0.5412 (54%!? there’s no way this dark purple is that bright!)

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: better.p3($green); // color(display-p3 0 1 0)

background: linear-gradient(135deg, $green, $blue); // linear-gradient(135deg, #00ff00, #0000ff)
background: linear-gradient(135deg, better.p3($green), better.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

better.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 better from 'better-color-tools';

better.from('rgb(196, 67, 43)').hex; // '#c4432b'
better.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: LAB conversion
• Planned: Sass function for Gamma-corrected gradients