pure-color
pure-color
is a color conversion and parsing library for the browser and node. It offers conversions between rgb
, hsl
, hsv
, hwb
, cmyk
, xyz
, lab
, lch
, hex
. It offers parsing of rgb(a)
, hex
and hsl(a)
strings.
Installation
Install with npm:
Structure
The library is structured to allow requiring of just the functions you need. You can also require everything if file size is not a concern (e.g. node environment).
API
Conversion
The majority of conversion functions have the signature [Number] -> [Number]
. The exceptions are rgb2string
and rgb2hex
, whose signature is [Number] -> String
.
You can see all available conversions in the convert
directory.
Hash
"pure-color/convert"
exports a hash of conversion functions keyed first by the "from" space, then by the "to" space:
Notes
Alpha values
The conversion functions make no effort to handle alpha values. For instance:
The reason for this is two-fold:
Alpha value is orthogonal to color. A color with 50% opacity, is still the same color if it had 100% opacity.
It is not clear how alpha values should be handled in some color spaces. For instance, does alpha make sense in CMYK space?
You must make effort to preserve alpha values between conversions yourself if this is important to you.
Missing conversions
Any conversions that are simple compositions of other conversions have been omitted.
For example, let's imagine we wanted to convert hsl
to cmyk
. This function doesn't exist, but it can be trivially created by composing hsl2rgb
and rgb2cmyk
:
If there are missing conversions that cannot be achieved through composition, please raise an issue.
Parsing
Parse functions have signature String -> [Number]
.
A generic parsing function is available, which accepts hsl
, rgb
, and hex
string formats. This always converts to rgb
space for consistency - if you don't know what format the color is to begin with, you don't know what color space will be returned.
Individual parsing functions are available if you know what format you will be parsing. Note that the hsl
parse function returns an hsl
array, whereas rgb
and hex
return an rgb
array
Dependencies
No dependencies. Should work in any browser with ES5 support (which can be shimmed easily).
Motivation
I have tried many color conversion/parsing libraries and I was not satisfied with any of them.
They're often wrapped up in awkward object-oriented APIs
They require that you include the entire library, when you often only want a subset of functionality
This library attempts to correct that by:
Offering pure functions with consistent signatures
Offer the bare minimum necessary functions
Allow requiring of only the functions you need, reducing file size
Contributions & Issues
Contributions are welcome from everyone.
Issues can be resolved quickest if they are descriptive and include both a reduced test case and a set of steps to reproduce. Personal help requests filed as issues will be declined.
Please clearly explain the purpose of any pull request. In lieu of a formal style guide, please follow the current coding style. Tests would be nice, but are not essential.
License
Licensed under the MIT License
Last updated