HexagonJS
Edit Page
Color
A module for manipulating colors.
Examples
// Create a color from an array
col = hx.color([123,190,49,1])

// Create a color from a css string
col = hx.color('#7BBE31')
col = hx.color('rgb(123,190,49)')
col = hx.color('rgba(123,190,49,1)')
col = hx.color('hsl(88.5,59%,46.9%)')
col = hx.color('hsla(88.5,59%,46.9%,1)')

// Output a color to an array
col.rgb() // returns [123, 190, 49, 1]

// Lighten a color
hx.color([50,50,50]).lighten(0.5) // returns color object equivalent to [75,75,75,1]

// Darken a color
hx.color([50,50,50]).lighten(-0.5) // returns color object equivalent to [25,25,25,1]

// Mix colors on a 50/50 ratio
hx.color([50,50,50]).mix(hx.color([100,100,100])) // returns color object equivalent to [75,75,75,1]

// Mix colors on a 70/30 ratio
hx.color([50,50,50]).mix(hx.color([100,100,100]), 0.3) // returns color object equivalent to [65,65,65,1]
Api
Prototypes
Color
This class should be created through the hx.color function.
A class that can be used to create a color object with methods to manipulate the color such as changing the lightness, saturation and mixing with other colors. The object consists of multiple methods that allow the manipulation of color properties (e.g. red, green etc.) as well as other functions for modifying the color as a whole.
The color object also allows conversion between hsl and rgb, however the conversions are not exact and are rounded to the nearest whole integer so it is suggested that conversions are only made in one direction to prevent a color being modified.
Methods
blueNumber
Gets the blue value for a color.
Returns
The blue value for a color as an integer between 0 and 255
bluevalueNumberColor
Sets the blue value for a color.
Arguments
valueNumber
A number between 0 and 255
Returns
Color
This Color
cloneColor
Returns a duplicate object. Useful for creating new colors based on a palette without modifying the originals.
Returns
Color
A duplicate color object.
fadeamountNumberColor
A method for changing the alpha value of a color by a given percentage amount
Arguments
amountNumber
A value from 0-1 as a percentage.
Returns
Color
This Color
greenNumber
Gets the green value for a color.
Returns
The green value for a color as an integer between 0 and 255
greenvalueNumberColor
Sets the green value for a color.
Arguments
valueNumber
A number between 0 and 255
Returns
Color
This Color
hslarrArray[Number]Color
Sets the tgb array for a color.
Arguments
The hsl array to set. It can be in the format of r,g,b or r,g,b,a
Returns
Color
This Color
Gets the hsl array for a color.
Returns
The hsl array for a color in the format r,g,b,a
Gets the hue value for a color.
Returns
The hue value for a color as an integer between 0 and 360
huevalueNumberColor
Sets the hue value for a color.
Arguments
valueNumber
A number between 0 and 360
Returns
Color
This Color
lightenamountNumberColor
Increase the lightness of a color by a given percentage amount.
Arguments
amountNumber
A value from 0-1 as a percentage.
Returns
Color
This Color
lightnessNumber
Gets the lightness value for a color.
Returns
The lightness value for a color as an integer between 0 and 100
lightnessvalueNumberColor
Sets the lightness value for a color.
Arguments
valueNumber
A number between 0 and 100
Returns
Color
This Color
mixcolColoramountNumberColor
Modify the color by mixing it with another color object by a given ratio amount.
Arguments
colColor
The color object to mix with the selected color.
amountNumber
A value from 0-1 as a percentage.
Returns
Color
This Color
rangenumLightNumbernumDarkNumbermaxRangeNumberoutputFormatStringArray
Returns an array of colors based on the input color. The number of colors in the array will be the total of the numLight and numDark plus the original color.
The function can also return an array of hex strings instead of an array of Color objects using the outputHex parameter. Defaults to 3.
Arguments
numLightNumber
The number of lighter color steps in the range. Defaults to 3.
numDarkNumber
The number of darker color steps in the range. Defaults to 0.5.
maxRangeNumber
The maximum percentage increase/decrease in lightness.
outputFormatString
The output format for the array. If left undefined, a Color object will be returned.
Accepted values are:
  • hex
  • rgb
  • rgba
  • hsl
  • hsla
  • array
Returns
An array of colors in the specified output format. If no output format is specified, an array of Color objects is returned.
Gets the red value for a color.
Returns
The red value for a color as an integer between 0 and 255
redvalueNumberColor
Sets the red value for a color.
Arguments
valueNumber
A number between 0 and 255
Returns
Color
This Color
Gets the rgb array for a color.
Returns
The rgb array for a color in the format r,g,b,a
rgbarrArray[Number]Color
Sets the tgb array for a color.
Arguments
The rgb array to set. It can be in the format of r,g,b or r,g,b,a
Returns
Color
This Color
saturateamountNumberColor
Increase the saturation of a color by a given percentage amount.
Arguments
amountNumber
A value from 0-1 as a percentage.
Returns
Color
This Color
saturationNumber
Gets the saturation value for a color.
Returns
The saturation value for a color as an integer between 0 and 100
saturationvalueNumberColor
Sets the saturation value for a color.
Arguments
valueNumber
A number between 0 and 100
Returns
Color
This Color
textColString
A method to return the best text color (either black or white) when using the current color as a background.
Returns
'black' or 'white' depending on the color.
toStringtypeStringString
Output the color object as a hex, hsl, hsla, rgb or rgba CSS string.
Arguments
typeString
A css color string. The default is to output a hex string if the alpha is 1, and rgba string if the alpha value is less than 1.
Accepted types are:
  • hex
  • rgb
  • rgba
  • hsl
  • hsla
Returns
A css color string of the type passed in.
Functions
hx.color.isColorobjAnyBooleandeprecated
Deprecated
Replaced by hx.isColor
Checks if an object is a Color instance.
Arguments
objAny
The object to check.
Returns
True if the object is a Color instance.
hx.color.isColorStringstrStringBooleandeprecated
Deprecated
Replaced by hx.isColorString
Checks if a string is a css color string.
Arguments
A css color string, accepts "hex", "hsl", "hsla", "rgb", "rgba".
Returns
True if the string is a valid css string.
hx.colorColor
Constructs a new Color instance.
Returns
Color
hx.colorstrStringColor
Constructs a Color instance from a string. If the string passed in is not valid then this function will return undefined.
Arguments
A css color string, accepts "hex", "hsl", "hsla", "rgb", "rgba".
Returns
Color
hx.colorarrayArray[Number]Color
Constructs a Color instance from an array.
Arguments
An array containing the rgb or rgba values
hx.color([255, 255, 255])
hx.color([255, 255, 255, 1])
Returns
Color
hx.colorrNumbergNumberbNumberaNumberColor
Constructs a Color instance from a list of rgb values.
hx.color(255, 255, 255)
hx.color(255, 255, 255, 1)
Arguments
The red component of the color, given in the range [0, 255]
The green component of the color, given in the range [0, 255]
The blue component of the color, given in the range [0, 255]
The alpha component of the color, given in the range [0, 1]
Returns
Color
hx.isColorobjAnyBoolean
Checks if an object is a Color instance.
Arguments
objAny
The object to check.
Returns
True if the object is a Color instance.
hx.isColorStringstrStringBoolean
Checks if a string is a css color string.
Arguments
A css color string, accepts "hex", "hsl", "hsla", "rgb", "rgba".
Returns
True if the string is a valid css string.
Getting Started
Other functionality and examples
The Color prototype contains several methods to allow for modification of a color.
The below examples show all the available methods and also use the toString() method to show the hex value and set the background color of the cells.
In the below examples, exCol is the example color object that we are manipulating.
Cloning
The clone() function returns a new color with the same r, g, b and a values as the current color. Cloning a color object is useful for situations where you need a version of a color without modifying the original value. The methods on the Color class all modify the selected object. Cloning is useful for situations where you need a new version of a color without altering the original.
newColor = exCol.clone()
The newColor object can be modified freely without altering exCol color.
Lightness
The lightness functions are useful for creating variations of a color without changing them drastically. Below are examples of each of the lightness functions:
exCol
exCol.lighten(0.2)
exCol.lighten(-0.2)
exCol.lightness(30)
Saturation
The saturation functions are useful for creating new colors that are of a similar lightness. Below are examples of each of the saturation functions:
exCol
exCol.saturate(0.4)
exCol.saturate(-0.4)
exCol.saturation(10)
Alpha
The alpha functions are useful for making transparent colors where required or animating a color. Below are examples of each of the saturation functions. Note: The alpha channel is only supported with RGBA and HSLA. When outputting a color string, make sure you output to a type that accepts alpha values
exCol.alpha(0.7)
exCol.fade(0.2)
exCol.fade(-0.2)
exCol.alpha(0.3)
Mix
The mix function is used to create a mix of two colors. The mix amount indicates how much of the new color to mix with this color with lower values showing more of the current color and higher values showing more of the mixing color. Below is an example where we mix exCol with purple:
exCol
exColAlt = hx.color([103,23,112])
exCol.mix(exColAlt)
exCol.mix(exColAlt,0.3)
Chaining methods
It's possible to chain methods when using the Color api. For instance, to create a color that is 20% darker and 30% less saturated than the original, use:
newCol = exCol.clone().lighten(-0.2).saturate(-0.3)
instead of
newCol = exCol.clone()
newCol.lighten(-0.2)
newCol.saturate(-0.3)
Building a color range
You can use the colorRange function to create a range of lighter or darker colors based on any color. The default values for the function returns an array of 7 color objects, 3 lighter, 3 darker and the original, in order of lightness.
exCol.range()
You can use the function to build arrays of any length by specifying the numDark and numLight parameters.
exCol.range(5,5)
If the numDark and numLight are not equal, the step between each color will be calculated using the maximum value. As you can see, the lightest color below matches the above ranges and the dark color does not.
exCol.range(3,1)
You can also change the maxRange value to give greater increases/decreases in color
exCol.range(3,3,0.75)