README.md

Warna

Warna is color utility library written in Javascript to help you parse, convert, or manipulate colors. It can works on browser or Node.js as npm modules.

Installation

You can install Warna via npm,

npm install warna

or download latest version from Github

Getting Started

Node.js

var warna = require('warna');

var hex = '#ffffff';
var color = warna.parse(hex);

console.log(color.rgb);
// will print {red: 255, green: 255, blue: 255}

Browser

<script src="/path/to/warna.js"></script>
<script>
  var hex = '#ffffff';
  var color = warna.parse(hex);
  
  console.log(color.rgb);
  // will print {red: 255, green: 255, blue: 255}
</script>

Quick Examples

Convert color to RGB or HEX.

// Convert HEX to RGB
var color = warna.parse('#000000');
console.log(color.rgb); 
// will print {red: 0, green: 0, blue: 0}

// Convert RGB to HEX
var color = warna.parse(0, 0, 0);
console.log(color.hex); 
// will print '#ffffff'

Get gradient color position or color slices.

// Get color in center of white-black gradient
var gradient  = new warna.Gradient('#ffffff', '#000000')
var color     = gradient.getPosition(0.5).hex;
console.log(color); 
// will print '#7f7f7f'

// Get 3 color slices in red-blue gradient
var gradient  = warna.Gradient('#ff0000', '#0000ff')
var color     = gradient.getSlices(3, 'hex');
console.log(color);

//  will print
//  [ '#ff0000', '#7f007f', '#0000ff']

Lighten or darken color.

// Lighten red by 20%
var color = warna.lighten('#ff0000', 0.2).hex;
console.log(color); 
// will print '#ff3333'

// Darken red by 20%
var color = warna.darken('#ff0000', 0.2).hex;
console.log(color); 
// will print '#cc0000'

API

parse(color)

Parse color value into Warna object which is a object that contain various format of color, like RGB, HSV, HSL, HEX and Alpha value.

Argument:

• color - (mixed) Color value that will be parsed. It can be a HEX color string, RGB, HSV and HSL object.

Example:

// Parse Red HEX color string
warna.parse('#000000');
/**
  return { 
    rgb: { red: 255, green: 0, blue: 0 },
    hex: '#ff0000',
    hsv: { hue: 0, saturation: 100, value: 100 },
    hsl: { hue: 0, saturation: 1, luminosity: 0.5 },
    alpha: 1 
  }
*/

// This also return same object like above
warna.parse({red: 255, green: 0, blue: 0}); // RGB object
warna.parse({hue: 0, saturation: 100, value: 100}); // HSV object
warna.parse({hue: 0, saturation: 1, luminosity: 0.5}); // HSL object

Gradient(begin, end)

Set gradient color object which can be chained with other gradient utility function like getPosition() or getSlices().

Arguments:

• begin - (mixed) Beginning color value. It can be a HEX color string, RGB object or RGB array.
• end - (mixed) Ending color value. It can be a HEX color string, RGB object or RGB array.

getPosition(pos)

Get color value on gradient based on their position and return Warna object.

Argument:

• pos - (float) Float value (percent) of color position.

Example:

// Getting middle color of red-white gradient
var gradient = new warna.Gradient('#ff0000', '#ffffff');
gradient.getPosition(0.5);

/* Return a Warna object 
  { 
    rgb: {red: 255, green: 127, blue: 127},
    hex: '#ff7f7f',
    hsv: {hue: 0, saturation: 50, value: 100},
    hsl: {hue: 0, aturation: 1, luminosity: 0.7490196078431373},
    alpha: 1 
  }
*/

// You can also pass alpha value to gradient
var firstColor = {red: 255, green: 0, blue: 0, alpha: 0.25};
var secondColor = {red: 255, green: 255, blue: 255, alpha: 0.75};

var gradient = new warna.Gradient(firstColor, secondColor);
gradient.getPosition(0.5);

/* Return warna object
  { 
    rgb: {red: 255, green: 127, blue: 127},
    hex: '#ff7f7f',
    hsv: {hue: 0, saturation: 50, value: 100},
    hsl: {hue: 0, saturation: 1, luminosity: 0.7490196078431373},
    alpha: 0.5 
  }
*/

getSlices(slice, type)

Get color slices of a gradient and return array of Warna object based on number slices you want to get. Slice should be more than 2, if you want to get other color value other than start color and ending color.

Argument:

• slice - (integer) Integer value of number slices you want to get.
• type - (string) Type of color you want to output (rgb, hex, hsv, or hsl).

Example:

// Getting 3 color slices of black-white gradient
var gradient = new warna.Gradient('#ffffff', '#000000')
gradient.getSlices(3, 'hex');

//  Return
//  [ '#ffffff', '#7f7f7f', '#000000']

lighten(color, pos)

Lighten a color. Return warna object.

Arguments:

• color - (mixed) Color value that will be lighten. It can be a HEX color string, RGB object or RGB array.
• pos - (float) Float value of lighten percentation. 0 will returning base color and 1 will return white #ffffff.

Example:

// Lighten red by 20%
warna.lighten('#ff0000', 0.2);

/*
 Return
  { 
    rgb: {red: 255, green: 51, blue: 51},
    hex: '#ff3333',
    hsv: {hue: 0, saturation: 80, value: 100},
    hsl: {hue: 0, saturation: 1, luminosity: 0.6},
    alpha: 1 
  }
*/

darken(color, pos)

Darken a color.

Arguments:

• color - (mixed) Color value that will be lighten. It can be a HEX color string, RGB object or RGB array.
• pos - (float) Float value of lighten percentation. 0 will returning base color and 1 will return black #000000.

Example:

// Darken red by 20%
warna.darken('#ff0000', 0.2);

/* 
  Return
  { 
    rgb: {red: 204, green: 0, blue: 0},
    hex: '#cc0000',
    hsv: {hue: 0, saturation: 100, value: 80},
    hsl: {hue: 0, saturation: 1, luminosity: 0.4},
    alpha: 1 
  }
*/

Copyright and license

Copyright 2014 Alfiana E. Sibuea. Code released under the MIT license.