1# TinyColor 2 3## JavaScript color tooling 4 5TinyColor is a small, fast library for color manipulation and conversion in JavaScript. It allows many forms of input, while providing color conversions and other color utility functions. It has no dependencies. 6 7[![Build Status](https://travis-ci.org/bgrins/TinyColor.png?branch=master)](https://travis-ci.org/bgrins/TinyColor) 8 9## Including in a browser 10 11Download [tinycolor.js](https://raw.githubusercontent.com/bgrins/TinyColor/master/tinycolor.js) or install it with bower: 12 13 bower install tinycolor 14 15Then just include it in the page in a `script` tag: 16```html 17<script type='text/javascript' src='tinycolor.js'></script> 18<script type='text/javascript'> 19var color = tinycolor("red"); 20</script> 21``` 22## Including in node 23 24`tinycolor` may also be included as a [node](http://nodejs.org/) module like so: 25 26 npm install tinycolor2 27 28Then it can be used in your script like so: 29```js 30var tinycolor = require("tinycolor2"); 31var color = tinycolor("red"); 32``` 33## Usage 34 35Call `tinycolor(input)` or `new tinycolor(input)`, and you will have an object with the following properties. See Accepted String Input and Accepted Object Input below for more information about what is accepted. 36 37## Accepted String Input 38 39The 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). 40 41HSL 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. 42 43RGB input requires either 0-255 or 0%-100%. 44 45If you call `tinycolor.fromRatio`, RGB and Hue input can also accept 0-1. 46 47Here are some examples of string input: 48 49### Hex, 8-digit (RGBA) Hex 50```js 51tinycolor("#000"); 52tinycolor("000"); 53tinycolor("#369C"); 54tinycolor("369C"); 55tinycolor("#f0f0f6"); 56tinycolor("f0f0f6"); 57tinycolor("#f0f0f688"); 58tinycolor("f0f0f688"); 59``` 60### RGB, RGBA 61```js 62tinycolor("rgb (255, 0, 0)"); 63tinycolor("rgb 255 0 0"); 64tinycolor("rgba (255, 0, 0, .5)"); 65tinycolor({ r: 255, g: 0, b: 0 }); 66tinycolor.fromRatio({ r: 1, g: 0, b: 0 }); 67tinycolor.fromRatio({ r: .5, g: .5, b: .5 }); 68``` 69### HSL, HSLA 70```js 71tinycolor("hsl(0, 100%, 50%)"); 72tinycolor("hsla(0, 100%, 50%, .5)"); 73tinycolor("hsl(0, 100%, 50%)"); 74tinycolor("hsl 0 1.0 0.5"); 75tinycolor({ h: 0, s: 1, l: .5 }); 76tinycolor.fromRatio({ h: 1, s: 0, l: 0 }); 77tinycolor.fromRatio({ h: .5, s: .5, l: .5 }); 78``` 79### HSV, HSVA 80```js 81tinycolor("hsv(0, 100%, 100%)"); 82tinycolor("hsva(0, 100%, 100%, .5)"); 83tinycolor("hsv (0 100% 100%)"); 84tinycolor("hsv 0 1 1"); 85tinycolor({ h: 0, s: 100, v: 100 }); 86tinycolor.fromRatio({ h: 1, s: 0, v: 0 }); 87tinycolor.fromRatio({ h: .5, s: .5, v: .5 }); 88``` 89### Named 90```js 91tinycolor("RED"); 92tinycolor("blanchedalmond"); 93tinycolor("darkblue"); 94``` 95### Accepted Object Input 96 97If 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: 98 99 { r: 255, g: 0, b: 0 } 100 { r: 255, g: 0, b: 0, a: .5 } 101 { h: 0, s: 100, l: 50 } 102 { h: 0, s: 100, v: 100 } 103 104## Methods 105 106### getFormat 107 108Returns the format used to create the tinycolor instance 109```js 110var color = tinycolor("red"); 111color.getFormat(); // "name" 112color = tinycolor({r:255, g:255, b:255}); 113color.getFormat(); // "rgb" 114``` 115 116### getOriginalInput 117 118Returns the input passed into the constructer used to create the tinycolor instance 119```js 120var color = tinycolor("red"); 121color.getOriginalInput(); // "red" 122color = tinycolor({r:255, g:255, b:255}); 123color.getOriginalInput(); // "{r: 255, g: 255, b: 255}" 124``` 125 126### isValid 127 128Return 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. 129```js 130var color1 = tinycolor("red"); 131color1.isValid(); // true 132color1.toHexString(); // "#ff0000" 133 134var color2 = tinycolor("not a color"); 135color2.isValid(); // false 136color2.toString(); // "#000000" 137``` 138### getBrightness 139 140Returns the perceived brightness of a color, from `0-255`, as defined by [Web Content Accessibility Guidelines (Version 1.0)](http://www.w3.org/TR/AERT#color-contrast). 141```js 142var color1 = tinycolor("#fff"); 143color1.getBrightness(); // 255 144 145var color2 = tinycolor("#000"); 146color2.getBrightness(); // 0 147``` 148### isLight 149 150Return a boolean indicating whether the color's perceived brightness is light. 151```js 152var color1 = tinycolor("#fff"); 153color1.isLight(); // true 154 155var color2 = tinycolor("#000"); 156color2.isLight(); // false 157``` 158### isDark 159 160Return a boolean indicating whether the color's perceived brightness is dark. 161```js 162var color1 = tinycolor("#fff"); 163color1.isDark(); // false 164 165var color2 = tinycolor("#000"); 166color2.isDark(); // true 167``` 168### getLuminance 169 170Returns the perceived luminance of a color, from `0-1` as defined by [Web Content Accessibility Guidelines (Version 2.0).](http://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef) 171```js 172var color1 = tinycolor("#fff"); 173color1.getLuminance(); // 1 174 175var color2 = tinycolor("#000"); 176color2.getLuminance(); // 0 177``` 178### getAlpha 179 180Returns the alpha value of a color, from `0-1`. 181```js 182var color1 = tinycolor("rgba(255, 0, 0, .5)"); 183color1.getAlpha(); // 0.5 184 185var color2 = tinycolor("rgb(255, 0, 0)"); 186color2.getAlpha(); // 1 187 188var color3 = tinycolor("transparent"); 189color3.getAlpha(); // 0 190``` 191### setAlpha 192 193Sets the alpha value on a current color. Accepted range is in between `0-1`. 194```js 195var color = tinycolor("red"); 196color.getAlpha(); // 1 197color.setAlpha(.5); 198color.getAlpha(); // .5 199color.toRgbString(); // "rgba(255, 0, 0, .5)" 200``` 201### String Representations 202 203The following methods will return a property for the `alpha` value, which can be ignored: `toHsv`, `toHsl`, `toRgb` 204 205### toHsv 206```js 207var color = tinycolor("red"); 208color.toHsv(); // { h: 0, s: 1, v: 1, a: 1 } 209``` 210### toHsvString 211```js 212var color = tinycolor("red"); 213color.toHsvString(); // "hsv(0, 100%, 100%)" 214color.setAlpha(0.5); 215color.toHsvString(); // "hsva(0, 100%, 100%, 0.5)" 216``` 217### toHsl 218```js 219var color = tinycolor("red"); 220color.toHsl(); // { h: 0, s: 1, l: 0.5, a: 1 } 221``` 222### toHslString 223```js 224var color = tinycolor("red"); 225color.toHslString(); // "hsl(0, 100%, 50%)" 226color.setAlpha(0.5); 227color.toHslString(); // "hsla(0, 100%, 50%, 0.5)" 228``` 229### toHex 230```js 231var color = tinycolor("red"); 232color.toHex(); // "ff0000" 233``` 234### toHexString 235```js 236var color = tinycolor("red"); 237color.toHexString(); // "#ff0000" 238``` 239### toHex8 240```js 241var color = tinycolor("red"); 242color.toHex8(); // "ff0000ff" 243``` 244### toHex8String 245```js 246var color = tinycolor("red"); 247color.toHex8String(); // "#ff0000ff" 248``` 249### toRgb 250```js 251var color = tinycolor("red"); 252color.toRgb(); // { r: 255, g: 0, b: 0, a: 1 } 253``` 254### toRgbString 255```js 256var color = tinycolor("red"); 257color.toRgbString(); // "rgb(255, 0, 0)" 258color.setAlpha(0.5); 259color.toRgbString(); // "rgba(255, 0, 0, 0.5)" 260``` 261### toPercentageRgb 262```js 263var color = tinycolor("red"); 264color.toPercentageRgb() // { r: "100%", g: "0%", b: "0%", a: 1 } 265``` 266### toPercentageRgbString 267```js 268var color = tinycolor("red"); 269color.toPercentageRgbString(); // "rgb(100%, 0%, 0%)" 270color.setAlpha(0.5); 271color.toPercentageRgbString(); // "rgba(100%, 0%, 0%, 0.5)" 272``` 273### toName 274```js 275var color = tinycolor("red"); 276color.toName(); // "red" 277``` 278### toFilter 279``` 280var color = tinycolor("red"); 281color.toFilter(); // "progid:DXImageTransform.Microsoft.gradient(startColorstr=#ffff0000,endColorstr=#ffff0000)" 282``` 283### toString 284 285Print 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. 286```js 287var color1 = tinycolor("red"); 288color1.toString(); // "red" 289color1.toString("hsv"); // "hsv(0, 100%, 100%)" 290 291var color2 = tinycolor("rgb(255, 0, 0)"); 292color2.toString(); // "rgb(255, 0, 0)" 293color2.setAlpha(.5); 294color2.toString(); // "rgba(255, 0, 0, 0.5)" 295``` 296### Color Modification 297 298These methods manipulate the current color, and return it for chaining. For instance: 299```js 300tinycolor("red").lighten().desaturate().toHexString() // "#f53d3d" 301``` 302### lighten 303 304`lighten: function(amount = 10) -> TinyColor`. Lighten the color a given amount, from 0 to 100. Providing 100 will always return white. 305```js 306tinycolor("#f00").lighten().toString(); // "#ff3333" 307tinycolor("#f00").lighten(100).toString(); // "#ffffff" 308``` 309### brighten 310 311`brighten: function(amount = 10) -> TinyColor`. Brighten the color a given amount, from 0 to 100. 312```js 313tinycolor("#f00").brighten().toString(); // "#ff1919" 314``` 315### darken 316 317`darken: function(amount = 10) -> TinyColor`. Darken the color a given amount, from 0 to 100. Providing 100 will always return black. 318```js 319tinycolor("#f00").darken().toString(); // "#cc0000" 320tinycolor("#f00").darken(100).toString(); // "#000000" 321``` 322### desaturate 323 324`desaturate: function(amount = 10) -> TinyColor`. Desaturate the color a given amount, from 0 to 100. Providing 100 will is the same as calling `greyscale`. 325```js 326tinycolor("#f00").desaturate().toString(); // "#f20d0d" 327tinycolor("#f00").desaturate(100).toString(); // "#808080" 328``` 329### saturate 330 331`saturate: function(amount = 10) -> TinyColor`. Saturate the color a given amount, from 0 to 100. 332```js 333tinycolor("hsl(0, 10%, 50%)").saturate().toString(); // "hsl(0, 20%, 50%)" 334``` 335### greyscale 336 337`greyscale: function() -> TinyColor`. Completely desaturates a color into greyscale. Same as calling `desaturate(100)`. 338```js 339tinycolor("#f00").greyscale().toString(); // "#808080" 340``` 341### spin 342 343`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). 344```js 345tinycolor("#f00").spin(180).toString(); // "#00ffff" 346tinycolor("#f00").spin(-90).toString(); // "#7f00ff" 347tinycolor("#f00").spin(90).toString(); // "#80ff00" 348 349// spin(0) and spin(360) do nothing 350tinycolor("#f00").spin(0).toString(); // "#ff0000" 351tinycolor("#f00").spin(360).toString(); // "#ff0000" 352``` 353### Color Combinations 354 355Combination functions return an array of TinyColor objects unless otherwise noted. 356 357### analogous 358 359`analogous: function(, results = 6, slices = 30) -> array<TinyColor>`. 360```js 361var colors = tinycolor("#f00").analogous(); 362 363colors.map(function(t) { return t.toHexString(); }); // [ "#ff0000", "#ff0066", "#ff0033", "#ff0000", "#ff3300", "#ff6600" ] 364``` 365### monochromatic 366 367`monochromatic: function(, results = 6) -> array<TinyColor>`. 368```js 369var colors = tinycolor("#f00").monochromatic(); 370 371colors.map(function(t) { return t.toHexString(); }); // [ "#ff0000", "#2a0000", "#550000", "#800000", "#aa0000", "#d40000" ] 372``` 373### splitcomplement 374 375`splitcomplement: function() -> array<TinyColor>`. 376```js 377var colors = tinycolor("#f00").splitcomplement(); 378 379colors.map(function(t) { return t.toHexString(); }); // [ "#ff0000", "#ccff00", "#0066ff" ] 380``` 381### triad 382 383`triad: function() -> array<TinyColor>`. 384```js 385var colors = tinycolor("#f00").triad(); 386 387colors.map(function(t) { return t.toHexString(); }); // [ "#ff0000", "#00ff00", "#0000ff" ] 388``` 389### tetrad 390 391`tetrad: function() -> array<TinyColor>`. 392```js 393var colors = tinycolor("#f00").tetrad(); 394 395colors.map(function(t) { return t.toHexString(); }); // [ "#ff0000", "#80ff00", "#00ffff", "#7f00ff" ] 396 397``` 398### complement 399 400`complement: function() -> TinyColor`. 401```js 402tinycolor("#f00").complement().toHexString(); // "#00ffff" 403``` 404## Color Utilities 405```js 406tinycolor.equals(color1, color2) 407tinycolor.mix(color1, color2, amount = 50) 408``` 409### random 410 411Returns a random color. 412```js 413var color = tinycolor.random(); 414color.toRgb(); // "{r: 145, g: 40, b: 198, a: 1}" 415``` 416 417### Readability 418 419TinyColor assesses readability based on the [Web Content Accessibility Guidelines (Version 2.0)](http://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef). 420 421#### readability 422 423`readability: function(TinyColor, TinyColor) -> Object`. 424Returns the contrast ratio between two colors. 425```js 426tinycolor.readability("#000", "#000"); // 1 427tinycolor.readability("#000", "#111"); // 1.1121078324840545 428tinycolor.readability("#000", "#fff"); // 21 429``` 430Use the values in your own calculations, or use one of the convenience functions below. 431 432#### isReadable 433 434`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"`. 435 436Here are links to read more about the [AA](http://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) and [AAA](http://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast7.html) requirements. 437```js 438tinycolor.isReadable("#000", "#111", {}); // false 439tinycolor.isReadable("#ff0088", "#5c1a72",{level:"AA",size:"small"}); //false 440tinycolor.isReadable("#ff0088", "#5c1a72",{level:"AA",size:"large"}), //true 441``` 442#### mostReadable 443 444`mostReadable: function(TinyColor, [TinyColor, Tinycolor ...], Object) -> Boolean`. 445Given a base color and a list of possible foreground or background colors for that base, returns the most readable color. 446If none of the colors in the list is readable, `mostReadable` will return the better of black or white if `includeFallbackColors:true`. 447```js 448tinycolor.mostReadable("#000", ["#f00", "#0f0", "#00f"]).toHexString(); // "#00ff00" 449tinycolor.mostReadable(tinycolor.mostReadable("#123", ["#124", "#125"],{includeFallbackColors:false}).toHexString(); // "#112255" 450tinycolor.mostReadable(tinycolor.mostReadable("#123", ["#124", "#125"],{includeFallbackColors:true}).toHexString(); // "#ffffff" 451tinycolor.mostReadable("#ff0088", ["#2e0c3a"],{includeFallbackColors:true,level:"AAA",size:"large"}).toHexString() // "#2e0c3a", 452tinycolor.mostReadable("#ff0088", ["#2e0c3a"],{includeFallbackColors:true,level:"AAA",size:"small"}).toHexString() // "#000000", 453``` 454See [index.html](https://github.com/bgrins/TinyColor/blob/master/index.html) in the project for a demo. 455 456## Common operations 457 458### clone 459 460`clone: function() -> TinyColor`. 461Instantiate a new TinyColor object with the same color. Any changes to the new one won't affect the old one. 462```js 463var color1 = tinycolor("#F00"); 464var color2 = color1.clone(); 465color2.setAlpha(.5); 466 467color1.toString(); // "#ff0000" 468color2.toString(); // "rgba(255, 0, 0, 0.5)" 469``` 470