taksim-coco v0.1.3
coco
coco is a fast and lightweight javascript library that focuses on color conversions between hex, rgb, hsl and hsv formats. It has no dependencies and you can use it both client and server side to handle different color syntaxes easily. It's also ready for 8 digit hex notation of CSS4, but the requirements and definition of this feature are in editor's draft status which will be updated frequently. So don't use hex8/hex4 notation in production until things get more clear.
Installation
Server
Install it as a node module via npm.
npm install taksim-coco --save
and include in a file;
var coco = require('taksim-coco');
Client
You can pull down coco using Bower
bower install taksim-coco --save
or just download the latest minified version and include in your document.
<script type='text/javascript' src='taksim-coco.min.js'></script>
Usage
coco(color:string, format:string)
- color should have a valid syntax.
#f00
or#ff0000
rgb(255, 0, 0)
hsl(0, 100%, 50%)
hsv(0, 100%, 100%)
- format should be one of the supported types;
name, hex, hex3, hex6, hex4, hex8, rgb, hsl, hsv
name
refers to the x11 colors.hex4, hex8
is only available if you call coco.supportHex8() explicitly.
coco('#f00', 'name')
=> 'red'
coco('#f00', 'hex6')
=> '#ff0000'
coco('#ff0000', 'hex3')
=> '#f00'
coco('#ff0000', 'rgb')
=> 'rgb(255, 0, 0)'
coco('rgba(255, 0, 0, 0.5)', 'hsl')
=> 'hsla(0, 100%, 50%, 0.5)'
// Hex format returns hex3 representation if available.
coco('rgba(255, 0, 0, 0.5)', 'hex')
=> '#f00'
coco('rgba(255, 10, 50, 0.5)', 'hex')
=> '#ff6432'
// If input color is not defined in x11 colors, it will be converted to hex.
coco('rgba(255, 10, 50, 0.5)', 'name')
=> '#ff6432'
// Alpha is removed automatically when it is equal to 1
coco('hsla(0, 100%, 50%, 1)', 'hsv')
=> 'hsv(0, 100%, 100%)'
// Any invalid color string returns the representation of black in the requested format.
coco('f00', 'hsl')
=> 'hsl(0, 0%, 0%)'
coco('(255, 0, 0)', 'hex')
=> '#000'
// If the format is unknown, input color string will return as it is.
coco('rgb(255, 0, 0)', 'rgba')
=> 'rgb(255, 0, 0)'
coco('red', 'cmyk')
=> 'red'
Conversion Methods
There are plenty of specific conversion methods attached to coco() function and they don't require a valid syntax unlike coco(). The naming of these methods follows a simple convention: inputFormat2outputFormat, e.g. coco.rgb2hsl
or coco.name2hex
. So, we can commonize some of the rules;
- All 2rgb (except percentage2rgb()), 2hsl and 2hsv methods return a color array like
[255, 0, 0, 1]
coco.hex2rgb('#f00')
=> [255, 0, 0, 1]
coco.rgb2hsl('rgba(255, 0, 0, 0.5)')
=> [0, 100, 50, 0.5]
- All rgb2, hsl2 and hsv2 methods accept a string or an array.
coco.rgb2hex([255, 0, 0, 1])
=> '#f00'
coco.rgb2hex('rgba(255, 0, 0, 0.5)')
=> '#f00'
- All 2hex and 2name methods return a string.
coco.hsv2hex([0, 100, 100)
=> '#f00'
coco.rgb2name('rgb(255, 0, 0)')
=> 'red'
- All hex2 and name2 methods accept a string.
coco.hex2name('#f00')
=> 'red'
coco.name2rgb('red')
=> [255, 0, 0, 1]
// Because hex2hex6 and hex2hex3 are misleading method names,
// I prefer to use hex2Short and hex2Long.
coco.hex2Long('#f00')
=> '#ff0000'
coco.hex2Short('#ff0000')
=> '#f00'
- The conversion methods don't expect a valid color string, which means that they should return (most of the time) the correct result even if the input string has a typo.
coco.hex2name('f00')
=> 'red'
coco.rgb2hsl('rg(255, 0, 0, 0.5)')
=> [0, 100, 50, 0.5]
coco.rgb2hsl('255,0,0,.5')
=> [0, 100, 50, 0.5]
coco.rgb2hex('255')
=> '#f00'
coco.rgb2hex('255, 255')
=> '#ff0'
coco.percentage2rgb()
is a helper method that allows coco to cover percentage based rgb colors.
// If we directly pass a percentage based rgb color to a conversion method,
// it will be evaluated as it contains reqular rgb values.
coco.rgb2hex('rgb(100%, 0%, 0%)')
=> '#640000'
// To get the correct result, first convert it to regular rgb string.
var rgbStr = coco.percentage2rgb('rgb(100%, 0%, 0%)');
=> 'rgb(255, 0, 0)'
coco.rgb2hex(rgbStr)
=> '#ff0'
All conversion methods are as follows;
rgb2hex, hsl2hex, hsv2hex, name2hex, hex2Short, hex2Long
hex2rgb, hsl2rgb, hsv2rgb, name2rgb
hex2hsl, rgb2hsl, hsv2hsl, name2hsl
hex2hsv, hsl2hsv, rgb2hsv, name2hsv
hex2name, rgb2name, hsl2name, hsv2name
Hue Conversions
By passing a hue angle between 0 and 360 to one the following converters, you can get the hue color.
coco.hue2name(120)
=> 'lime'
coco.hue2hex(120)
=> '#0f0'
coco.hue2rgb(120)
=> [0, 255, 0, 1]
coco.hue2hsl(120)
=> [120, 100, 50, 1]
coco.hue2hsv(120)
=>[120, 100, 100, 1]
// To extract the hue value from a color, just use a 2hsl or 2hsv converter
// and select first item of the returned array.
coco.hex2hsl('#0f0')[0]
=> 120
Conversions Between Color Strings and Arrays
coco.toString(color:array, format:string)
coco.toString([255, 0, 0, 1], 'rgb')
=> 'rgb(255, 0, 0)'
// Or you can use following format specific stringifiers.
coco.rgbStr([255, 0, 0, 0.5])
=> 'rgba(255, 0, 0, 0.5)'
coco.hslStr([0, 100, 50])
=> 'hsl(0, 100%, 50%)'
coco.hsvStr([0, 100, 100])
=> 'hsv(0, 100%, 100%)'
coco.toArray(color:string)
coco.toArray('rgb(255, 0, 0)')
=> [255, 0, 0, 1]
coco.toArray('255')
=> [255, 0, 0, 1]
Format Checks
Following methods test whether the input string is a valid color syntax or not. For more examples you can see equality unit tests.
coco.isHexShort('#f00')
=> true
coco.isHexLong('#ff0000')
=> true
coco.isHex('#ff0000')
=> true
coco.isRgb('rgb(255, 0, 0)')
=> true
// Color strings with alpha parameter can be tested as well.
coco.isRgb('rgba(255, 0, 0, 1)')
=> true
coco.isHsl('hsl(0, 100%, 50%)')
=> true
coco.isHsv('hsv(0, 100%, 50%)')
=> true
coco.isName('red')
=> true
// If you don't know input format, use isColor method.
coco.isColor('rgba(255, 0, 0, 0.5)')
=> true
// Check alpha support
coco.isAlpha('rgba(255, 0, 0, 0.5)')
=> true
coco.isEqual(color:string, color:string)
Compares two color strings.
coco.isEqual('red', 'rgb(255, 0, 0)')
=> true
coco.format(color:string)
Returns format of the input string.
coco.format('#f00')
=> 'hex'
coco.format('#ff0000')
=> 'hex'
coco.format('rgb(255, 0, 0)')
=> 'rgb'
// Color strings with alpha parameter return base format.
coco.format('rgba(255, 0, 0, 0.5)')
=> 'rgb'
coco.format('hsl(0, 100%, 50%)')
=> 'hsl'
coco.format('hsv(0, 100%, 100%)')
=> 'hsv'
// If the input string cannot be parsed, undefined is returned.
coco.format('(0, 0, 100%)')
=> undefined
coco.replace(text:string, callback:function)
Finds all color strings in a given text and passes them to the replacer callback function. This method is useful to unify different color syntaxes.
var cssText = 'background-color: rgb(255, 255, 255); color: hsl(0, 100%, 50%);'
coco.replace(cssText, function(color) {
return coco(color, 'hex');
});
=> 'background-color: #fff; color: #f00;'
Alpha Manipulation
coco.getAlpha(color:string)
coco.getAlpha('rgba(255, 0, 0, 0.5)');
=> 0.5
coco.setAlpha(color:string, alpha:number)
coco.setAlpha('red', 0.5);
=> 'rgba(255, 0, 0, 0.5)'
coco.setAlpha('rgb(255, 0, 0)', 0.5);
=> 'rgba(255, 0, 0, 0.5)'
coco.setAlpha('rgba(255, 0, 0, .5)', 0.8);
=> 'rgba(255, 0, 0, 0.8)'
coco.removeAlpha(color:string)
Removes alpha from a color string if there is one.
coco.removeAlpha('rgba(255, 0, 0, 0.5)');
=> 'rgb(255, 0, 0)'
CSS4 Hex8 Notation Support
The latest W3C color module draft describes that a hexadecimal notation can have 4 or 8 digits. The first 6 digits (or 3 digits in shorter version) of this notation are interpreted as regular red, green and blue channels, but the last pair specifies alpha channel, where 00
represents a transparent color and ff
represent a opaque color. To support this type of notation, there is coco.supportHex8()
method but using this feature in production is not recommended because the W3C draft is in early stage. For those, who want to experiment hex8 notation, here are some examples;
// Use it at your own risk
coco.supportHex8();
// Now, 2hex or hex2 converters take into account
// the alpha channel if it is lower than 1.
coco.rgb2hex('rgba(255, 0, 0, 0.8)')
=> '#f00c'
coco.rgb2hex('rgba(255, 0, 0, 0.5)')
=> '#ff000080'
coco.rgb2hex('rgba(255, 0, 0, 1)')
=> '#f00'
coco.hex2rgb('#ff000080')
=> 'rgba(255, 0, 0, 0.5)'
coco.hex2rgb('#f00c')
=> 'rgba(255, 0, 0, 0.8)'
coco.hex2rgb('#f00f')
=> 'rgb(255, 0, 0)'
// Alpha manipulation
coco.setAlpha('red', 0.5);
=> '#ff000080'
coco.getAlpha('#ff000080');
=> 0.5
coco.removeAlpha('ff000080');
=> '#f00'
// Format checks
coco.isHex('#ff000080')
=> true
coco.isHexLong('#ff000080')
=> true
coco.isHexShort('#f00c')
=> true
// To rollback to regular hex6 notation
coco.unsupportHex8();
License
MIT Copyright (c) 2015 taksim.io