An extensive color manipulation library for the browser and node.js. While extensive, this library is less than 6KB in size (minified and gzipped).
var c =// Calculate a grey level color valuec// Calculate a gradient color between #fc0 and #f00 23% of the way through the gradientc// Calculate the visible color when lightgrey is overlayed on top of #f00 with an opacity of 69%.c// Return a color that's 10% lighterc// Chain them togetherc
var element = documentxolor
This library was ported from the jquery xcolor plugin, and has all the non-jQuery related functionality that library had. Some great documentation for that library that will help understand the methods in this library, see the code examples and demonstrations here: http://www.xarg.org/project/jquery-color-plugin-xcolor/
npm install xolor
// node.jsvar xolor =// amdrequire// global variable<script src="xolor.umd.js"></script>xolor; // xolor.umd.js can define xolor globally if you really// want to shun module-based design
xolor(cssColorString) - Constructor. Takes in either a css color like
"rgb(1, 234, 56)",
"rgb(66%, 55%, 44%)",
xolor(rgbObject) - an rgb object like
xolor(rgbString) - a comma-sparated rgb string like
xolor(rgbArray) - an array where each element is interpreted as an rgba component [r,g,b,a] like
xolor(hslColorString) - an hsl/hsb color like
"hsl(10, 90, 20)" or
"hsb(10, 90, 20)"
xolor(hslObject) - an hsl object like
xolor(hsvColorString) - an hsv color like
"hsv(64, 40, 16)"
xolor(hslObject) - an hsv object like
xolor(integer) - an integer where the least significant 2 bytes represent blue, the next 2 bytes represent green, the next 2 represent red, and the most significant bytes represent alpha.
xolor(xolorObject) - Returns a copy of the passed in xolor object.
xolor.random() - Returns a xolor object representing a random color with 100% opacity.
xolor.readable(background, textColor, fontSize) - Returns true if text will be readable at the given size with the given background and text colors.
background- The background color. Can be any value the
xolorconstructor can take in.
textcolor- The text color. Can be any value the
xolorconstructor can take in.
fontSize- The font size in pixels. Default: 10.
domNode- A domNode to check for readability.
xolor.colorize(domNode, from, to, methodFn) - Colors the text within a domNode.
xolor.colorize(domNode, from, to, methodString)
domNode- The domNode to color.
from- The color the first letter should be.
to- The color the last letter should be.
methodFn(charsProcessed,textLength,lastPosition,character)- The method used to transition between
to. Is a function that should return a number between 0 and 1 indicating how far from
fromand how close to
tothe color will be at the given position.
charsProcessed- The number of characters tha have been processed (ie the index of the character).
textLength- The full length of text in this node.
lastPosition- The last position returned by a call to this method. Starts at 0.
character- The character at the given position.
methodString- The method used to transition between
to. Can be one of the following values:
"gradient"- A smooth gradient between
"flip"- Flips between
toevery visible character.
"pillow"- A smooth gradient between
toand back to
Instance methods and properties:
xolorObject.r - Returns the red part of the xolor. Setting this value mutates the color.
xolorObject.g - Returns the green part of the xolor. Setting this value mutates the color.
xolorObject.b - Returns the blue part of the xolor. Setting this value mutates the color.
xolorObject.a - Returns the alpha part of the xolor. Setting this value mutates the color.
xolorObject.rbg - Returns an rbga object representing the color (like
xolorObject.css - Returns a css color string representing the color (either
"transparent" or a css rbg or rbga string like
"rgb(1, 234, 56)").
xolorObject.fraction - Returns an rbga object where each property is a number from 0 to 1 representing a percentage of full color. To clarify,
xolor('rbg(10%,20%,30%)').fraction would return
[0.1, 0.2, 0.3].
xolorObject.array - Returns an array where each element represents an rgba value. To clarify,
xolor('rbg(20,50,100)').array would return
xolorObject.hsl - Returns an hsla object representing the color in Hue-Saturation-Lightness format.
xolorObject.hsv - Returns an hsva object representing the color in Hue-Saturation-Value format.
xolorObject.hex - Returns a hex string value representing the color.
xolorObject.toString() - Same as
xolorObject.int - Returns an integer where the least significant 2 bytes represent blue, the next 2 bytes represent green, the next 2 represent red, and the most significant bytes represent alpha.
xolorObject.name - Returns the closest name for the color from this list: http://www.w3.org/TR/css3-color/#svg-color
Combinations two colors:
Each of these functions returns a new xolor object based on a function of two colors. Xolor objects are never mutated by commands on them - all methods return new objects and are, consequently, chainable.
xolorObject.blend(topColor, opacity) - Returns the color that would show if
topColor was over the
xolorObject's color with the given
xolorObject.combine(otherColor) - Returns the two colors combined with a ximple XOR method.
xolorObject.breed(otherColor) - Returns a xolor with random parts of each color.
xolorObject.add(otherColor) - Returns the additive mix of the two colors.
xolorObject.subtractive(otherColor) - Returns the subtractive mix of the two colors.
xolorObject.subtract(otherColor) - Returns the subtraction of the two colors. I don't believe this is a standard color method.
xolorObject.mult(otherColor) - Returns the multiplicative mix of the two colors.
xolorObject.multiply(otherColor) - Alias for
xolorObject.avg(otherColor) - Returns a color between the two colors by averaging the rgb parts.
xolorObject.average(otherColor) - Alias for
xolorObject.gradient(otherColor, position) - Returns the color on a gradient between the two colors at the given
position on the gradient.
otherColor- Can be any value the
xolorconstructor can take in.
position- A number from 0 to 1 representing how close to
otherColorthe returned color should be (where 1 represents the
The following methods return a single xolor object:
xolorObject.inverse() - Returns the inverse xolor.
xolorObject.web() - Returns a "web safe" xolor.
xolorObject.complementary() - Returns of the complementary color as a a xolor object.
xolorObject.comp() - Alias for
xolorObject.red() - Returns a xolor with just the red part.
xolorObject.green() - Returns a xolor with just the green part.
xolorObject.blue() - Returns a xolor with just the blue part.
These methods return a color attribute when called with no argument, and return a new
xolor object with that attribute modified if you do pass an argument.
xolorObject.lightness() - Returns the lightness level (a number between 0 and 255).
xolorObject.lightness(level) - Returns a xolor with the lightness changed to the given
level (a number between 0 and 255).
xolorObject.hue() - Returns the hue (a number between 0 and 360).
xolorObject.hue(newHue) - Returns a xolor with the hue changed to the passed
newHue (a number between 0 and 360).
xolorObject.saturation() - Returns the saturation as caluated in the HSV model (a number between 0 and 1).
xolorObject.saturation(newSaturation) - Returns a xolor with the hue (as caluated in the HSV model) changed to the passed
newSaturation (a number between 0 and 1).
xolorObject.brightness() - Returns the brightness (aka "value") as caluated in the HSV model (a number between 0 and 1).
xolorObject.brightness(newValue) - Returns a xolor with the brightness (aka "value", as caluated in the HSV model) changed to the passed
newValue (a number between 0 and 1).
xolorObject.luminosity() - Returns the WCAG luminosity (a number between 0 and 1).
xolorObject.sepia() - Returns a xolor filtered by microsoft's sepia filter.
xolorObject.greyfilter(method) - Returns a grey version of the xolor.
method- (Default: 1) Can be:
1- Robert Eisele's grey filter method
2- Sun's grey filter method
3- An unknown grey filter method (I'm not sure where it came from)
The following methods return arrays of xolor objects.
xolorObject.triad() - Returns the color's triad.
xolorObject.tetrad() - Returns the color's tetrad.
xolorObject.splitcomplement() - Returns the color's split complement colors.
xolorObject.splitcomp() - Alias for
xolorObject.monochromatic(number) - Returns an array of monochromatic colors.
xolorObject.monochromes(number) - Alias for
xolorObject.analogous(number, slices) - Returns an array of analogous color.
number- (Default:8) The number of colors to return.
slices- (Default:32) I'm not entirely sure what this parameter is.
xolorObject.schemeFromDegrees(hueDegreesArray) - Returns an array of xolor objects the same length as the array passed in. For example,
xolor('red').schemeFromDegrees([0, 120, 240]) is a triadic color scheme.
hueDegreesArray- An array where each element is a number of degrees representing a color with a hue (0-360) that many degrees from the original color.
xolorObject.distance(fromColor) - Returns an integer representing the "distance" between the
xolorObject's color and the
fromColor can be any value you can pass into the
xolor constructor (a number between 0 and 441.67). See here for details.
xolorObject.contrast(color2) - Returns the WCAG contrast between the two colors (a number between 1 and 21).
How to Contribute!
- Creating issues (aka tickets/bugs/etc). Please feel free to use issues to report bugs, request features, and discuss changes
- Updating the documentation: ie this readme file. Be bold! Help create amazing documentation!
- Submitting pull requests.
How to submit pull requests:
- Please create an issue and get my input before spending too much time creating a feature. Work with me to ensure your feature or addition is optimal and fits with the purpose of the project.
- Fork the repository
- clone your forked repo onto your machine and run
npm installat its root
- If you're gonna work on multiple separate things, its best to create a separate branch for each of them
- If it's a code change, please add to the unit tests (at test/xolor.js) to verify that your change
- When you're done, run the unit tests and ensure they all pass
- Commit and push your changes
- Submit a pull request: https://help.github.com/articles/creating-a-pull-request
- Adding hue, saturation, brightness, luminosity, schemeFromDegrees, and contrast
- Removing relLightness and lighter
- 1.1.8 - Fixing colorize and adding full documentation
- 1.1.0 - Changed lightness and relLightness from getter/setters to functions
- 1.0.0 - Created based on https://github.com/infusion/jQuery-xcolor
- Incorporate more color methods from less.js
- Incorporate missing methods listed here: http://stackoverflow.com/questions/10266123/hex-rgb-color-manipulation-methods/10266506#10266506
- Write tests
- Add HSI support
- Add HWB support
- Add 'whiteness' and 'blackness' methods
- Add CMYK support
Thanks goes out to:
- Robert Eisele who's xColor jQuery plugin is where I got much of the code for this module.
Dual licensed under the MIT or GPL Version 2 licenses.
Other useful javacript color modules
These modules may have manipulation methods not contained in this library:
These modules have manipulations that are already contained in this xolor library as of last checking: