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