A library of well-tested helper methods for working with colors. Comes with flow typings and tree-shakeable modules.
Installation
Simply do: npm install colorutilities
.
What is it?
This is a collection of helper methods for working with colors and converting between color systems. Simple methods are provided such as toHex()
, toHsl()
, toHsv()
, toRgb()
, saturate()
, lighten()
and much more.
The library takes care of figuring out which color system your input string comes from, so you can just use the library and not care about the rest.
Supported color systems:
- RGB/RGBa
- Hex
- HSV/HSB
- HSL/HSLa
- HTML color names.
Beyond that, everything is typed with Flow and every method is exported as separate modules. This makes this library very easy to tree-shake and incorporate in your rollup or webpack build.
At the time of writing, 388 tests has been written for the library methods. I'd say you can use it in production today.
Have fun!
Examples
; // returns 'hsl(348, 83%, 47%)' // returns 'hsl(348, 83%, 47%)' // returns 'hsl(348, 83%, 47%)' // returns 'hsl(348, 83%, 47%)' // returns 'hsl(348, 83%, 47%)' // lightens the color 10% and returns the new value: #EACDF4. // saturates the HTML color 'brown' an additional 100%. // returns true, that's a pretty light color.; // returns a random hex color.
Changelog:
v0.02:
- Fixed a bug where RGB colors could be returned non-rounded even though 'rounding' was true.
v0.01:
- First release! 388 tests has been written and bidirectional conversions between HEX, RGB/RGBa, HSL/HSLa, HSV/HSB and HTML color names are supported in this initial release.
Usage
Import it in your project like this:
; // (standard) Transpiled to ES5.// or ; // Transpiled to ES5 except for native ES-modules.// or ; // Flow typings, ES-modules, pretranspile.
Documentation
#isLight()
Determines if the given color is light or not.
Signature:
: boolean
Arguments:
color: string
- The color to check. Can be any of the color systems CSS can handle with the addition of HSB/HSV.
Returns:
boolean
- Returns true if the color is light, false otherwise.
Example
// returns true, that's a pretty light color.
#lighten()
Changes the lightness of the given color. Will automatically determine the type of color and how to handle it. Pass negative values to darken the color instead.
Signature:
: string
Arguments:
-
color: string
- The color to lighten. Can be any of the color systems CSS can handle with the addition of HSB/HSV. -
percentage?: number
- Optionally, the amount of percentage to lighten the color. Pass a negative value to darken the color instead.Default = 10
Returns:
string
- The lightened/darkened color.
Example
// lightens the color 10% and returns the new value: #EACDF4. // darkens the color 90% and returns the new value: #1B0721.
#saturate()
Changes the saturation of the given color. Will automatically determine the type of color and how to handle it. Pass a negative percentage value to desaturate the color instead.
Signature:
: string
Arguments:
-
color: string
- The color to saturate. Can be any of the color systems CSS can handle with the addition of HSB/HSV. -
percentage?: number
- Optionally, the amount of percentage to saturate the color. Pass a negative value to desaturate the color instead.Default = 10
Returns:
string
- The saturated/desaturated color.
Example
// saturates the HTML color 'brown' an additional 100%. // desaturates the HTML color 'brown' 100%.
#toHex()
Takes a color and converts it to a hex color.
Signature:
: string
Arguments:
color: string
- The color to convert to a hex color. Can be any of the color systems CSS can handle with the addition of HSB/HSV. If a hex color is given, a hex color will be returned.
Returns:
string
- The hex representation of the given color. Will always have a '#' in front of it.
Throws:
TypeError
- If the first argument is not of type 'string'.TypeError
- If the given color appears to be a hex color but is of invalid length.TypeError
- If the method didn't succeed in normalizing the given argument into a hex color.
Example
// returns '#DC143C' // returns '#DC143C' // returns '#DC143C' // returns '#DC143C' // returns '#DC143C'
#toRgb()
Takes a color and converts it to an RGB color.
Signature:
: string
Arguments:
color: string
- The color to convert to an RGB color. Can be any of the color systems CSS can handle with the addition of HSB/HSV. If an RGB color is given, an RGB color will be returned.
Returns:
string
- The RGB representation of the given color.
Throws:
TypeError
- If the first argument is not of type 'string'.TypeError
- If the given color appears to be a hex color but is of invalid length.TypeError
- If the method didn't succeed in normalizing the given argument into an RGB color.
Example
// returns 'rgb(220, 20, 60)' // returns 'rgb(220, 20, 60)' // returns 'rgb(220, 20, 60)' // returns 'rgb(220, 20, 60)' // returns 'rgb(220, 20, 60)'
#toHsl()
Takes a color and converts it to an HSL color.
Signature:
: string
Arguments:
color: string
- The color to convert to an HSL color. Can be any of the color systems CSS can handle with the addition of HSB/HSV. If an HSL color is given, an HSL color will be returned.
Returns:
string
- The HSL representation of the given color.
Throws:
TypeError
- If the first argument is not of type 'string'.TypeError
- If the given color appears to be a hex color but is of invalid length.TypeError
- If the method didn't succeed in normalizing the given argument into an HSL color.
Example
// returns 'hsl(348, 83%, 47%)' // returns 'hsl(348, 83%, 47%)' // returns 'hsl(348, 83%, 47%)' // returns 'hsl(348, 83%, 47%)' // returns 'hsl(348, 83%, 47%)' // returns 'hsl(348, 83%, 47%)'
#toHsv()
Takes a color and converts it to an HSV/HSB color.
Signature:
: string
Arguments:
color: string
- The color to convert to an HSV/HSB color. Can be any of the color systems CSS can handle with the addition of HSB/HSV. If an HSV/HSB color is given, an HSV/HSB color will be returned.
Returns:
string
- The HSV/HSB representation of the given color.
Throws:
TypeError
- If the first argument is not of type 'string'.TypeError
- If the given color appears to be a hex color but is of invalid length.TypeError
- If the method didn't succeed in normalizing the given argument into an HSVB/HSB color.
Example
// returns 'hsb(348, 91, 86)' // returns 'hsv(348, 91, 86)' // returns 'hsb(348, 91, 86)' // returns 'hsb(348, 91, 86)' // returns 'hsb(348, 91, 86)' // returns 'hsb(348, 91, 86)' // returns 'hsb(348, 91, 86)'
#randomHexColor()
Generates a random hex color and returns it.
Signature:
: string
Returns:
string
- A random hex color. Always starts with '#'.
Example
; // Makes the background of the body element change to a new random color every 100ms. Welcome back to web 1.0!
#randomRgbColor()
Generates a random RGB color and returns it.
Signature:
: string
Returns:
string
- A random RGB color.
Example
; // Makes the background of the body element change to a new random color every 100ms. Welcome back to web 1.0!
#randomHslColor()
Generates a random HSL color and returns it.
Signature:
: string
Returns:
string
- A random HSL color.
Example
; // Makes the background of the body element change to a new random color every 100ms. Welcome back to web 1.0!
#randomHsvColor()
Generates a random HSV color and returns it.
Signature:
: string
Returns:
string
- A random HSV color.
Example
; // Makes the background of the body element change to a new random color every 100ms. Welcome back to web 1.0!
Other methods
There's a lot of them. The above was the highlights. Everything is well-documented in the source code. Here's a quick overview of the methods that isn't included in this readme:
-
hslStringToHslTuple
:- Converts a string-represented HSL color to a tuple of the values.
-
hslToHsla
:- Generates a HSLA color from a HSL color.
-
hslaStringToHslaTuple
:- Converts a string-represented HSLa color to a tuple of the values.
-
hslToRgbTuple
:- Converts the given HSL color to an RGB color and returns it as a tuple of the values.
-
hslToRgb
:- Converts the given HSL color to an RGB color and returns it as a string.
-
hslaToRgbaTuple
:- Converts the given HSLa color to an RGBa color and returns it as a tuple of the values.
-
hslaToRgba
:- Converts the given HSLa color to an RGBa color and returns it as a string.
-
hslaToHsl
:- Converts the given HSLa color to an HSL color and returns it as a string.
-
rgbStringToRgbTuple
:- Generates a tuple-representation of an RGB color.
-
rgbaStringToRgbaTuple
:- Generates a tuple-representation of an RGBa color.
-
rgbToHex
:- Generates a hex representation of an RGB color.
-
rgbaToHex
:- Generates a hex representation of an RGBa color.
-
hsvStringToHsvTuple
:- Generates a tuple-representation of an HSV/HSB color.
-
hsvToRgbTuple
:- Converts an HSV/HSB color to an RGB color and returns it as a tuple of the values.
-
hsvToRgb
:- Converts a HSV color to an RGB color and returns it as a string.
-
hexToRgbTuple
:- Generates a RGB version of a hex color and returns it as a tuple of the values.
-
hexToRgb
:- Generates a RGB version of a hex color and returns it as a string.
-
hexToHslTuple
:- Generates a HSL color from a hex color and returns it as a tuple.
-
hexToHslaTuple
:- Generates a HSLA color from a hex color and returns it as a tuple.
-
hexToHsla
:- Generates a HSLA color from a hex color and returns it as a string.
-
hexToHsl
:- Generates a HSL color from a hex color and returns it as a string.
-
rgbToHslTuple
:- Generates a HSL color from a RGB color and returns it as a tuple of the values.
-
rgbToHsl
:- Generates a HSL color from a RGB color and returns it as a string.
-
rgbToHsvTuple
:- Converts an RGB color to an HSV/HSB color and returns it as a tuple of the values.
-
rgbToHsv
:- Converts an RGB color to an HSV/HSB color and returns it as a string.
-
randomRgbColor
:- Generates a random RGB color and returns it.
-
randomHslColor
:- Generates a random HSL color and returns it.
-
randomHsvColor
:- Generates a random HSV/HSB color and returns it.