Repository navigation
Releases
v0.7.1
Fixed a regression that broke space accessors (e.g. color.oklch.l instead of color.get("oklch.l")) in bundlers. (reported by @GodTamIt in #759 and fixed by @LeaVerou in #760).
Also a bugfix: ix steps using deltaEMethod inconsistently by @TimonLukas in #740
New Contributors
- @TimonLukas made their first contribution in #740
Full Changelog: v0.7.0...v0.7.1
v0.7.0
Two pre-releases in the making, this release brings a lot of new color spaces, a new gamut mapping method, a smarter display(), a leaner dist/, and a pile of fixes.
If you have been following along with the v0.7.0-alpha.1 and v0.7.0-alpha.2 pre-releases, the only things new to you are in Changes since v0.7.0-alpha.2.
⬇️ Over 240 million downloads! 🤯
Color.js has now been downloaded over 240 million times on npm!
As a reminder, we have an Open Collective that you can fund directly.
If your company depends on Color.js in any way, it is in your best interest to ensure its future is sustainable.
🚨 Breaking changes
These are unlikely to break things for the majority of users, but theoretically could if you were doing weird stuff with Color.js 😜.
We cleaned up dist/ quite a bit with this release and re-evaluated what actually needs to be there:
- Removed the pre-built ESM bundles. We now only generate bundles for CJS and global builds. ESM exports point directly at the corresponding files in
src/. This also fixes a dual-instance bug where importing fromsrc/vs. the package root could yield differentColorregistries (by @LeaVerou in #739). - Removed the minified
.min.*files from the package, since packages are moving away from providing these and minification is becoming a consumer concern (by @LeaVerou in #741).
For those of you that have been importing files directly from colorjs.io, removed files now redirect to the versions still there (e.g. colorjs.io/dist/color.min.js and colorjs.io/dist/color.js now both redirect to colorjs.io/src/color.js), so your code should continue to work.
New color spaces
- 🆕 Gamut-relative (OK)LCH spaces (by @LeaVerou in #736) Ever tried to use (OK)LCH and kept struggling with the irregularity of the gamut shape? You can now have your cake and eat it too, as we introduced gamut-relative versions of these spaces, where
c = 1is the most colorful in-gamut color at a given lightness and hue so you never have to worry about getting out of gamut! These new spaces are:oklch-p3,oklch-srgb,oklch-rec2020,lch-p3,lch-srgb,lch-rec2020.- All six are built on a new general
GamutRelativeColorSpaceclass that can be easily used to generate such color spaces for any gamut and color space, as long as there is a coordinate to reduce that is guaranteed to get you in-gamut. - Note that this loses you some of the perceptual uniformity of the original spaces, but it is a tradeoff that is often worth it for the convenience of staying in-gamut. After all, perceptual uniformity only applies in-gamut anyway.
- 🆕
hsl-p3andhsl-rec2020: HSL syntax, wider gamut (by @LeaVerou in #735) - 🆕 The experimental Helmlab family of perceptual color spaces:
helmlab-metric(Helmlab MetricSpace),helmgen(HelmGen), andhelmgenlch(HelmGenLCh) (by @Grkmyldz148)
Other new features
- 🆕 Smarter
display()fallback When a color isn't natively supported by the browser,display()now stays as close as possible to the original color: it walks up the base color space chain (closest first) and uses the first supported ancestor, preserving the color's gamut (e.g. anhsl-p3color falls back tocolor(display-p3 …)rather thanlab()) instead of always jumping to the widest default. Adds an opt-indisplaySpacesoverride onColorSpace, a parameterizablesupports(), and aDisplayOptionsinterface (by @LeaVerou in #738) - 🆕 New gamut mapping method:
raytrace. It traces a ray to the gamut boundary instead of binary-searching, automatically determining the RGB gamut and linear space from the space object (by @facelessuser) - 🆕 New deltaE method:
deltaEHelmlab, based on the Helmlab model (by @Grkmyldz148) - 🆕 Added a
collapseoption toserialize()/Color.toString()to disable collapsing for hex colors (e.g. keep#ff0066instead of collapsing it to#f06) (by @MysteryBlokHed in #712)
For plugin/library/tooling authors
Exposed more internals, so you never have to duplicate stuff that Color.js already knows about:
- Expose transformation matrices via
ColorSpace.MColor spaces now expose the transformation matrices they use internally through a newMproperty, so consumers can reuse them instead of duplicating the data. Matrices for RGB spaces can also be supplied via the genericMoption (by @LeaVerou in #749) - Matrix algebra utilities Added
inv(matrix inversion) andsolveto the math utilities, so external libraries are no longer required when developing new color spaces (by @facelessuser) - Polar spaces declare their hue coordinate via the new
ColorSpace#hueIdandColorSpace#hueIndex, so code that needs the hue angle can look it up from the space definition instead of assuming it is namedh(by @svgeesus in #754)
Changes since v0.7.0-alpha.2
Bug fixes
- Premultiplied interpolation is now correct in polar spaces (by @svgeesus in #754). Premultiplication used to multiply every coordinate by alpha, including the hue angle, which is meaningless. Per CSS Color 4 § 13.3, the hue angle is never premultiplied, and un-premultiplication must not divide by a zero or
nonealpha. Concretely:- The hue angle is skipped when premultiplying and when undoing it, and is found from the space definition, so spaces whose hue coordinate isn't called
h(e.g.hzin Jzczhz) now interpolate correctly too. - Un-premultiplying by an alpha of
0leaves the coordinates untouched instead of dividing by zero and producingNaN. - A
nonealpha is carried forward from the other color before premultiplying, per CSS Color 4 § 13.2, and staysnoneonly if both colors are missing it. Previously anonealpha premultiplied every coordinate to zero, turning the color black.
- The hue angle is skipped when premultiplying and when undoing it, and is found from the space definition, so spaces whose hue coordinate isn't called
helmgenlchnow serializes ascolor(--helmgenlch …)instead of the invalidcolor(helmgenlch …), by giving it thecssIdits sibling spaces already had (by @Grkmyldz148, fixes #730)- Gamut surface threshold updated, and the values for 32 bit vs 64 bit are now documented:
1e-12gives better resolution for 64 bit values, while1e-6is the right choice for 32 bit (by @facelessuser in #752)
For contributors
- Added an AI-assisted contributions section to CONTRIBUTING.md, spelling out our expectations for PRs written with AI assistance (by @Grkmyldz148, closes #723)
Other bug fixes & performance
These landed in the pre-releases:
- Preserve a subclass's own
toBase/fromBasewhen options omit them, instead of clobbering prototype methods withundefined(by @LeaVerou) - Add the
typesfield back topackage.json(by @MysteryBlokHed in #714) - Avoid implied color space dependencies for procedural usage, so consumers no longer need to manage them manually (by @aduth in #734)
- Reduce a CAM16 calculation in the worst-case scenario (by @facelessuser)
- Fix HCT tests and related calculations (by @facelessuser)
- Fix the CI install command after the lockfile removal (by @MysteryBlokHed in #744)
Full Changelog: v0.6.1...v0.7.0
New Contributors
- @Grkmyldz148 made their first contribution (Helmlab color spaces and
deltaEHelmlab) - @aduth made their first contribution in #734
v0.7.0-alpha.2
⬇️ Over 220 million downloads! 🤯
This is the second pre-release of v0.7.0, with several new color spaces, and other improvements.
For the changes in v0.7.0-alpha.1, see the previous release notes.
As a reminder, we recently started an Open Collective that you can fund directly.
If your company depends on Color.js in any way, it is in your best interest to ensure its future is sustainable.
🚨 Breaking changes
These are unlikely to break things for the majority of users, but theoretically could if you were doing weird stuff with Color.js 😜.
We cleaned up dist/ quite a bit with this release and re-evaluated what actually needs to be there:
- Removed the pre-built ESM bundles. We now only generate bundles for CJS and global builds. ESM exports point directly at the corresponding files in
src/. This also fixes a dual-instance bug where importing fromsrc/vs. the package root could yield differentColorregistries (by @LeaVerou in #739). - Removed the minified
.min.*files from the package, since packages are moving away from providing these and minification is becoming a consumer concern (by @LeaVerou in #741).
For those of you that have been importing files directly from colorjs.io, removed files now redirect to the versions still there (e.g. colorjs.io/dist/color.min.js and colorjs.io/dist/color.js now both redirect to colorjs.io/src/color.js), so your code should continue to work.
Improvements
New features
- 🆕 New color spaces (by @LeaVerou in #736) Ever tried to use (OK)LCH and kept struggling with the irregularity of the gamut shape? You can now have your cake and eat it too, as we introduced gamut-relative versions of these spaces, where
c = 1is the most colorful in-gamut color at a given lightness and hue so you never have to worry about getting out of gamut! These new spaces are:oklch-p3,oklch-srgb,oklch-rec2020,lch-p3,lch-srgb,lch-rec2020.- All six are built on a new general
GamutRelativeColorSpaceclass that can be easily used to generate such color spaces for any gamut and color space, as long as there is a coordinate to reduce that is guaranteed to get you in-gamut. - Note that this loses you some of the perceptual uniformity of the original spaces, but it is a tradeoff that is often worth it for the convenience of staying in-gamut. After all, perceptual uniformity only applies in-gamut anyway.
- 🆕 Smarter
display()fallback When a color isn't natively supported by the browser,display()now stays as close as possible to the original color: it walks up the base color space chain (closest first) and uses the first supported ancestor, preserving the color's gamut (e.g. anhsl-p3color falls back tocolor(display-p3 …)rather thanlab()) instead of always jumping to the widest default. Adds an opt-indisplaySpacesoverride onColorSpace, a parameterizablesupports(), and aDisplayOptionsinterface (by @LeaVerou in #738)
For plugin/library/tooling authors
Exposed more internals, so you never have to duplicate stuff that Color.js already knows about:
- Expose transformation matrices via
ColorSpace.MColor spaces now expose the transformation matrices they use internally through a newMproperty, so consumers can reuse them instead of duplicating the data. Matrices for RGB spaces can also be supplied via the genericMoption (by @LeaVerou in #749) - Matrix algebra utilities Added
inv(matrix inversion) andsolveto the math utilities, so external libraries are no longer required when developing new color spaces (by @facelessuser)
Bug fixes & performance
- Preserve a subclass's own
toBase/fromBasewhen options omit them, instead of clobbering prototype methods withundefined(by @LeaVerou) - Fix the CI install command after the lockfile removal (by @MysteryBlokHed in #744)
Full Changelog: v0.7.0-alpha.1...v0.7.0-alpha.2
v0.7.0-alpha.1
⬇️ Over 200 million downloads! 🤯
This is the first pre-release of v0.7.0, with several new color spaces, and other improvements.
As a reminder, we recently started an Open Collective that you can fund directly.
If your company depends on Color.js in any way, it is in your best interest to ensure its future is sustainable.
New features
- 🆕 New color spaces
hsl-p3andhsl-rec2020color spaces: HSL syntax, wider gamut (by @LeaVerou in #735) - 🆕 New color spaces Add the experimental Helmlab family of perceptual color spaces:
helmlab-metric(Helmlab MetricSpace),helmgen(HelmGen), andhelmgenlch(HelmGenLCh) (by @Grkmyldz148) - 🆕 New deltaE method :
deltaEHelmlab, based on the Helmlab model (by @Grkmyldz148) - 🆕 New gamut mapping method:
raytrace. It traces a ray to the gamut boundary instead of binary-searching, automatically determining the RGB gamut and linear space from the space object (by @facelessuser) - 🆕 Added a
collapseoption toserialize()/Color.toString()to disable collapsing for hex colors (e.g. keep#ff0066instead of collapsing it to#f06) (by @MysteryBlokHed in #712)
Bug fixes & performance
- Add the
typesfield back topackage.json(by @MysteryBlokHed in #714) - Avoid implied color space dependencies for procedural usage, so consumers no longer need to manage them manually (by @aduth in #734)
- Reduce a CAM16 calculation in the worst-case scenario (by @facelessuser)
- Fix HCT tests and related calculations (by @facelessuser)
Full Changelog: v0.6.1...v0.7.0-alpha.1
New Contributors
- @Grkmyldz148 made their first contribution (Helmlab color spaces and
deltaEHelmlab) - @aduth made their first contribution in #734
v0.6.1
v0.6.0
This has taken a while and three pre-releases, but we wanted to make sure we got everything right.
This is likely to be the last v0.x release, as Color.js is certainly mature enough to go to v1 in the next major version.
Speaking of maturity…
⬇️ Over 100 million downloads! 🤯
Color.js has now been downloaded over 114 million times on npm!
The rate of increase is still accelerating, currently at 3.5 million downloads per week!
We even had to automate updating the number in our README so we could have a chance to keep up (thanks @MysteryBlokHed!).
Making Color.js sustainable
You may have noticed we removed ads from the Color.js website a while back.
While Carbon ads were the good kind of ads (relevant, not intrusive), it was not really worth it, they barely made enough to cover costs like the domain name etc.
Instead, we have started an Open Collective that you can fund directly.
If your company depends on Color.js in any way, it is in your best interest to ensure its future is sustainable.
Once there are enough sponsors, we plan to feature them prominently on our website and README, so if you want to be among the first ones to get your name in there, now’s the chance:
Breaking changes
There are a number of breaking changes in this release, but they should only negatively affect some pretty specialized use cases.
null instead of NaN to represent none values
As announced in v0.5.0, we have now switched to using null instead of NaN to represent none values (naturally occurring when converting achromatic colors to certain color spaces).
Not only is null conceptually closer, but since CSS also now has a NaN value, this change allows us to represent it properly, using an actual NaN value.
NaN continues to be parsed (and becomes NaN in JS). Instead of being serialized as NaN (which is invalid in CSS), it is serialized as calc(NaN) which is a valid CSS coordinate. For roundtripping to work properly, this also means we now parse calc(NaN) as well. Slippery slope? We’ll see. 😁
(by @LeaVerou in cdf6f0d, @facelessuser in #476, @MysteryBlokHed in #530)
Programmatically detecting how none is represented
If you are working with any code that needs to handle Color instances/objects generically, without knowing which version of Color.js they come from, you can detect which value is being used and use that instead of a hardcoded null or NaN:
let noneCoord = new Color("rgb(none none none)").coords[0];
const NONE_VALUE = noneCoord?.valueOf() ?? noneCoord;Plain numbers instead of Number objects for coordinates
Previously, coordinates would be parsed into Number objects so they could retain metadata about their parsing. From this release onwards, they are plain number primitives, which results in both performance improvements, and improved DX for most cases.
Instead, parsing metadata is passed around as a separate object, and stored on Color instances under color.parseMeta. This happens automatically in the OOP API, but users need to explicitly opt-in when using the procedural API, since that is optimized for high performance use cases.
In addition, this metadata is now far more elaborate and can pretty much recreate the format parsed. Which brings us to…
Colors now reserialized in the format parsed
We heard you! This has been a longstanding pain point, and it is now fixed. If you’re parsing a hex color, it will be serialized back to a hex color by default. If you’re specifying your chroma in percentages, percentages you’ll get back. If for some reason, you’re parsing a legacy comma-separated color, lo and behold, you can modify it and get back a legacy comma-separated color without lifting a finger!
Caveats:
- This only happens automatically in the OOP API. The procedural API does not store parsing metadata by default as it’s optimized for speed, you need to pass a
parseMetaobject explicitly. - You can always override this by passing
format(orformat: "default") for the color space default, which gives you the previous behavior.
Other big improvements
New color spaces
- 🆕 OKHSL and OKHSV by @facelessuser (#469 #517)
- 🆕 OkLrab and OkLrCh by @facelessuser (#511)
- 🆕 Linear Rec2100 by @lloydk (#591)
More control over serialization
You can now specify a format from any color space in serialize()/color.toString() without having to convert the color to a different color space.
There is even a new function, ColorSpace.findFormat() to find a format that matches certain criteria across all registered color spaces.
Another big pain point was that the way Color.js did serialization made simple things easy (by having sensible defaults and a wide range of predefined formats) and complex things possible (by allowing entirely custom formats to be specified), but the in-between was not smooth at all: the moment you needed anything custom, the only way was to recreate a whole format, which is a UX antipattern.
Starting with this release, you can now specify a lot more granular options for serialization, without having to redefine a format:
coordswith an array of coord types (e.g.["<percentage>", "<number>[0, 100]", "<angle>"]). Anyundefinedvalues will just get the default type, so you can even do things like[, "<percentage>", ]to e.g. make OKLCh chroma a percentage without having to respecify the default type of any other coord.alphato control display and type of alpha:- Force alpha to be added even when it’s 100%:
alpha: true - Prevent alpha from being added, even when < 100%:
alpha: false - Format alpha as a percentage:
alpha: "<percentage>" - Do both 1 and 3:
alpha: {include: true, type: "<percentage>"}
- Force alpha to be added even when it’s 100%:
Switching from TypeScript types to JSDoc
You may have noticed that our API docs had not been great in the past. This is because we were describing types in .d.ts files, but documentation was in JSDoc comments. However (the otherwise lovely) Typedoc expects a single source of truth for both, which would mean either having untyped API docs, or API docs with only types. It also meant that we had to maintain Color.js’s pretty extensive API in two places, which did not scale.
With this release we went all in on JSDoc, thanks to @MysteryBlokHed’s monumental effort in #540.
For complex types, we are still using .d.ts files with the new JSDoc @import syntax so that JSDoc is still the source of truth (by @MysteryBlokHed and @lloydk in #686).
This does not affect you, whether you are consuming Color.js via TS or JS, types should still just work. You may, however, see better inline documentation!
Other Color.js Initiatives
Color Apps
We have also moved our Color apps (which also serve as Color.js demos) into their own repo and domain: apps.colorjs.io.
If you have links to these, there’s nothing to worry about: the old URL still works (it just redirects to the new one).
There is also a new app:
- Gamut mapping: Explores different gamut mapping algorithms
- Gamut mapping gradients by @jamesnw (#471)
These are rather esoteric, but they have been used in CSS Working Group research to help figure out what gamut mapping algorithm to use natively in CSS.
Color Palettes
Another experimental project under the Color.js umbrella is Color Palettes,
which aims to analyze designer-created color palettes in a variety of color spaces, as an attempt to understand how to generate them
and document what patterns are prominent.
You may (or may not) be surprised to find that they are not regular in any color space, not even perceptually uniform ones.
This project is still in its infancy (I would not even call it alpha), but we are excited about its potential.
Color Elements
You may have noticed our three experimental custom elements in the past — or maybe not, as they were very experimental and thus not featured very prominently.
These have now been split into a separate project, and a separate domain: elements.colorjs.io and expanded into a library of 10 web components for building color-related apps (the first library of its kind to our knowledge).
They are still very experimental, but way more polished than their previous state.
If you were referencing these from their previous URL, there is a redirect in place, but do note their tag names and API have changed.
Color Elements were originally developed for our own Color Apps and the Color Palettes project, so these projects also serve as demos for them.
Other changes
API changes
Color parsing & formatting
v0.6.0 Beta 2
v0.6.0-beta.2
Just one more quick beta to make sure all is smooth before we get stable v0.6.0 out!
⬇️ 90 million downloads!
Just a few days ago when we released v0.6.0-beta.1, Color.js had 80 million downloads.
We are now at 90 million downloads, and the rate of increase is still accelerating (currently at 3 million downloads per week).
In fact, we had to automate updating the number in our README so we could have a chance to keep up (thanks @MysteryBlokHed!)
As a reminder, we recently started an Open Collective so you can fund Color.js's development.
If your company depends on Color.js in any way, it is in your best interest to ensure its future is sustainable.
Changes from v0.6.0-beta.1
Improvements to types
- Bump TypeScript to v5.5 and in type definitions, replace
@typedefwith@importwhere relevant to improve DX and overall quality of generated.d.tsfiles (by @MysteryBlokHed and @lloydk in #686)
v0.6.0 Beta 1
We hear you, it’s been a while, and v0.6.0 is long overdue. Assuming any significant issues come up in this beta, we plan to release a stable v0.6.0 in 1-2 weeks or so.
⬇️ 84 million downloads!
Color.js is quickly becoming the de facto color handling library for JS:
it has now been downloaded over 84 million times on npm,
a number that is rapidly increasing, at the rate of nearly 3 million downloads per week!
As a reminder, we recently started an Open Collective so you can fund Color.js's development.
If your company depends on Color.js in any way, it is in your best interest to ensure its future is sustainable.
Changes
Note
This only includes the changes after v0.6.0 Alpha 1.
Check out the v0.6.0 Alpha 1 release notes for changes since 0.5.2
API changes for DX
- A common request has been a function that gracefully parses colors, without throwing if there is an error. This version adds exactly that:
tryColor()/Color.try()(by @LeaVerou in #664) - A common use case was to use the procedural API for tree-shaking and performance, but still import all color spaces that Color.js supports. This is now made much easier, through the new
spacesexport of/fnand the new/spacestop-level export. (by @LeaVerou in #663, with types by @MysteryBlokHed in #668) - New
/srcexport to import Color.js's source code directly (by @LeaVerou in #663, with types by @MysteryBlokHed in #668)
API changes for spec compliance
- Change
color(ictcp ...)toictcp(...)per CSS Color HDR (by @svgeesus in #646) - Change
color(jzazbz ...)tojzazbz(...), andcolor(jzczhz ...)tojzczhz(...)per CSS Color HDR (by @svgeesus in #647) - Unprefix
display-p3-linearsince it is now in CSS Color 4 (i.e.color(--display-p3-linear ...)→color(display-p3-linear ...)(by @svgeesus in c90fe38). Not a breaking change, as both are still supported. - Use gamma 2.40 for display-referred
rec2020; rename previous implementation as scene-referred--rec2020-oetf(by @svgeesus in #669) - Make HSL parsing spec-compliant (by @kleinfreund in #650)
Bug fixes
- CAM16 and HCT hues are now correctly set to
nullwhen chroma is near zero (by @facelessuser in #644) - Fix issues with creating custom color spaces (by @sidewayss and @LeaVerou in #628)
- Don't clamp negative values in Absolute XYZ D65 (by @svgeesus in #613)
- Adjust calculations in Jzazbz and fix Jzazbz and JzCzhz reference ranges (by @svgeesus in #634 #635)
- Ensure Prophoto and Rec2020 spaces handle negative values (by @lloydk in #640)
- Don't throw for unknown coords when space accessors are used (by @LeaVerou)
- In
toGamut(), better handle the case when JND equals 0 (by @facelessuser in #659)
Improvements to types
- Overload
multiplyMatricestypes and update implementation to pass all tests (by @epsilonError in #580 #631) - Fix CAM16 and HCT type errors (by @lloydk and @MysteryBlokHed in #622)
- Fix different types and type errors (by @lloydk in #642)
- Fix space accessor types to allow
null(by @lloydk) - Fix return types of the
darken()/lighten()functions on theColorclass (by @lloydk in #654)
For contributors
- Testsuite & test coverage improvements (by @epsilonError in #594 and @svgeesus in f02ce7f)
Full Changelog: v0.6.0-alpha.1...v0.6.0-beta.1
New Contributors
- @sidewayss made their first contribution in #628
- @kleinfreund made their first contribution in #650
- @drwpow made their first contribution in #656
v0.6.0 Alpha 1
⬇️ 10 million downloads! + Making Color.js sustainable
Color.js has now been downloaded over 10 million times on npm!
You may have noticed we removed ads from the Color.js website a while back.
While Carbon ads were the good kind of ads (relevant, not intrusive), it was not really worth it, they barely made enough to cover costs like the domain name etc.
Instead, we have started an Open Collective that you can fund directly.
If your company depends on Color.js in any way, it is in your best interest to ensure its future is sustainable.
Breaking changes
There are a number of breaking changes in this release, but they should only negatively affect some pretty specialized use cases.
null instead of NaN to represent none values
As announced in v0.5.0, we have now switched to using null instead of NaN to represent none values (naturally occurring when converting achromatic colors to certain color spaces).
Not only is null conceptually closer, but since CSS also now has a NaN value, this change allows us to represent it properly, using an actual NaN value.
NaN continues to be parsed (and becomes NaN in JS). Instead of being serialized to NaN (which is invalid in CSS), it is serialized to calc(NaN) which is a valid coordinate in CSS. For roundtripping to work properly, this also means we now parse calc(NaN) as well. Slippery slope? We’ll see. 😁
If you are working with any code that needs to handle Color instances/objects generically, without knowing which version of Color.js they come from, you can detect which value is being used and use that instead of a hardcoded null or NaN:
let noneCoord = new Color("rgb(none none none)").coords[0];
const NONE_VALUE = noneCoord?.valueOf() ?? noneCoord;(by @LeaVerou in cdf6f0d, @facelessuser in #476, @MysteryBlokHed in #530)
Plain numbers instead of Number objects for coordinates
Previously, coordinates would be parsed into Number objects so they could retain metadata about their parsing. From this release onwards, they are plain number primitives, which results in both performance improvements, and improved DX.
Instead, parsing metadata is passed around as a separate object, and stored on Color instances under color.parseMeta. This happens automatically in the OOP API, but users need to explicitly opt-in when using the procedural API, since that is optimized for high performance use cases.
In addition, this metadata is now far more elaborate and can pretty much recreate the format parsed. Which brings us to…
Colors now reserialized in the format parsed
We heard you! This has been a longstanding pain point, and it is now fixed. If you’re parsing a hex color, it will be serialized back to a hex color. If you’re specifying your chroma in percentages, percentages you’ll get back. If for some reason, you’re parsing a legacy comma-separated color, lo and behold, you can modify it and get back a legacy comma-separated color without lifting a finger!
Caveats:
- This only happens automatically in the OOP API. The procedural API does not store parsing metadata by default as it’s optimized for speed, you need to pass a
parseMetaobject explicitly. - You can always override this by passing
format(orformat: "default") for the color space default, which gives you the previous behavior.
Other big improvements
New color spaces
- 🆕 OKHSL and OKHSV by @facelessuser (#469 #517)
- 🆕 OkLrab and OkLrCh by @facelessuser (#511)
- 🆕 Linear Rec2100 by @lloydk (#591)
More control over serialization
You can now specify a format from any color space in serialize()/color.toString() without having to convert the color to a different color space.
And colorSpace.findFormat()
Another big pain point was that the way Color.js did serialization made simple things easy (by having sensible defaults and a wide range of predefined formats) and complex things possible (by allowing entirely custom formats to be specified), but the in-between was not smooth at all: the moment you needed anything custom, the only way was to recreate a whole format.
Starting with this release, you can now specify a lot more granular options for serialization, without having to redefine a format:
coordswith an array of coord types (e.g.["<percentage>", "<number>[0, 100]", "<angle>"]). Anyundefinedvalues will just get the default type, so you can even do things like[, "<percentage>", ]to e.g. make OKLCh chroma a percentage without having to respecify the default type of any other coord.alphato control display and type of alpha:- Force alpha to be added even when it’s 100%:
alpha: true - Prevent alpha from being added, even when < 100%:
alpha: false - Format alpha as a percentage:
alpha: "<percentage>" - Do both 1 and 3:
alpha: {include: true, type: "<percentage>"}
- Force alpha to be added even when it’s 100%:
Switching from TypeScript types to JSDoc
You may have noticed that our API docs had not been great in the past. This is because we were describing types in .d.ts files, but documentation was in JSDoc comments. However (the otherwise lovely) Typedoc expects a single source of truth for both, which would mean either having untyped API docs, or API docs with only types. It also meant that we had to maintain Color.js’s pretty extensive API in two places, which did not scale.
With this release we went all in on JSDoc, thanks to @MysteryBlokHed’s monumental effort in #540.
Other Color.js Initiatives
Color Elements
You may have noticed our three experimental custom elements in the past — or maybe not, as they were very experimental and thus not featured very prominently.
These have now been split into a separate project, and a separate domain: https://elements.colorjs.io and expanded into a library of 10 web components for building color-related apps (the first library of its kind to our knowledge).
They are still very experimental, but way more polished than their previous state, and there is heavy activity on the project.
If you were referencing these from their previous URL, there is a redirect in place, but do note their tag names and API has changed.
Color Apps
We have also moved our Color apps (which also serve as Color.js demos) into their own repo and domain: https://apps.colorjs.io
If you have links to these, there’s nothing to worry about: the old URL still works (it just redirects to the new one).
There is also a new app:
- Gamut mapping: Explores different gamut mapping algorithms (used in CSS WG research)
Color Palettes
Another experimental project under the Color.js umbrella is Color Palettes,
which aims to analyze designer-created color palettes in a variety of color spaces, as an attempt to understand how to generate them
and document what patterns are prominent.
You may (or may not) be surprised to find that they are not regular in any color space, not even perceptually uniform ones.
This project is still in its infancy (I would not even call it alpha), but we are excited about its potential.
Other changes
API
deltas()functions for getting coordinate/alpha differences between two colors in any color space. (@LeaVerou in #532)get()/set()/setAll()now support alpha as well (by @LeaVerou)- Hate seeing numbers like 0.30000000000000004 ? Our default number formatting now attempts to limit IEEE 754 precision issues.
- New DeltaE method:
OK2(believed to be more perceptually uniform) (by @svgeesus in #486) - Longer and undefined/same hues now have parity with CSS spec (thanks @facelessuser in #474)
- New
colorSpace.isUnboundedproperty (by @lloydk in #503) - Improved number parsing (by @facelessuser in #508)
parse()now clamps alpha as well, just like theColorconstructor (by @LeaVerou)- Functional API now also available with ESM exports (by @MysteryBlokHed in #606)
getAll()now supports an optionaloptionsparameter object withspaceandprecisionas possible keys (by @DmitrySharabin in #548)
Performance
- Matrix transform performance improvements by @lloydk that make certain conversions 3x faster (#585 #588)
Docs
- API docs that are actually up to date, using typedoc! You can find them in (by @LeaVerou with help from @MysteryBlokHed in #498 #497 #549)
- Updated color space diagram in https://colorjs.io/docs/spaces which is now dynamically generated via https://d2lang.com/ (by @LeaVerou)
- Demonstrate JND with colours that are different (by @perey in #538)
Website
- Avoid style recalculation of all elements on each scroll event. It makes the experience of working with the website much smoother (by @Inwerpsel in #592)
Bug fixes
- Object-oriented functions now work between different sources of Color.js (by @MysteryBlokHed in #605)
- Fix serialization of negative percentages (by @lloydk in #554)
- Handle negative square roots in a sane manner for Rec. 2100 HLG (by @facelessuser in #575)
- Do not use HSL normalized saturation and hue for certain spaces (by @facelessuser in #582)
- Avoid mutating arguments passed to the Color constructor (by @MysteryBlokHed in #603)
- Fix parsing 7-character hex colors (by @kleinfreund in #616)
- Fix parsing of percentage values for color spaces with coords that have a range property with a minimum value less than 0 (e.g. acescc) (by @lloydk in ...
v0.5.2
A fix for the same issue as the previous patch. This should fix compatibility with all TypeScript versions.
What's Changed
- [types] Remove module augmentation by @MysteryBlokHed in #566
Full Changelog: v0.5.1...v0.5.2