Documentation will be updated after API is finalized. Please be mindful of this!

Here it is, the final piece of the color makeover trilogy. If you recall, I did a makeover of both color-string and color-convert that have been generally well-received. This was the final piece.

After an increasing number of people expressing some stress over the 'quirkiness' of the API recently, I decided to finally get to it. It's been about an 8 or 9 hour ordeal, which is why I was really good at procrastinating :dancing_men:.

I do already have some things in mind for a 2.x makeover, but that's far into the future and is contingent on the evolution of color-convert specifically.

Without further adieu, here are all of the changes. Keep in mind this is a complete re-write with a pretty good portion of the API being compatible with the 0.x releases.

The Fun Parts (new stuff, fixes, etc.)

• (Closes #56) Completely immutable API.
• (Fixes #42) All color models from color-convert are supported (using .<model-name>()). Try it yourself!

Color(0xFF0000).rgb().hsl().lab().hwb().xyz().cmyk().ansi256().rgb().toString()

Yes, this does mean that portion of the API has changed. Please see the migrations section below.

• Main Color class now has swizzle-able model constructors (e.g. Color.cmyk(10, 20, 30, 40), Color.rgb([15, 67, 200]), etc.).
• No longer performs conversion for every model on every single operation - smaller footprint and faster computation times. Not entirely sure why we were doing this to begin with, but whatever.
• (Fixes #79) Constructor now supports non-string hexadecimal RGB instantiation
• (Fixes #87) .toString() now returns a color string.
• Added HCG-specific getters/setters.
• (Fixes #42) Added XYZ/Lab getters/setters.
• (Fixes #83, #57, #93) Added a .round() function that takes a number of places (default is 0) to round the internal values to. The modified .string() and .percentString() methods also take this parameter, and those methods default to 1. See notes below.
• (Fixes #82) Several API clarifications. See Migrations section below.

As well, bumping the dependencies fixes #74.

The Not-So-Fun Parts (migration)

• Everything is immutable. There isn't a single fix for this if you (ab)used this library earlier on - you'll most likely be tweaking several touch points. It's for the greater good, I promise. If you already treated the library as immutable then you're probably good to go. Good tests are key here.
• All .model() functions (to convert to an object) must now be .model().object(). See notes below for justification.
• All .modelArray() functions must now be .model().array(). See notes below for justification.
• When using the .object() method, alpha values are now .alpha instead of .a so as to not conflict with Lab.
• If you used the internal properties of the object instead of getters, you'll need to.. not do that anymore :) Use the respective model calls (.rgb(), .hsl(), etc.) paired with .array() - this is because we don't store every single model in the object at once, but simply the last worked-with model.
• .whiteness() / .blackness() -> .white() / .wblack() (note the w prefix).

I want to explain this one because it doesn't feel 'great' but I felt like it needed to happen. We have had a couple of issues (#73 being the most definitive) that address problems with the assumed functionality of the methods.

I chose to remove the -ness from the names because I didn't want them being interpreted as a characteristic of the color, but instead a more concrete, 'absolute' (if you will) property of a specific color model (akin to .cyan(), .red(), .hue(), etc.).

The w prefix was chosen for both objective and subjective reasons: it objectively conflicts with CMYK's .black(), and HWB subjectively isn't used as much as CMYK is (please let me know if this is an abhorrently wrong assumption). Further, we have another example of the API doing this that nobody has complained about since I took over - .saturationl() and .saturationv() for the HSV and HSL models.

Also, since this seems like a good place to mention it - in lieu of something like .lightnessab() for the Lab model, I just stuck with .l(). In the future, I hope to have something a little more consistent, but for now this works.

• Constructors with specialized keys (such as .red, .green and .blue for RGB instead of .r, .g. and .b) were removed. If this is a huge problem, please let me know. For clarity, this means you can no longer instantiate with Color({red: 10, green: 100, blue: 150}) but instead must use Color({r: 10, g: 100, b: 150}).
• The model getter methods (e.g. .rgb(), .hsl(), .keyword()) no longer act as setters. Since everything is immutable now, such functionality is useless and only creates more overhead. Please use the Color() constructor directly, or use the new 'static' methods (functions) such as Color.rgb() directly.
• (Closes #67, #46) .clone() was removed since all objects are immutable. Just pass objects directly. If you really need a new copy of an object, use Color(otherColorObject).
• rgbaString() was removed. If you really need a string that forces the alpha value, please let me know and I can add something into the API. Otherwise, use .rgbString() and if the alpha is anything but 100% then it will include it.
• The specialized .xxxString() methods should move to .xxx().string() calls. In the case you need the RGB percent string, you may still use .percentString() - it will automatically convert to the RGB model. For instance, if you used .hslString(), you would now call .hsl().string().
• .clearer() -> .fade(), because "clearer" is not at all what I thought it was personally and the API is already kind of confusing (I thought clearer meant more saturated).
• .toJSON() now returns the current model's representation. If you absolutely need RGB, tack on .rgb(). This shouldn't affect many people, if any.
• Values no longer normalize (round) when getting objects or arrays. Call .round() first. If you are seeing crazy long decimals, this is why. I wanted to be sensitive to the scientific community that is using this library to perform more mathematically sensitive operations instead of approximate stuff for web users. Most people won't have a problem with this since most people use the CSS strings.
• (Fixes #24) Initializing a Color object with a hue-based model (hsl, hwb, etc.) performs a rotation on the value instead of clamping it to 0-360. This is in-line with the .hue() getter/setter and I believe it to be the correct functionality to begin with.
• .greyscale() -> .grayscale() - if you think we should have both, please let me know :)
• (Closes #86) .saturation() -> .saturationl() (to match .saturationv())

Some Notes

So why the extra three characters for things like .hslString() -> .hsl().string()? Two reasons - one, you can now snap colors to another model if necessary. For example, if I wanted to snap a color to the nearest ANSI 256 color, I can do Color(123, 44, 220).ansi256().rgb().object(); two, the dependencies (e.g. color-string) have pretty good parity with the model names used in color-convert, and color-convert has evolved a bit since the 0.x releases of color to a point where we can intelligently include most models, and can future-proof new models just by updating color-convert in color's package.json.

Further, a lot of these changes are due to the internal object no longer holding every single conversion possible. color-convert now supports quite a lot of conversion routes and maintaining all of them here was impractical, messy and tedious.

As mentioned earlier, another win is that you're going to save quite a bit of processing time, so applications that are doing things like color manipulation on images and whatnot should benefit greatly by switching to 1.x.

Next Steps

After this PR is approved by the community and merged, it will be published as 1.0.0.

After that, there will be a few efforts moving forward:

• Tests (of course) - I noticed comprehensive tests are lacking, and a test makeover would be beneficial in its own right.
• More transformations, and more clarity as to what those transformations are.
• Color scheme support (#44)
• Color space support (maybe)

I think the first thing that should be tackled now that we will have a slightly cleaner code base is to figure out some of the hairy naming that is going on here. I would love to hear some ideas about this (feel free to drop as many tickets as you'd like) - I have some of my own, but I don't always have the best ideas!

Feedback!

I need feedback on this as I am not a primary user of this library (admittedly I use color-convert more than color proper) so I want to make sure the users of this library are satisfied before I merge it in. There are a lot of opinionated changes in here that I have included based on all of the tickets and pull requests I've received.

Another thing I'd like to point out - this library is edge-case hell. Making decisions that benefitted all users, use cases, and color models, elegantly and without a ton of overhead, was incredibly difficult. I've attempted this rewrite probably 4 or 5 times now, ultimately scrapping it and trying again a month or two later.

If you have any strong feelings, or even not-so-strong feelings, please let me know. I'd love to know what could be done better.

Obligatory CC list: // @MoOx @sindresorhus @kevinsuttle @mattbasta @xml @huan086 @ooflorent @mindjuice @wmira @lapanoid @ZuBB @iamstarkov @stevemao @ericclemmons @igl @dliv

Thanks everybody!

Making Color objects immutable would result in a leaner API:

// Mutable
const red = Color('#ee1100')
const darkerRed = red.clone().darken(.2)
const lighterRed = red.clone().lighten(.2)

// Immutable
const red = Color('#ee1100')
const darkerRed = red.darken(.2)
const lighterRed = red.lighten(.2)

Hi there!

First of all I would like to excuse for test case that is not as simple as it should be.

I have next code

        ...
        //var baseColor = Color('#73FF73');
        var gtColor = Color('#FF7400');
        var ltColor = Color('#004DFF');
        var colors = { '0.00': 'rgb(255,255,255)' };

        this.getDepDataSet().forEach(function(item) {
            if (typeof colors[item.index] !== 'undefined') {
                return;
            }

            var value = item.number;
            var otherColor = value > 1 ? gtColor : ltColor;
            var weight = (value > 1 ? (value - 1) : (1 - value)) * 3;
            //var resultColor = baseColor.clone().mix(otherColor, weight);
            var resultColor = Color('#73FF73').mix(otherColor, weight);
            colors[item.index] = resultColor.rgbString();
        });
        ...

Code above produces a set of colors that are used in table coloring. With this code I get a right colors that I am expect (lets call them 'correct'). See 1st pic. When I use code that is commented I get wrong colors (see 2nd pic). In both cases same set of data is used

Currently the hex converter simply ignores the alpha value if the color is of rgba format. The PR resolves the issue.

Related to Do we already have argb hex string converter

In my node REPL ([email protected], [email protected]):

[temp (master)]$ node
> var Color = require('color');
undefined
> new Color('#ffffff').whiteness(5).hexString()
'#FF0D0D'
> 

That doesn't seem right to me.

Hi. This came up when I tried to do this:

const color = Color(baseColor)
  .mix(Color(hoverColor), values.hover)
  .mix(Color(activeColor), values.active)
  .mix(Color(errorColor), values.error);

values is an object that contains 0 to 1 values for the hover, active, and error state which are animated. My thought was that if you start with the baseColor and "mix" the others in with 0 weight I would be left with the base color. Then as the weights animated to 1 I would end up with the full state color.

Turns out that's not what happens, a weight of 0 overwrites the original color while 1 will keep it and use none of the passed in color. I've looked at the code and documentation you cited as the source of the function and it makes sense now.

In the original code it's a function, not a method on an object. So when you write mix(black, white, 0.1);. You read that as "mix black into white by 10%". Contrast that with this module where the mix function is a method on a color object. When you write white.mix(black, 0.1) it is more natural to read it as "starting with white, mix in black by 10%".

You could argue that it's just me being biased towards reading the .mix method as "mix in" when I should have read it as "mix into". My counter to that would be that all of the other alteration methods (.whiten, .blacken, .fade, etc) return the original value when you pass 0 as the amount you want to alter them by. .mix on the other hand will return same things only when 1 is passed in. Also of note is that one of the examples in the README file is this: color.mix(Color("yellow"), 0.3) // cyan -> rgb(77, 255, 179) which is the result you get from my alterations but is not the value you'll get with the current mix function.

In conclusion, I know that could simply write my code as

const color = Color(errorColor)
  .mix(Color(activeColor), values.error)
  .mix(Color(hoverColor), values.active)
  .mix(Color(baseColor), values.hover);

but that is WAY more difficult to parse than the example I gave at the start.

In this change I...

• Switched the colors in mix method
• Updated the mix tests
• Added tests for 25% and 75% mixes
• Bumped the version to 2.0.0 (breaking change)

Hi, color team. This lib is great, and seems to work normally... except on any version of the color black.

On black, if I try to lighten it, nothing changes. lighten(0.5) and whiten(0.5) fail completely on black, where they work fine on other colors, or on grey. And darken() works fine on white. It's just black that fails. (And I'm baffled by the results of lightness(0.5), but that might be more a question of my understanding. :-)

negate() works, and converts it to white. alpha(0.5) works.

mix() also seems to work on black.

I've tried hard to test this thoroughly. You can see a series of experiments on this Tonic, and you can manipulate the 'source' color to see the varying results: https://tonicdev.com/xmlilley/testing-color-lib

Please let me know if I'm somehow just misunderstanding either color-theory or the API. It's certainly possible. If nothing else, this behavior is at least violating the principle-of-least-surprise for me. :-)

Is this project active, and are you taking PR's for the current branch, or only for your 1.0 milestone?

Hi! I want this lib to be accessible via just a script tag so I've added a webpack-build. I haven't changed where the 'main' is pointing out, so require('color') will still be delivering index.js from the root of the package, but at the same time one would be able to access the lib via https://npmcdn.com/color/standalone_dist/color.min.js (and also via cdnjs, cdnjs/cdnjs#6800).

error node_modules/color/index.js: Unexpected token: name (_FF_FF) in file node_modules/color/index.js at 64:20. Error: Unexpected token: name (_FF_FF) in file node_modules/color/index.js at 64:20 at /Users/user/app/node_modules/metro-transform-worker/src/index.js:279:15 at Generator.next () at asyncGeneratorStep (/Users/user/app/node_modules/metro-transform-worker/src/index.js:146:24) at _next (/Users/user/app/node_modules/metro-transform-worker/src/index.js:168:9) at /Users/user/app/node_modules/metro-transform-worker/src/index.js:175:7 at new Promise () at /Users/user/app/node_modules/metro-transform-worker/src/index.js:164:12 at minifyCode (/Users/user/app/node_modules/metro-transform-worker/src/index.js:289:17) at Object. (/Users/user/app/node_modules/metro-transform-worker/src/index.js:569:40) info Run CLI with --verbose flag for more details. Command PhaseScriptExecution failed with a nonzero exit code

This library is really weird, mutability is causing me so many problems :(

But anyway, why this piece of code:

var color = require("color")
const b = color('#fff')
console.log(b.clone().mix(color('black')).hexString())

returns "#000000" ? it doesn't make any sense. If i remove clone() it works.

In fact:

console.log(color('#ffffff').clone())

Color
values: Object
alpha: 1
cmyk: [0, 0, 0, 0]
hsl: [0, 0, 0]
hsv: [0, 0, 0]
hwb: [0, 0, 0]
rgb: [0, 0, 0]

Hi,

Calling the color node module seems to break things in io.js and possibly npm 2.13.0. This is before I even try to use any of its functionality, just calling the module like so triggers the following error:

import Color from 'color'

I tried uninstalling and reinstalling it. Here is the error message:

ERROR in ./~/color/~/color-string/~/color-name/index.json
Module parse failed: /Users/~/git/xyz-repo/node_modules/color/node_modules/color-string/node_modules/color-name/index.json Line 2: Unexpected token :
You may need an appropriate loader to handle this file type.
| {
|   "aliceblue": [240, 248, 255],
|   "antiquewhite": [250, 235, 215],
|   "aqua": [0, 255, 255],
 @ ./~/color/~/color-string/color-string.js 2:17-38

Any help on this would be really appreciated it.

How to reproduce:

1. Open Sandbox
2. Check the console output

Current behavior

• For invalid rgb input (E.g. "rgb(277,0,0)"), r is rounded to the nearest valid value 255 and a value is returned.
• For invalid hex input (E.g. "#p10000"), an exception is thrown.

Expected behavior

Exceptions are expected to be thrown for all invalid inputs (i.e. for input that can't be turned into an equivalent color).

Extra info

Probablly related to this code: https://github.com/Qix-/color-string/blob/4daceef89391f28eba415d043bbd1163c8f19a8c/index.js#L128

When for example the alpha is set to 1 in an RGBA object return, the alpha/a variable disappears. I know this is a part of the design of the library though this means that there has to be extra code checking to make sure the variable isn't missing before using it. Can there be an option where the RGBA object keeps it's alpha/a variable? Thanks!

These manipulators for those, who will making dark and light themes, without color changes itself (doesn't change hue and chroma value). It useful for invert light into dark themes, and revert. Added 3 operators: lightenHcg, darkenHcg and negateHcg (now tinten, shaden, negateTones).

.light-theme {
  $mod: 0; /* dark font */
  color: hcg(240, 50, $mod);
}

.dark-theme {
  $mod: 100; /* light font */
  color: hcg(240, 50, $mod);
  filter: invert(100%) hue-rotate(180deg); /* same effect */ 
}

The docs give examples of various forms of Color.rgb() with 3 arguments, but never give an example of specifying an alpha value in the constructor. They do give the example Color('#7743CE').alpha(0.5) but nothing like Color.rgb([0x77, 0x43, 0xCE, 0.5]).

Also, there are no examples of construction from non-RGB color spaces. Color.hsl(200,80,70) works but is never mentioned.

Certain colors (I've only seen this in HSL so far) don't round correctly when calling string().

For example:

var Color = require('color');

var pink = Color('#FF08C2');
console.log(pink.hsl().string()); // 'hsl(314.79999999999995, 100%, 51.6%)'