Return a random RGB array.

Return an item in COLOR_SPACES. If space argument is a invalid string, that is, find the item that ColorSpace.name_ === space (if no such item, return RGB space).

Convert color from a space to target space.

toSpace([176, 59, 79], 'RGB', 'XYZ'); // [ 20.88159899406145, 12.925309240980702, 8.790857610353417 ]
rgb2xyz([176, 59, 79]);               // [ 20.88159899406145, 12.925309240980702, 8.790857610353417 ]

Convert the color to string.

If checkSupport is true, then the function will set sep = ' ' and change the color space to RGB when the browser does not support this color space.

getCssColor([140, 17, 243], 'RGB');                        // "rgb(54.9% 6.67% 95.29%)"
getCssColor([140, 17, 243], 'RGB', { sep_: "," });         // "rgb(54.9%,6.67%,95.29%)"
getCssColor([140, 17, 243], 'RGB', { percent_: false });   // "rgb(140 17 243)"
getCssColor([273, 90, 51], 'HSL');                         // "hsl(273 90% 51%)"
getCssColor([27, 12, 86], 'xyz');                          // "xyz(28.41% 12% 78.98%)"
getCssColor([27, 12, 86], 'xyz', { checkSupport_: true }); // "color(xyz-d65 28.41% 12% 78.98%)"

type CssColorOptions = {
  /**
   * Check the browser support or not. If browser does not support the color,
   * return string in RGB space.
   * @default false
   */
  checkSupport_?: boolean,
  /**
   * Seperator of values. If checkSupport_ is true, the seperator will always be ' '
   * @default ' '
   */
  sep_?: string,
  /**
   * Convert all values to percent except deg.
   * @default true
   */
  percent_?: boolean,
  /**
   * Argument for rounding values. Set false to disable rounding. true equials
   * default value.
   * @default 2
   */
  place_?: number | boolean
}

See also

• <color>
• color()

Normalize RGB or HEX to array type.

Change the reference white of CIEXYZ space. This library only support sRGB for RGB model. This function will change .max_ property of XYZ space.

Several keywords are aliases for each other, we only preserve one of alias:

and other 6 groups of alias that containing 'gray' (preserved) or 'grey' (removed).

The maximum value is based on RGB model and reference white. y channel will be normalize to 100. The library currently only supports sRGB as RGB model and D65 (default) and D50 as reference white.

D65

D50

The range of a and b follows the format of CSS. See: lab().

The LCH space that converted from LAB.

The range of u and v channels are the extreme values when converting from RGB to LUV.

The LCH space that converted from LUV.

The range of a and b follows the format of CSS. See: oklab().

Return the grayscale value (within [0, 255]) of an RGB color. See: color brightness

rgb2gray([1, 100, 255]); // 88.06899999999999

Return true if the grayscale value of an RGB array or a hex string is greater than 127.5. Otherwise, return false. rgb2gray

rgb2gray([156, 49, 93]); // 86.009
isLight([156, 49, 93]);  // false

rgb2gray('#E6ECB6');     // 228.04999999999995
isLight('#E6ECB6');      // true

Hue of RGB. Note that this value is different from hue of CIELCH.

rgb2hue([1, 100, 255]); // 216.61417322834643

Return the relative luminance (within [0, 1]) of an RGB array or a hex string. See: WCAG2.0 relative luminance

getRelativeLuminance([191, 123, 86]);   // 0.259141693330052
getRelativeLuminance([0, 0, 0]);        // 0
getRelativeLuminance([255, 255, 255]);  // 1

Return the contrast ratio of two RGB colors. See: WCAG2.0 contrast ratio

getContrastRatio([191, 123, 86], [230, 236, 182]); // 2.759999999999999
getContrastRatio([0, 0, 0], '#FFF');               // 20.99999999999999
getContrastRatio('FFF', [0, 0, 0]);                // 20.99999999999999

Check that the contrast ratio of two colors (background and text) is satisfing the WCAG standard. See: WCAG2.1 contrast minimum

type ReadbleOptions = {
  /**
   * Text size is large scale (`true`) or normal scale (`false`).
   * @default false
   */
  isLarge?: boolean,
  /**
   * Required to satisfy WCAG level AAA (`true`) or level AA (`false`).
   * @default false
   */
  levelAAA?: boolean
}

isReadable([191, 123, 86], [230, 236, 182]);       // false
isReadable('000', '#FFF', { levelAAA: true });     // true
isReadable('987654', '123456');                    // false
isReadable('987654', '123456', { isLarge: true }); // true
isReadable('987654', '123456', { isLarge: true, levelAAA: true }) // false

Return a palette that each color is the hue shift of primary. The primary color should be HSB, HSL, HWB color, or color space that first channel represents hue.

The return space is the same as the input space.

shiftHue([43, 12, 94], [0, 30, 60]);    // [ [ 43, 12, 94 ], [ 73, 12, 94 ], [ 103, 12, 94 ] ]
shiftHue([159, 76, 84], [0, 120, 240]); // [ [ 159, 76, 84 ], [ 279, 76, 84 ], [ 399, 76, 84 ] ]

Return a gradient that colors decreasing in brightness from bri = hsb[2] to bri * (1-1/num).

The return space is the same as the input space.

shades([26, 83, 90], 6); // [ [ 26, 83, 90 ], [ 26, 83, 75 ], [ 26, 83, 60 ], [ 26, 83, 45 ], [ 26, 83, 30 ], [ 26, 83, 15 ] ]
shades([84, 39, 80], 2); // [ [ 84, 39, 80 ], [ 84, 39, 40 ] ]

Return a gradient that colors decreasing in saturation from sat = hsb[1] to sat * (1-1/num).

The return space is the same as the input space.

tints([346, 83, 100], 6); // [ [ 346, 83, 100 ], [ 346, 69.17, 100 ], [ 346, 55.33, 100 ], [ 346, 41.5, 100 ], [ 346, 27.67, 100 ], [ 346, 13.83, 100 ] ]
tints([7, 30, 58], 2);    // [ [ 7, 30, 58 ], [ 7, 15, 58 ] ]

Return a gradient that colors decreasing in both saturation (from sat = hsb[1] to sat * (1-1/num)) and brightness (from bri = hsb[2] to bri * (1-1/num)).

The return space is the same as the input space.

tones([256, 51, 52], 6); // [ [ 256, 51, 52 ], [ 256, 42.5, 43.33 ], [ 256, 34, 34.67 ], [ 256, 25.5, 26 ], [ 256, 17, 17.33 ], [ 256, 8.5, 8.67 ] ]
tones([342, 95, 73], 2); // [ [ 342, 95, 73 ], [ 342, 47.5, 36.5 ] ]

Generate harmony palettes. The return space is RGB.

harmonize([54, 98, 47], 'analogous');      // [ [ 119.85, 49.38, 2.4 ], [ 119.85, 108.1, 2.4 ], [ 72.87, 119.85, 2.40 ] ]
harmonize([58, 64, 48], 'shades', 3);      // [ [ 122.4, 119.8, 44.064 ], [ 81.6, 79.8592, 29.38 ], [ 40.8, 39.93, 14.69 ] ]
harmonize([131, 98, 76], 'complementary'); // [ [ 3.88, 193.8, 38.7 ], [ 193.8, 3.88, 158.98 ] ]

Input a number as method argument will equals the order of method below. If the input is invalid, then it will use 'analogous'

Mixing two colors by evaluate weighted sum weight1 * color1 + weight2 * color2.
The weights will be normalized to 1 if their sum > 1.

mix([42, 62, 206], [55, 202, 93], 0.5, 0.5);     // [ 48.5, 132, 149.5 ]
mix([155, 122, 126], [211, 243, 242], 0.2);      // [ 199.8, 218.8, 218.8 ]
mix([204, 248, 241], [149, 241, 118], 3, 2);     // [ 182, 245.2, 191.8 ]
mix([204, 248, 241], [149, 241, 118], 0.6, 0.4); // [ 182, 245.2, 191.8 ]

Return the elementwise mean of two colors.

meanMix([42, 62, 206], [55, 202, 93]);     // [ 48.5, 132, 149.5 ]
meanMix([155, 122, 126], [211, 243, 242]); // [ 183, 182.5, 184 ]

1. Evaluate the elementwise mean mean of colors.
2. Convert mean to HSL space.
3. Evaluate new saturation and luminance: newVal = 100 * (val / 100)**gamma;.
4. Convert new HSL color to original space and return.

The inputs and output are in RGB space.

If gamma < 1, the returns will brighter than meanMix. If gamma > 1, the returns will deeper than meanMix.

gammaMix([42, 62, 206], [55, 202, 93], 0.7);     // [ 54.39561213833195, 181.8755020626048, 208.5928442623028 ]
gammaMix([155, 122, 126], [211, 243, 242], 1.2); // [ 171.41502723522638, 171.18140357959763, 171.8822745464839 ]

gammaMix with gamma = 0.3.

The inputs and output are in RGB space.

brighterMix([42, 62, 206], [55, 202, 93]);     // [ 140.49399108764436, 225.63360346857013, 243.47723480588996 ]
brighterMix([155, 122, 126], [211, 243, 242]); // [ 228.89399229092206, 224.81031497062736, 237.06134693151148 ]

gammaMix with gamma = 1.5.

The inputs and output are in RGB space.

deeperMix([42, 62, 206], [55, 202, 93]);     // [ 39.21213833570636, 76.37097203065198, 84.1587515475568 ]
deeperMix([155, 122, 126], [211, 243, 242]); // [ 155.3090002573382, 155.2379985085759, 155.4510037548627 ]

See wiki blend modes. The order of input color will influence the result.

The inputs and output are in RGB space.

softLightBlend([42, 62, 206], [55, 202, 93], 'RGB');              // [ 22.051211072664362, 99.24922945171917, 195.2889504036909 ]
softLightBlend([42, 62, 206], [55, 202, 93], 'RGB', 'photoshop'); // [ 22.05121107266436, 99.24288450324661, 195.28895040369088 ]
softLightBlend([55, 202, 93], [42, 62, 206], 'RGB', 'photoshop'); // [ 26.072664359861598, 180.4315878508266, 130.55486374261477 ]

Add their RGB values.

The inputs and output are in RGB space.

additive([42, 62, 206], [55, 202, 93]);     // [ 97, 255, 255 ]
additive([155, 122, 126], [211, 243, 242]); // [ 255, 255, 255 ]

Mix colors (at least two) by specifying the method. The return space is the same as the input space.

The inputs and output are in RGB space.

type Mixing =  "additive" | "mean" | "brighter" | "deeper" | "soft light" | "weighted";

Scale ths values of RGBs by multiplying c. The values will be clipped to [0, 255].

The inputs and output are in RGB space.

scaling([170, 107, 170], 1.2); // [ [ 204, 128.4, 204 ] ]
scaling([146, 167, 40], 0.7);  // [ [ 102.2, 116.9, 28 ] ]

Calculate the new value of RGBs by the formula newVal = 255 * (val / 255)**gamma. If gamma < 1, the returns will brighter than original color. If gamma > 1, the returns will deeper than original color.

The inputs and output are in RGB space.

The inputs and output are in RGB space.

gammaCorrection([148, 241, 14], 2);  // [ [ 85.9, 227.77, 0.77 ] ]
gammaCorrection([178, 4, 200], 0.7); // [ [ 198.27, 13.91, 215.12 ] ]

Enhance the contrast by the following steps:

1. Find minimum lightness and maximum lightness in LAB space.
2. Scaling from [minimum, maximum] to [0, 100]
3. Convert new color to RGB space and return.

The inputs and output are in RGB space.

Adjust the brightness of input RGBs. The outputs become darker when coeff close to 0 and become brighter when coeff close to 1

1. Find mean lightness meanL in LAB space.
2. Calculate gamma = log(coeff) / log(meanL / 100);.
3. Do gamma correction to L channel with gamma.
4. Convert new color to RGB space and return.

The inputs and output are in RGB space.

Adjust the contrast of array of RGB colors by specifying the method.

The inputs and output are in RGB space.

type ContrastMethod = "linear" | "gamma" | "auto enhancement" | "auto brightness";

Return the difference of grayscales rgb2gray(rgb1) - rgb2gray(rgb2).

Return the L2-distance of two LAB colors. This is the CIE 1976 color difference (CIE76 or E76).

Return the square of CIE 1994 color difference (CIE94 or E94).

The square: CIE94 formula will take square root. This function is present for comparing the color difference between colors, e.g. distE94(lab1, lab2) < distE94(lab1, lab3), thus the square root is unnecessary.

Return CIEDE2000 color difference (CIEDE2000 or E00).

In-place shuffle an array by Fisher-Yates shuffle.

Sort by Greedy algorithm. The first item will be fixed. The second is the closest item to the first and so on.

The argument rgbGetter make this function can handle the object such as { color : number[], otherProperty: unknown }.

Return a sorted and copied (cloneDeep) array of objects.

The argument rgbGetter make this function can handle the object such as { color : number[], otherProperty: unknown }.

type Sort =  "luminance" | "random" | "reversion" | "CIE76" | "CIE94" | "CIEDE2000";

Return a sorted and copied array of RGB colors. Similar to sortColors but input arrays directly.

type Sort =  "luminance" | "random" | "reversion" | "CIE76" | "CIE94" | "CIEDE2000";

The input is a channel/value of RGB, not array.

The full-scale value of linear-RGB is 1 due to the calculation of CIEXYZ and relative luminance.

srgb2linearRgb(127);                 // 0.21223075741405512
linearRgb2srgb(srgb2linearRgb(127)); // 127
linearRgb2srgb(0.5);                 // 187.5160306783746

The input is a channel/value of LAB, not array.

This function is part of the conversion between CIEXYZ and CIELAB. I do not know the formal name.

const cieTrans = (val: number): number => {
  return val > (6/29)**3 ? Math.cbrt(val) : (903.3 * x + 16) / 116;
};
const cieTransInv = (val: number) => {
  return val > (6/29) ? val**3 : (val - 16/116) / (903.3/116) ;
};

and cieTransInv is the inverse function of cieTrans.

Deeply clone object.

The following types will be handle:

• primitive type
• Number, String, Boolean (convert to primitive type)
• Date
• built-in object

If other type with typeof obj === 'object' will turn into built-in object. The other types will not be copied.

type map = {
  /**
   * Generate an array with specific length.
   */
  <R>(
    len: number,
    callback: (i: number) => R
  ): R[];
  /**
   * Similar to Array.prototype.map but this can control the length of output array .
   */
  <R, T>(
    arr: readonly T[],
    callback: (val: T, i: number) => R,
    len?: number,
  ): R[]
}

In most cases, replace Array.prototype.map with this function can improve the performance and file size.

Equivalent to x**y. Much more faster than x**y and Math.pow(x,y) if y is uncertain.

For square, simply write x * x.

if (!x && !y) return 1;
return Math.exp(y * Math.log(x));

Generate a random (positive) integer in [0, max].

Rounding a number to specific place value. Positive place means decimal places and negative means whole number places.

Math.round(10**place * num) / 10**place;

Limit the number in the interval [min, max]. If min and/or max is undefined, it will be regarded as unbound.

if (num < min!) num = min!; // max < min return min
else if (num > max!) num = max!;
return num;

Scaling and shift to new range. If place is given, then round new value.

const rangeMapping = (
  val: number,
  min: number,
  max: number,
  newMin: number,
  newMax: number,
  place?: number,
) => {
  const ratio = clip((val - min) / (max - min), 0, 1); // avoid floating problem.
  const newVal = newMin + ratio * (newMax - newMin);
  return place == null ? newVal : round(newVal, place);
};

Conversions between degree and radian.

Elementwise mean of two array. The length of output is Math.min(arr1.length, arr2.length).

Dot two arrays with length = 3.

const dot3 = (arr1: readonly number[], arr2: readonly number[]): number => {
  return arr1[0] * arr2[0] + arr1[1] * arr2[1] + arr1[2] * arr2[2];
};

Return a * a + b * b + c * c + d * d.

Return Math.sqrt(squareSum(a, b, c)).

const l2Dist3 = (color1: readonly number[], color2: readonly number[]): number => {
  return l2Norm3(
    color1[0] - color2[0],
    color1[1] - color2[1],
    color1[2] - color2[2]
  );
};

• 10 colors/sampling

rgb2xyz

xyz2rgb

• 500 colors/sampling

rgb2xyz

xyz2rgb

• 10 colors/sampling

rgb2cmyk

cmyk2rgb

• 500 colors/sampling

rgb2cmyk

rgb2cmyk

• 10 colors/sampling

rgb2hex

hex2rgb

• 500 colors/sampling

rgb2hex

hex2rgb

• 10 colors/sampling

rgb2hsb

hsb2rgb

• 500 colors/sampling

rgb2hsb

hsb2rgb

• 10 colors/sampling

rgb2named

named2rgb

• 500 colors/sampling

rgb2named

named2rgb

• 10 colors/sampling

rgb2oklab

oklab2rgb

• 500 colors/sampling

rgb2oklab

oklab2rgb

Our function handle more checks.

'color-utils': Default option.
'color-utils (number)': Pass { percent_: false }.

• 10 colors/sampling

To RGB string

rgb2hsl + to HSL string

rgb2xyz + to XYZ string

rgb2lab + to LAB string

• 500 colors/sampling

To RGB string

rgb2hsl + to HSL string

rgb2xyz + to XYZ string

rgb2lab + to LAB string

• 10 times/sampling

Adjust 5 colors for 6 times

Harmony: analogous. Generate 3 colors for 10 times

Harmony: shades. Generate 6 colors for 10 times

Mix 2 colors for 499 times

Sort 5 colors for 6 times

• 500 times/sampling

Harmony: analogous. Generate 3 colors for 500 times

Harmony: shades. Generate 6 colors for 500 times

Mix 2 colors for 499 times

• 10 colors/sampling

rgb2hue

isReadable

• 500 colors/sampling

rgb2hue

isReadable