onecolor

JavaScript color calculation toolkit for node.js and the browser.

Features:

• RGB, HSV, HSL, and CMYK colorspace support (experimental implementations of LAB and XYZ)
• Legal values for all channels are 0..1
• Instances are immutable -- a new object is created for each manipulation
• All internal calculations are done using floating point, so very little precision is lost due to rounding errors when converting between colorspaces
• Alpha channel support
• Extensible architecture -- implement your own colorspaces easily
• Chainable color manipulation
• Seamless conversion between colorspaces
• Outputs as hex, rgb(...), or rgba(...).

Module support:

• CommonJS / Node
• AMD / RequireJS
• Vanilla JS (installs itself on one.color)

Package managers:

• npm: npm install onecolor
• bower: bower install color

Small sizes:

• one-color.js (Basic RGB, HSV, HSL)
• one-color-all.js (Full RGB, HSV, HSL, CMYK, XYZ, LAB, named colors, helper functions)

Usage

In the browser (change one-color.js to one-color-all.js to gain named color support):

1<script src="one-color.js"></script>
2<script>
3  alert(
4    'Hello, ' + one.color('#650042').lightness(0.3).green(0.4).hex() + ' world!'
5  );
6</script>

In the browser, the parser is exposed as a global named onecolor. In node.js, it is returned directly with a require of the module (after npm install onecolor):

1var color = require('onecolor');
2console.warn(color('rgba(100%, 0%, 0%, .5)').alpha(0.4).cssa());

1rgba(255,0,0,0.4)

All of the above return color instances in the relevant color space with the channel values (0..1) as instance variables:

1var myColor = color('#a9d91d');
2myColor instanceof color.RGB; // true
3myColor.red(); // 0.6627450980392157

You can also parse named CSS colors (works out of the box in node.js, but the requires the slightly bigger one-color-all.js build in the browser):

1color('maroon').lightness(0.3).hex(); // '#990000'

To turn a color instance back into a string, use the hex(), css(), and cssa() methods:

1color('rgb(124, 96, 200)').hex(); // '#7c60c8'
2color('#bb7b81').cssa(); // 'rgba(187,123,129,1)'

Color instances have getters/setters for all channels in all supported colorspaces (red(), green(), blue(), hue(), saturation(), lightness(), value(), alpha(), etc.). Thus you don't need to think about which colorspace you're in. All the necessary conversions happen automatically:

1color('#ff0000') // Red in RGB
2  .green(1) // Set green to the max value, producing yellow (still RGB)
3  .hue(0.5, true) // Add 180 degrees to the hue, implicitly converting to HSV
4  .hex(); // Dump as RGB hex syntax: '#2222ff'

When called without any arguments, they return the current value of the channel (0..1):

1color('#09ffdd').green(); // 1
2color('#09ffdd').saturation(); // 0.9647058823529412

When called with a single numerical argument (0..1), a new color object is returned with that channel replaced:

1var myColor = color('#00ddff');
2myColor.red(0.5).red(); // .5
3
4// ... but as the objects are immutable, the original object retains its value:
5myColor.red(); // 0

When called with a single numerical argument (0..1) and true as the second argument, a new value is returned with that channel adjusted:

1color('#ff0000') // Red
2  .red(-0.1, true) // Adjust red channel by -0.1
3  .hex(); // '#e60000'

Alpha channel

All color instances have an alpha channel (0..1), defaulting to 1 (opaque). You can simply ignore it if you don't need it.

It's preserved when converting between colorspaces:

1color('rgba(10, 20, 30, .8)').green(0.4).saturation(0.2).alpha(); // 0.8

Comparing color objects

If you need to know whether two colors represent the same 8 bit color, regardless of colorspace, compare their hex() values:

1color('#f00').hex() === color('#e00').red(1).hex(); // true

Use the equals method to compare two color instances within a certain epsilon (defaults to 1e-9).

1color('#e00').lightness(0.00001, true).equals(color('#e00'), 1e-5); // false
2color('#e00').lightness(0.000001, true).equals(color('#e00'), 1e-5); // true

Before comparing the equals method converts the other color to the right colorspace, so you don't need to convert explicitly in this case either:

1color('#e00').hsv().equals(color('#e00')); // true

API overview

Color parser function, the recommended way to create a color instance:

1color('#a9d91d'); // Regular hex syntax
2color('a9d91d'); // hex syntax, # is optional
3color('#eee'); // Short hex syntax
4color('rgb(124, 96, 200)'); // CSS rgb syntax
5color('rgb(99%, 40%, 0%)'); // CSS rgb syntax with percentages
6color('rgba(124, 96, 200, .4)'); // CSS rgba syntax
7color('hsl(120, 75%, 75%)'); // CSS hsl syntax
8color('hsla(120, 75%, 75%, .1)'); // CSS hsla syntax
9color('hsv(220, 47%, 12%)'); // CSS hsv syntax (non-standard)
10color('hsva(120, 75%, 75%, 0)'); // CSS hsva syntax (non-standard)
11color([0, 4, 255, 120]); // CanvasPixelArray entry, RGBA
12color(['RGB', 0.5, 0.1, 0.6, 0.9]); // The output format of color.toJSON()

The slightly bigger one-color-all.js build adds support for the standard suite of named CSS colors:

1color('maroon');
2color('darkolivegreen');

Existing onecolor instances pass through unchanged, which is useful in APIs where you want to accept either a string or a color instance:

1color(color('#fff')); // Same as color('#fff')

Serialization methods:

1var myColor = color('#bda65b');
2
3myColor.hex(); // 6-digit hex string: '#bda65b'
4myColor.css(); // CSS rgb syntax: 'rgb(10,128,220)'
5myColor.cssa(); // CSS rgba syntax: 'rgba(10,128,220,0.8)'
6myColor.toString(); // For debugging: '[onecolor.RGB: Red=0.3 Green=0.8 Blue=0 Alpha=1]'
7myColor.toJSON(); // ["RGB"|"HSV"|"HSL", <number>, <number>, <number>, <number>]

Getters -- return the value of the channel (converts to other colorspaces as needed):

1var myColor = color('#bda65b');
2
3myColor.red();
4myColor.green();
5myColor.blue();
6myColor.hue();
7myColor.saturation();
8myColor.value();
9myColor.lightness();
10myColor.alpha();
11myColor.cyan(); // one-color-all.js and node.js only
12myColor.magenta(); // one-color-all.js and node.js only
13myColor.yellow(); // one-color-all.js and node.js only
14myColor.black(); // one-color-all.js and node.js only

Setters -- return new color instances with one channel changed:

1color.red(<number>)
2color.green(<number>)
3color.blue(<number>)
4color.hue(<number>)
5color.saturation(<number>)
6color.value(<number>)
7color.lightness(<number>)
8color.alpha(<number>)
9color.cyan(<number>)    // one-color-all.js and node.js only
10color.magenta(<number>) // one-color-all.js and node.js only
11color.yellow(<number>)  // one-color-all.js and node.js only
12color.black(<number>)   // one-color-all.js and node.js only

Adjusters -- return new color instances with the channel adjusted by the specified delta (0..1):

1color.red(<number>, true)
2color.green(<number>, true)
3color.blue(<number>, true)
4color.hue(<number>, true)
5color.saturation(<number>, true)
6color.value(<number>, true)
7color.lightness(<number>, true)
8color.alpha(<number>, true)
9color.cyan(<number>, true)    // one-color-all.js and node.js only
10color.magenta(<number>, true) // one-color-all.js and node.js only
11color.yellow(<number>, true)  // one-color-all.js and node.js only
12color.black(<number>, true)   // one-color-all.js and node.js only

Comparison with other color objects, returns true or false (epsilon defaults to 1e-9):

1color.equals(otherColor[, <epsilon>])

Mostly for internal (and plugin) use:

"Low level" constructors, accept 3 or 4 numerical arguments (0..1):

1new onecolor.RGB(<red>, <green>, <blue>[, <alpha>])
2new onecolor.HSL(<hue>, <saturation>, <lightness>[, <alpha>])
3new onecolor.HSV(<hue>, <saturation>, <value>[, <alpha>])

The one-color-all.js build includes CMYK support:

1new onecolor.CMYK(<cyan>, <magenta>, <yellow>, <black>[, <alpha>])

All color instances have rgb(), hsv(), and hsl() methods for explicitly converting to another color space. Like the setter and adjuster methods they return a new color object representing the same color in another color space.

If for some reason you need to get all the channel values in a specific colorspace, do an explicit conversion first to cut down on the number of implicit conversions:

1var myColor = color('#0620ff').lightness(+0.3).rgb();
2
3console.log(myColor.red() + ' ' + myColor.green() + ' ' + myColor.blue());

10 0.06265060240963878 0.5999999999999999

Building

git clone https://github.com/One-com/one-color.git
cd one-color
npm install
npm run build

If you aren't up for a complete installation, there are pre-built packages in the repository as well as the npm package:

• Basic library: one-color.js
• Full library including named color support: one-color-all.js

License

onecolor is licensed under a standard 2-clause BSD license -- see the LICENSE file for details.