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