tinycolor

TinyColor is a small library for color manipulation and conversion

A fork of tinycolor2 by Brian Grinstead

DEMO: https://tinycolor.vercel.app

Changes from tinycolor2

• reformatted into TypeScript / es2015 and requires node >= 8
  • tree shakeable "module" export and no package sideEffects
• tinycolor is now exported as a class called TinyColor
• default export removed, use import { TinyColor } from '@ctrl/tinycolor'
• new random, an implementation of randomColor by David Merfield that returns a TinyColor object
• several functions moved out of the tinycolor class and are no longer TinyColor.<function>
  • readability, fromRatio moved out
  • random moved out and renamed to legacyRandom
  • toFilter has been moved out and renamed to toMsFilter
• mix, equals use the current TinyColor object as the first parameter
• added polyad colors tinycolor PR 126
• color wheel values (360) are allowed to over or under-spin and still return valid colors tinycolor PR 108
• added tint() and shade() tinycolor PR 159
• isValid, format are now propertys instead of a function

Install

npm install @ctrl/tinycolor

Use

import { TinyColor } from '@ctrl/tinycolor';
const color = new TinyColor('red').toHexString(); // '#ff0000'

Accepted String Input

The string parsing is very permissive. It is meant to make typing a color as input as easy as possible. All commas, percentages, parenthesis are optional, and most input allow either 0-1, 0%-100%, or 0-n (where n is either 100, 255, or 360 depending on the value).

HSL and HSV both require either 0%-100% or 0-1 for the S/L/V properties. The H (hue) can have values between 0%-100% or 0-360.

RGB input requires either 0-255 or 0%-100%.

If you call tinycolor.fromRatio, RGB and Hue input can also accept 0-1.

Here are some examples of string input:

Hex, 8-digit (RGBA) Hex

new TinyColor('#000');
new TinyColor('000');
new TinyColor('#369C');
new TinyColor('369C');
new TinyColor('#f0f0f6');
new TinyColor('f0f0f6');
new TinyColor('#f0f0f688');
new TinyColor('f0f0f688');

RGB, RGBA

new TinyColor('rgb (255, 0, 0)');
new TinyColor('rgb 255 0 0');
new TinyColor('rgba (255, 0, 0, .5)');
new TinyColor({ r: 255, g: 0, b: 0 });

import { fromRatio } from '@ctrl/tinycolor';
fromRatio({ r: 1, g: 0, b: 0 });
fromRatio({ r: 0.5, g: 0.5, b: 0.5 });

HSL, HSLA

new TinyColor('hsl(0, 100%, 50%)');
new TinyColor('hsla(0, 100%, 50%, .5)');
new TinyColor('hsl(0, 100%, 50%)');
new TinyColor('hsl 0 1.0 0.5');
new TinyColor({ h: 0, s: 1, l: 0.5 });

HSV, HSVA

new TinyColor('hsv(0, 100%, 100%)');
new TinyColor('hsva(0, 100%, 100%, .5)');
new TinyColor('hsv (0 100% 100%)');
new TinyColor('hsv 0 1 1');
new TinyColor({ h: 0, s: 100, v: 100 });

CMYK

new TinyColor('cmyk(0, 25, 20, 0)');
new TinyColor('cmyk(0, 100, 100, 0)');
new TinyColor('cmyk 100 0 100 0)');
new TinyColor({c: 0, m: 25, y: 25, k: 0});

Named

new TinyColor('RED');
new TinyColor('blanchedalmond');
new TinyColor('darkblue');

Number

new TinyColor(0x0);
new TinyColor(0xaabbcc);

Accepted Object Input

If you are calling this from code, you may want to use object input. Here are some examples of the different types of accepted object inputs:

{ r: 255, g: 0, b: 0 }
{ r: 255, g: 0, b: 0, a: .5 }
{ h: 0, s: 100, l: 50 }
{ h: 0, s: 100, v: 100 }

Properties

originalInput

The original input passed into the constructer used to create the tinycolor instance

const color = new TinyColor('red');
color.originalInput; // "red"
color = new TinyColor({ r: 255, g: 255, b: 255 });
color.originalInput; // "{r: 255, g: 255, b: 255}"

format

Returns the format used to create the tinycolor instance

const color = new TinyColor('red');
color.format; // "name"
color = new TinyColor({ r: 255, g: 255, b: 255 });
color.format; // "rgb"

isValid

A boolean indicating whether the color was successfully parsed. Note: if the color is not valid then it will act like black when being used with other methods.

const color1 = new TinyColor('red');
color1.isValid; // true
color1.toHexString(); // "#ff0000"

const color2 = new TinyColor('not a color');
color2.isValid; // false
color2.toString(); // "#000000"

Methods

getBrightness

Returns the perceived brightness of a color, from 0-255, as defined by Web Content Accessibility Guidelines (Version 1.0).

const color1 = new TinyColor('#fff');
color1.getBrightness(); // 255

const color2 = new TinyColor('#000');
color2.getBrightness(); // 0

isLight

Return a boolean indicating whether the color's perceived brightness is light.

const color1 = new TinyColor('#fff');
color1.isLight(); // true

const color2 = new TinyColor('#000');
color2.isLight(); // false

isDark

Return a boolean indicating whether the color's perceived brightness is dark.

const color1 = new TinyColor('#fff');
color1.isDark(); // false

const color2 = new TinyColor('#000');
color2.isDark(); // true

getLuminance

Returns the perceived luminance of a color, from 0-1 as defined by Web Content Accessibility Guidelines (Version 2.0).

const color1 = new TinyColor('#fff');
color1.getLuminance(); // 1

const color2 = new TinyColor('#000');
color2.getLuminance(); // 0

getAlpha

Returns the alpha value of a color, from 0-1.

const color1 = new TinyColor('rgba(255, 0, 0, .5)');
color1.getAlpha(); // 0.5

const color2 = new TinyColor('rgb(255, 0, 0)');
color2.getAlpha(); // 1

const color3 = new TinyColor('transparent');
color3.getAlpha(); // 0

setAlpha

Sets the alpha value on a current color. Accepted range is in between 0-1.

const color = new TinyColor('red');
color.getAlpha(); // 1
color.setAlpha(0.5);
color.getAlpha(); // .5
color.toRgbString(); // "rgba(255, 0, 0, .5)"

onBackground

Compute how the color would appear on a background. When the color is fully transparent (i.e. getAlpha() == 0), the result will be the background color. When the color is not transparent at all (i.e. getAlpha() == 1), the result will be the color itself. Otherwise you will get a computed result.

const color = new TinyColor('rgba(255, 0, 0, .5)');
const computedColor = color.onBackground('rgb(0, 0, 255)');
computedColor.toRgbString(); // "rgb(128, 0, 128)"

String Representations

The following methods will return a property for the alpha value, which can be ignored: toHsv, toHsl, toRgb

toHsv

const color = new TinyColor('red');
color.toHsv(); // { h: 0, s: 1, v: 1, a: 1 }

toHsvString

const color = new TinyColor('red');
color.toHsvString(); // "hsv(0, 100%, 100%)"
color.setAlpha(0.5);
color.toHsvString(); // "hsva(0, 100%, 100%, 0.5)"

toHsl

const color = new TinyColor('red');
color.toHsl(); // { h: 0, s: 1, l: 0.5, a: 1 }

toHslString

const color = new TinyColor('red');
color.toHslString(); // "hsl(0, 100%, 50%)"
color.setAlpha(0.5);
color.toHslString(); // "hsla(0, 100%, 50%, 0.5)"

toCmykString

const color = new TinyColor('red');
color.toCmykString(); // "cmyk(0, 100, 100, 0)"

toNumber

new TinyColor('#aabbcc').toNumber() === 0xaabbcc // true
new TinyColor('rgb(1, 1, 1)').toNumber() === (1 << 16) + (1 << 8) + 1 // true

toHex

const color = new TinyColor('red');
color.toHex(); // "ff0000"

toHexString

const color = new TinyColor('red');
color.toHexString(); // "#ff0000"

toHex8

const color = new TinyColor('red');
color.toHex8(); // "ff0000ff"

toHex8String

const color = new TinyColor('red');
color.toHex8String(); // "#ff0000ff"

toHexShortString

const color1 = new TinyColor('#ff000000');
color1.toHexShortString(); // "#ff000000"
color1.toHexShortString(true); // "#f000"

const color2 = new TinyColor('#ff0000ff');
color2.toHexShortString(); // "#ff0000"
color2.toHexShortString(true); // "#f00"

toRgb

const color = new TinyColor('red');
color.toRgb(); // { r: 255, g: 0, b: 0, a: 1 }

toRgbString

const color = new TinyColor('red');
color.toRgbString(); // "rgb(255, 0, 0)"
color.setAlpha(0.5);
color.toRgbString(); // "rgba(255, 0, 0, 0.5)"

toPercentageRgb

const color = new TinyColor('red');
color.toPercentageRgb(); // { r: "100%", g: "0%", b: "0%", a: 1 }

toPercentageRgbString

const color = new TinyColor('red');
color.toPercentageRgbString(); // "rgb(100%, 0%, 0%)"
color.setAlpha(0.5);
color.toPercentageRgbString(); // "rgba(100%, 0%, 0%, 0.5)"

toName

const color = new TinyColor('red');
color.toName(); // "red"

toFilter

import { toMsFilter } from '@ctrl/tinycolor';
toMsFilter('red', 'blue'); // 'progid:DXImageTransform.Microsoft.gradient(startColorstr=#ffff0000,endColorstr=#ff0000ff)'

toString

Print to a string, depending on the input format. You can also override this by passing one of "rgb", "prgb", "hex6", "hex3", "hex8", "name", "hsl", "hsv" into the function.

const color1 = new TinyColor('red');
color1.toString(); // "red"
color1.toString(