@ctrl/tinycolor
Advanced tools
The @ctrl/tinycolor npm package is a comprehensive tool for color manipulation and conversion. It allows users to perform a variety of operations on colors, including parsing colors in different formats, converting between color models (e.g., RGB, HSL, HSV), and manipulating colors (e.g., lighten, darken, saturate).
Color Parsing
This feature allows the parsing of colors from strings in various formats, including HEX, RGB, RGBA, HSL, HSLA, etc. The code sample demonstrates how to parse a color from a HEX string and an RGBA string.
"const tinycolor = require('@ctrl/tinycolor');\nconst color1 = tinycolor('#f00');\nconst color2 = tinycolor('rgba(255, 0, 0, 0.5)');"Color Conversion
This feature enables the conversion of colors between different models and formats. The code sample shows how to convert a named color ('red') to its HSV representation and then to an RGB string.
"const tinycolor = require('@ctrl/tinycolor');\nconst color = tinycolor('red');\nconst hsvColor = color.toHsv();\nconst rgbString = color.toRgbString();"Color Manipulation
This feature provides methods to manipulate colors, such as lightening, darkening, and desaturating. The code sample demonstrates how to lighten and desaturate a color.
"const tinycolor = require('@ctrl/tinycolor');\nconst color = tinycolor('red');\nconst lighterColor = color.lighten().toString();\nconst desaturatedColor = color.desaturate().toString();"chroma-js is a powerful library for all kinds of color conversions and color scales. It offers similar functionalities to @ctrl/tinycolor but with additional features for generating color scales and working with color spaces more extensively.
The color package is another tool for color manipulation and conversion, supporting a wide range of color models. It is similar to @ctrl/tinycolor but differs in its API design and the way it handles color objects and conversions.
TinyColor is a small library for color manipulation and conversion
A fork of tinycolor2 by Brian Grinstead
sideEffectstinycolor is now exported as a class called TinyColorrandom, an implementation of randomColor by David Merfield that returns a TinyColor objectTinyColor.<function>
readability, fromRatio moved outrandom moved out and renamed to legacyRandomtoFilter has been moved out and renamed to toMsFiltermix, equals use the current TinyColor object as the first parametertint() and shade() tinycolor PR 159isValid, format are now propertys instead of a functionnpm install @ctrl/tinycolor
import { TinyColor } from '@ctrl/tinycolor';
const color = new TinyColor('red').toHexString(); // '#ff0000'
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:
new TinyColor('#000');
new TinyColor('000');
new TinyColor('#369C');
new TinyColor('369C');
new TinyColor('#f0f0f6');
new TinyColor('f0f0f6');
new TinyColor('#f0f0f688');
new TinyColor('f0f0f688');
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 });
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 });
import { fromRatio } from '@ctrl/tinycolor';
fromRatio({ h: 1, s: 0, l: 0 });
fromRatio({ h: 0.5, s: 0.5, l: 0.5 });
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 });
import { fromRatio } from '@ctrl/tinycolor';
fromRatio({ h: 1, s: 0, v: 0 });
fromRatio({ h: 0.5, s: 0.5, v: 0.5 });
new TinyColor('RED');
new TinyColor('blanchedalmond');
new TinyColor('darkblue');
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 }
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"
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"
Returns the input passed into the constructer used to create the tinycolor instance
const color = new TinyColor('red');
color.getOriginalInput(); // "red"
color = new TinyColor({ r: 255, g: 255, b: 255 });
color.getOriginalInput(); // "{r: 255, g: 255, b: 255}"
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
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
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
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
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
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)"
The following methods will return a property for the alpha value, which can be ignored: toHsv, toHsl, toRgb
const color = new TinyColor('red');
color.toHsv(); // { h: 0, s: 1, v: 1, a: 1 }
const color = new TinyColor('red');
color.toHsvString(); // "hsv(0, 100%, 100%)"
color.setAlpha(0.5);
color.toHsvString(); // "hsva(0, 100%, 100%, 0.5)"
const color = new TinyColor('red');
color.toHsl(); // { h: 0, s: 1, l: 0.5, a: 1 }
const color = new TinyColor('red');
color.toHslString(); // "hsl(0, 100%, 50%)"
color.setAlpha(0.5);
color.toHslString(); // "hsla(0, 100%, 50%, 0.5)"
const color = new TinyColor('red');
color.toHex(); // "ff0000"
const color = new TinyColor('red');
color.toHexString(); // "#ff0000"
const color = new TinyColor('red');
color.toHex8(); // "ff0000ff"
const color = new TinyColor('red');
color.toHex8String(); // "#ff0000ff"
const color = new TinyColor('red');
color.toRgb(); // { r: 255, g: 0, b: 0, a: 1 }
const color = new TinyColor('red');
color.toRgbString(); // "rgb(255, 0, 0)"
color.setAlpha(0.5);
color.toRgbString(); // "rgba(255, 0, 0, 0.5)"
const color = new TinyColor('red');
color.toPercentageRgb(); // { r: "100%", g: "0%", b: "0%", a: 1 }
const color = new TinyColor('red');
color.toPercentageRgbString(); // "rgb(100%, 0%, 0%)"
color.setAlpha(0.5);
color.toPercentageRgbString(); // "rgba(100%, 0%, 0%, 0.5)"
const color = new TinyColor('red');
color.toName(); // "red"
import { toMsFilter } from '@ctrl/tinycolor';
toMsFilter('red', 'blue'); // 'progid:DXImageTransform.Microsoft.gradient(startColorstr=#ffff0000,endColorstr=#ff0000ff)'
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('hsv'); // "hsv(0, 100%, 100%)"
const color2 = new TinyColor('rgb(255, 0, 0)');
color2.toString(); // "rgb(255, 0, 0)"
color2.setAlpha(0.5);
color2.toString(); // "rgba(255, 0, 0, 0.5)"
These methods manipulate the current color, and return it for chaining. For instance:
new TinyColor('red')
.lighten()
.desaturate()
.toHexString(); // '#f53d3d'
lighten: function(amount = 10) -> TinyColor. Lighten the color a given amount, from 0 to 100. Providing 100 will always return white.
new TinyColor('#f00').lighten().toString(); // '#ff3333'
new TinyColor('#f00').lighten(100).toString(); // '#ffffff'
brighten: function(amount = 10) -> TinyColor. Brighten the color a given amount, from 0 to 100.
new TinyColor('#f00').brighten().toString(); // '#ff1919'
darken: function(amount = 10) -> TinyColor. Darken the color a given amount, from 0 to 100. Providing 100 will always return black.
new TinyColor('#f00').darken().toString(); // '#cc0000'
new TinyColor('#f00').darken(100).toString(); // '#000000'
Mix the color with pure white, from 0 to 100. Providing 0 will do nothing, providing 100 will always return white.
new TinyColor('#f00').tint().toString(); // "#ff1a1a"
new TinyColor('#f00').tint(100).toString(); // "#ffffff"
Mix the color with pure black, from 0 to 100. Providing 0 will do nothing, providing 100 will always return black.
new TinyColor('#f00').shade().toString(); // "#e60000"
new TinyColor('#f00').shade(100).toString(); // "#000000"
desaturate: function(amount = 10) -> TinyColor. Desaturate the color a given amount, from 0 to 100. Providing 100 will is the same as calling greyscale.
new TinyColor('#f00').desaturate().toString(); // "#f20d0d"
new TinyColor('#f00').desaturate(100).toString(); // "#808080"
saturate: function(amount = 10) -> TinyColor. Saturate the color a given amount, from 0 to 100.
new TinyColor('hsl(0, 10%, 50%)').saturate().toString(); // "hsl(0, 20%, 50%)"
greyscale: function() -> TinyColor. Completely desaturates a color into greyscale. Same as calling desaturate(100).
new TinyColor('#f00').greyscale().toString(); // "#808080"
spin: function(amount = 0) -> TinyColor. Spin the hue a given amount, from -360 to 360. Calling with 0, 360, or -360 will do nothing (since it sets the hue back to what it was before).
new TinyColor('#f00').spin(180).toString(); // "#00ffff"
new TinyColor('#f00').spin(-90).toString(); // "#7f00ff"
new TinyColor('#f00').spin(90).toString(); // "#80ff00"
// spin(0) and spin(360) do nothing
new TinyColor('#f00').spin(0).toString(); // "#ff0000"
new TinyColor('#f00').spin(360).toString(); // "#ff0000"
mix: function(amount = 50) => TinyColor. Mix the current color a given amount with another color, from 0 to 100. 0 means no mixing (return current color).
let color1 = new TinyColor('#f0f');
let color2 = new TinyColor('#0f0');
color1.mix(color2).toHexString(); // #808080
Combination functions return an array of TinyColor objects unless otherwise noted.
analogous: function(results = 6, slices = 30) -> array<TinyColor>.
const colors = new TinyColor('#f00').analogous();
colors.map(t => t.toHexString()); // [ "#ff0000", "#ff0066", "#ff0033", "#ff0000", "#ff3300", "#ff6600" ]
monochromatic: function(, results = 6) -> array<TinyColor>.
const colors = new TinyColor('#f00').monochromatic();
colors.map(t => t.toHexString()); // [ "#ff0000", "#2a0000", "#550000", "#800000", "#aa0000", "#d40000" ]
splitcomplement: function() -> array<TinyColor>.
const colors = new TinyColor('#f00').splitcomplement();
colors.map(t => t.toHexString()); // [ "#ff0000", "#ccff00", "#0066ff" ]
triad: function() -> array<TinyColor>. Alias for polyad(3).
const colors = new TinyColor('#f00').triad();
colors.map(t => t.toHexString()); // [ "#ff0000", "#00ff00", "#0000ff" ]
tetrad: function() -> array<TinyColor>. Alias for polyad(4).
const colors = new TinyColor('#f00').tetrad();
colors.map(t => t.toHexString()); // [ "#ff0000", "#80ff00", "#00ffff", "#7f00ff" ]
polyad: function(number) -> array<TinyColor>.
const colors = new TinyColor('#f00').polyad(4);
colors.map(t => t.toHexString()); // [ "#ff0000", "#80ff00", "#00ffff", "#7f00ff" ]
complement: function() -> TinyColor.
new TinyColor('#f00').complement().toHexString(); // "#00ffff"
let color1 = new TinyColor('red');
let color2 = new TinyColor('#f00');
color1.equals(color2); // true
Returns a random TinyColor object. This is an implementation of randomColor by David Merfield. The difference input parsing and output formatting are handled by TinyColor.
You can pass an options object to influence the type of color it produces. The options object accepts the following properties:
hue – Controls the hue of the generated color. You can pass a string representing a color name: red, orange, yellow, green, blue, purple, pink and monochrome are currently supported. If you pass a hexidecimal color string such as #00FFFF, its hue value will be extracted and use that to generate colors.
luminosity – Controls the luminosity of the generated color. You can specify a string containing bright, light or dark.
count – An integer which specifies the number of colors to generate.
seed - An integer or string which when passed will cause randomColor to return the same color each time.
alpha – A decimal between 0 and 1. Only relevant when using a format with an alpha channel (rgba and hsla). Defaults to a random value.
import { random } from '@ctrl/tinycolor';
// Returns a TinyColor for an attractive color
random();
// Returns an array of ten green colors
random({
count: 10,
hue: 'green',
});
// Returns a TinyColor object in a light blue
random({
luminosity: 'light',
hue: 'blue',
});
// Returns a TinyColor object in a 'truly random' color
random({
luminosity: 'random',
hue: 'random',
});
// Returns a dark RGB color with specified alpha
random({
luminosity: 'dark',
alpha: 0.5,
});
TinyColor assesses readability based on the Web Content Accessibility Guidelines (Version 2.0).
readability: function(TinyColor, TinyColor) -> Object.
Returns the contrast ratio between two colors.
import { readability } from '@ctrl/tinycolor';
readability('#000', '#000'); // 1
readability('#000', '#111'); // 1.1121078324840545
readability('#000', '#fff'); // 21
Use the values in your own calculations, or use one of the convenience functions below.
isReadable: function(TinyColor, TinyColor, Object) -> Boolean. Ensure that foreground and background color combinations meet WCAG guidelines. Object is optional, defaulting to {level: "AA",size: "small"}. level can be "AA" or "AAA" and size can be "small" or "large".
Here are links to read more about the AA and AAA requirements.
import { isReadable } from '@ctrl/tinycolor';
isReadable("#000", "#111"); // false
isReadable("#ff0088", "#5c1a72", { level: "AA", size: "small" }); // false
isReadable("#ff0088", "#5c1a72", { level: "AA", size: "large" }), // true
mostReadable: function(TinyColor, [TinyColor, TinyColor ...], Object) -> Boolean.
Given a base color and a list of possible foreground or background colors for that base, returns the most readable color.
If none of the colors in the list is readable, mostReadable will return the better of black or white if includeFallbackColors:true.
import { mostReadable } from '@ctrl/tinycolor';
mostReadable('#000', ['#f00', '#0f0', '#00f']).toHexString(); // "#00ff00"
mostReadable('#123', ['#124', '#125'], { includeFallbackColors: false }).toHexString(); // "#112255"
mostReadable('#123', ['#124', '#125'], { includeFallbackColors: true }).toHexString(); // "#ffffff"
mostReadable('#ff0088', ['#2e0c3a'], {
includeFallbackColors: true,
level: 'AAA',
size: 'large',
}).toHexString(); // "#2e0c3a",
mostReadable('#ff0088', ['#2e0c3a'], {
includeFallbackColors: true,
level: 'AAA',
size: 'small',
}).toHexString(); // "#000000",
See index.html in the project for a demo.
clone: function() -> TinyColor.
Instantiate a new TinyColor object with the same color. Any changes to the new one won't affect the old one.
const color1 = new TinyColor('#F00');
const color2 = color1.clone();
color2.setAlpha(0.5);
color1.toString(); // "#ff0000"
color2.toString(); // "rgba(255, 0, 0, 0.5)"
FAQs
Fast, small color manipulation and conversion for JavaScript
The npm package @ctrl/tinycolor receives a total of 1,317,495 weekly downloads. As such, @ctrl/tinycolor popularity was classified as popular.
We found that @ctrl/tinycolor demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.