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 17 <script type='text/javascript' src='tinycolor.js'></script> 18 <script type='text/javascript'> 19 var 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 30 var tinycolor = require("./tinycolor"); 31 var 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. 42 43RGB input requires either 0-255 or 0%-100%. 44 45If you call `tinycolor.fromRatio`, RGB input can also accept 0-1 46Here are some examples of string input: 47 48### Hex, 8-digit (ARGB) Hex 49 50 tinycolor("#000"); 51 tinycolor("000"); 52 tinycolor("#f0f0f6"); 53 tinycolor("f0f0f6"); 54 tinycolor("#88f0f0f6"); 55 tinycolor("88f0f0f6"); 56 57### RGB, RGBA 58 59 tinycolor("rgb (255, 0, 0)"); 60 tinycolor("rgb 255 0 0"); 61 tinycolor("rgba (255, 0, 0, .5)"); 62 tinycolor({ r: 255, g: 0, b: 0 }); 63 tinycolor.fromRatio({ r: 1, g: 0, b: 0 }); 64 tinycolor.fromRatio({ r: .5, g: .5, b: .5 }); 65 66### HSL, HSLA 67 68 tinycolor("hsl(0, 100%, 50%)"); 69 tinycolor("hsla(0, 100%, 50%, .5)"); 70 tinycolor("hsl(0, 100%, 50%)"); 71 tinycolor("hsl 0 1.0 0.5"); 72 tinycolor({ h: 0, s: 1, l: .5 }); 73 74### HSV, HSVA 75 76 tinycolor("hsv(0, 100%, 100%)"); 77 tinycolor("hsva(0, 100%, 100%, .5)"); 78 tinycolor("hsv (0 100% 100%)"); 79 tinycolor("hsv 0 1 1"); 80 tinycolor({ h: 0, s: 100, v: 100 }); 81 82### Named 83 84 tinycolor("RED"); 85 tinycolor("blanchedalmond"); 86 tinycolor("darkblue"); 87 88### Accepted Object Input 89 90If 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: 91 92 { r: 255, g: 0, b: 0 } 93 { r: 255, g: 0, b: 0, a: .5 } 94 { h: 0, s: 100, l: 50 } 95 { h: 0, s: 100, v: 100 } 96 97## Methods 98 99### isValid 100 101Return 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. 102 103 var color1 = tinycolor("red"); 104 color1.isValid(); // true 105 color1.toHexString(); // "#ff0000" 106 107 var color2 = tinycolor("not a color"); 108 color2.isValid(); // false 109 color2.toString(); // "#000000" 110 111### isLight 112 113Return a boolean indicating whether the color's perceived brightness is light. 114 115 var color1 = tinycolor("#fff"); 116 color1.isLight(); // true 117 118 var color2 = tinycolor("#000"); 119 color2.isLight(); // false 120 121### isDark 122 123Return a boolean indicating whether the color's perceived brightness is dark. 124 125 var color1 = tinycolor("#fff"); 126 color1.isDark(); // false 127 128 var color2 = tinycolor("#000"); 129 color2.isDark(); // true 130 131### getAlpha 132 133Returns the alpha value of a color, from `0-1`. 134 135 var color1 = tinycolor("rgba(255, 0, 0, .5)"); 136 color1.getAlpha(); // 0.5 137 138 var color2 = tinycolor("rgb(255, 0, 0)"); 139 color2.getAlpha(); // 1 140 141 var color3 = tinycolor("transparent"); 142 color3.getAlpha(); // 0 143 144### getBrightness 145 146Returns the perceived brightness of a color, from `0-255`. 147 148 var color1 = tinycolor("#fff"); 149 color1.getBrightness(); // 255 150 151 var color2 = tinycolor("#000"); 152 color2.getBrightness(); // 0 153 154### setAlpha 155 156Sets the alpha value on a current color. Accepted range is in between `0-1`. 157 158 var color = tinycolor("red"); 159 color.getAlpha(); // 1 160 color.setAlpha(.5); 161 color.getAlpha(); // .5 162 color.toRgbString(); // "rgba(255, 0, 0, .5)" 163 164### toHsv 165 166 var color = tinycolor("red"); 167 color.toHsv(); // { h: 0, s: 1, v: 1, a: 1 } 168 169### toHsvString 170 171 var color = tinycolor("red"); 172 color.toHsvString(); // "hsv(0, 100%, 100%)" 173 174### toHsl 175 176 var color = tinycolor("red"); 177 color.toHsl(); // { h: 0, s: 1, l: 0.5, a: 1 } 178 179### toHslString 180 181 var color = tinycolor("red"); 182 color.toHslString(); // "hsl(0, 100%, 50%)" 183 184### toHex 185 186 var color = tinycolor("red"); 187 color.toHex(); // "ff0000" 188 189### toHexString 190 191 var color = tinycolor("red"); 192 color.toHexString(); // "#ff0000" 193 194### toHex8 195 196 var color = tinycolor("red"); 197 color.toHex8(); // "ffff0000" 198 199### toHex8String 200 201 var color = tinycolor("red"); 202 color.toHex8String(); // "#ffff0000" 203 204### toRgb 205 206 var color = tinycolor("red"); 207 color.toRgb(); // { r: 255, g: 0, b: 0, a: 1 } 208 209### toRgbString 210 211 var color = tinycolor("red"); 212 color.toRgbString(); // "rgb(255, 0, 0)" 213 214### toPercentageRgb 215 216 var color = tinycolor("red"); 217 color.toPercentageRgb() // { r: "100%", g: "0%", b: "0%", a: 1 } 218 219### toPercentageRgbString 220 221 var color = tinycolor("red"); 222 color.toPercentageRgbString(); // "rgb(100%, 0%, 0%)" 223 224### toName 225 226 var color = tinycolor("red"); 227 color.toName(); // "red" 228 229### toFilter 230 231 var color = tinycolor("red"); 232 color.toFilter(); // "progid:DXImageTransform.Microsoft.gradient(startColorstr=#ffff0000,endColorstr=#ffff0000)" 233 234### toString 235 236Print 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. 237 238 var color1 = tinycolor("red"); 239 color1.toString(); // "red" 240 color1.toString("hsv"); // ""hsv(0, 100%, 100%)" 241 242 var color2 = tinycolor("rgb(255, 0, 0)"); 243 color2.toString(); // "rgb(255, 0, 0)" 244 color2.setAlpha(.5); 245 color2.toString(); // "rgba(255, 0, 0, 0.5)" 246 247### Color Modification 248 249These methods manipulate the current color, and return it for chaining. For instance: 250 251 tinycolor("red").lighten().desaturate().toHexString() // "#f53d3d" 252 253### lighten 254 255`lighten: function(amount = 10) -> TinyColor`. Lighten the color a given amount, from 0 to 100. Providing 100 will always return white. 256 257 tinycolor("#f00").lighten().toString(); // "#ff3333" 258 tinycolor("#f00").lighten(100).toString(); // "#ffffff" 259 260### brighten 261 262`brighten: function(amount = 10) -> TinyColor`. Brighten the color a given amount, from 0 to 100. 263 264 tinycolor("#f00").brighten().toString(); // "#ff1919" 265 266### darken 267 268`darken: function(amount = 10) -> TinyColor`. Darken the color a given amount, from 0 to 100. Providing 100 will always return black. 269 270 tinycolor("#f00").darken().toString(); // "#cc0000" 271 tinycolor("#f00").darken(100).toString(); // "#000000" 272 273### desaturate 274 275`desaturate: function(amount = 10) -> TinyColor`. Desaturate the color a given amount, from 0 to 100. Providing 100 will is the same as calling `greyscale`. 276 277 tinycolor("#f00").desaturate().toString(); // "#f20d0d" 278 tinycolor("#f00").desaturate(100).toString(); // "#808080" 279 280### saturate 281 282`saturate: function(amount = 10) -> TinyColor`. Saturate the color a given amount, from 0 to 100. 283 284 tinycolor("hsl(0, 10%, 50%)").saturate().toString(); // "hsl(0, 20%, 50%)" 285 286### greyscale 287 288`greyscale: function() -> TinyColor`. Completely desaturates a color into greyscale. Same as calling `desaturate(100)`. 289 290 tinycolor("#f00").greyscale().toString(); // "#808080" 291 292### spin 293 294`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). 295 296 tinycolor("#f00").spin(180).toString(); // "#00ffff" 297 tinycolor("#f00").spin(-90).toString(); // "#7f00ff" 298 tinycolor("#f00").spin(90).toString(); // "#80ff00" 299 300 // spin(0) and spin(360) do nothing 301 tinycolor("#f00").spin(0).toString(); // "#ff0000" 302 tinycolor("#f00").spin(360).toString(); // "#ff0000" 303 304### Color Combinations 305 306Combination functions return an array of TinyColor objects unless otherwise noted. 307 308### analogous 309 310`analogous: function(, results = 6, slices = 30) -> array<TinyColor>`. 311 312 var colors = tinycolor("#f00").analogous(); 313 314 colors.map(function(t) { return t.toHexString(); }); // [ "#ff0000", "#ff0066", "#ff0033", "#ff0000", "#ff3300", "#ff6600" ] 315 316### monochromatic 317 318`monochromatic: function(, results = 6) -> array<TinyColor>`. 319 320 var colors = tinycolor("#f00").monochromatic(); 321 322 colors.map(function(t) { return t.toHexString(); }); // [ "#ff0000", "#2a0000", "#550000", "#800000", "#aa0000", "#d40000" ] 323 324### splitcomplement 325 326`splitcomplement: function() -> array<TinyColor>`. 327 328 var colors = tinycolor("#f00").splitcomplement(); 329 330 colors.map(function(t) { return t.toHexString(); }); // [ "#ff0000", "#ccff00", "#0066ff" ] 331 332### triad 333 334`triad: function() -> array<TinyColor>`. 335 336 var colors = tinycolor("#f00").triad(); 337 338 colors.map(function(t) { return t.toHexString(); }); // [ "#ff0000", "#00ff00", "#0000ff" ] 339 340### tetrad 341 342`tetrad: function() -> array<TinyColor>`. 343 344 var colors = tinycolor("#f00").tetrad(); 345 346 colors.map(function(t) { return t.toHexString(); }); // [ "#ff0000", "#80ff00", "#00ffff", "#7f00ff" ] 347 348 349### complement 350 351`complement: function() -> TinyColor`. 352 353 tinycolor("#f00").complement().toHexString(); // "#00ffff" 354 355## Color Utilities 356 357 tinycolor.equals(color1, color2) 358 tinycolor.mix(color1, color2, amount = 50) 359 360### readability 361 362`readable: function(TinyColor, TinyColor) -> Object`. Analyze 2 colors and returns an object with the following properties. `brightness` is difference in brightness between the two colors. `color`: difference in color/hue between the two colors. 363 364 tinycolor.readability("#000", "#111"); // {brightness: 17, color: 51} 365 tinycolor.readability("#000", "#fff"); // {brightness: 255, color: 765} 366 367### isReadable 368 369`isReadable: function(TinyColor, TinyColor) -> Boolean`. Ensure that foreground and background color combinations provide sufficient contrast. 370 371 tinycolor.isReadable("#000", "#111"); // false 372 373### mostReadable 374 375Given a base color and a list of possible foreground or background colors for that base, returns the most readable color. 376 377 tinycolor.mostReadable("#000", ["#f00", "#0f0", "#00f"]).toHexString(); // "#00ff00" 378 379See [index.html](https://github.com/bgrins/TinyColor/blob/master/index.html) in the project for a demo. 380