hex2rgb

Converts hex color to rgb and calculates appropriate corresponding foreground.

Example

For a dark hex color, hex2rgb will give you the rgb equivalent. It will also calculate and return an appropriate constrasting foreground (either 'black' or 'white').

Here's hex2rgb in action. Note the black or white text color (foreground) based on the background color.

Installation

via NPM:

npm install hex2rgb --save

via Bower:

bower install hex2rgb --save

Usage

Using Bower

Include hex2rgb.js in your web app and use it as usual:

<script src="hex2rgb.js"></script>
<script>
	hex2rgb('0033ff').rgb; // => [0, 51, 255]
	hex2rgb('0033ff').rgbString; // => 'rgb(0, 51, 255)'
</script>

Using NodeJS

var hex2rgb = require('hex2rgb');

var background,
	foreground,
	hex = '0033ff',
	shorthex = '03f',
	hashhex = '#0033ff',
	badhex = '00PS1E';

background = hex2rgb(hex).rgb; // => [0, 51, 255]
background = hex2rgb(shorthex).rgb; // => [0, 51, 255]
background = hex2rgb(hashhex).rgb; // => [0, 51, 255]
background = hex2rgb(hex).rgbString; // => 'rgb(0, 51, 255)'
foreground = hex2rgb(hex).yiq; // => white

// try with bad input and with options specified
background = hex2rgb(badhex, {debug: true, rgbStringDefault:'#e9e9e9'}).rgb;
// logs "(hex2rgb) 00PS1E: Expected 3 or 6 HEX-ONLY chars. Returning defaults."
// Returns rgb [255, 255, 255], rgbString '#e9e9e9'
// and yiq 'inherit' as fall-backs.

API

hex2rgb( hex {String}, options {Object} )

hex

A hex-only string of 3 or 6 characters. If the string has a # prefix, the # gets trimmed off.

{debug: true | false}

You can pass {debug:true} to enable errors logged to console.

{rgbStringDefault: "String e.g. transparent | black | #e9e9e9"}

As of v2 you can specify a default string that .rgbString will return when hex input is invalid or yet to be calculated. In v1, .rgbString returned "rgb(0,0,0)" (black).

{yiqDefault: "String e.g. inherit | gray | #333"}

Similar to rgbStringDefault above. In v1 .yiq returned "white" by default.

.rgb

Returns an array in [r, g, b] format. If hex input is invalid or yet to be calculated [255, 255, 255] (white) is returned as a fallback.

.rgbString

Returns a string in rgb(r, g, b) format. If hex input is invalid or yet to be calculated, either 'inherit' or your specified string value is returned as a fallback.

.yiq

Returns a string of either 'white' or 'black'. If hex input is invalid or yet to be calculated, either 'inherit' or your specified string value is returned as a fallback.

Tests

npm test

gulp test to generate code coverage

Contributing

No formal styleguide, but please maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code.

Thanks

• Brian Suda for his article, Calculating Color Contrast, on 24 ways.
• Brent Ertz for his node module article, Creating and publishing a node.js module.

Release History

• 2.2.0 - Minor description updates
• 2.0.0 - Returns [255, 255, 255], 'inherit', specified values as defaults/fallbacks
• 1.4.0 - Returns [0,0,0], 'rgb(0,0,0)' & 'white' as defaults/fallbacks
• 1.0.0 - Lock in release
• 0.8.0 - Add rgbString property
• 0.7.0 - Publish to Bower
• 0.5.0 - Update descriptions
• 0.1.0 - Initial release