The Color Object

The first part to many Color.js operations is creating a Color object, which represents a specific color, in a particular colorspace, and has methods to convert the color to other spaces or to manipulate it.. There are many ways to do so.

Passing a CSS color string

let color = new Color("slategray");
let color2 = new Color("hwb(60 30% 40% / .1)");
let color3 = new Color("color(display-p3 0 1 0)");
let color4 = new Color("lch(50% 80 30)");

You can even use CSS variables, optionally with a DOM element against which they will be resolved (defaults to document root):

new Color("--color-blue");
new Color("--color-green", document.querySelector("h1"));

Color space and coordinates

Internally, every Color object is stored this way, so this is the most low level way to create a Color object.

let lime = new Color("sRGB", [0, 1, 0], .5); // optional alpha
let yellow = new Color("P3", [1, 1, 0]);
new Color("lch", [50, 30, 180]);

// Capitalization doesn't matter
new Color("LCH", [50, 30, 180]);

// Color space objects work too
new Color(Color.spaces.lch, [50, 30, 180]);

The exact ranges for these coordinates are up to the color space definition.

You can also pass another color, or an object literal with spaceId/space, coords, and optionally alpha properties:

let red = new Color({space: "lab", coords: [50, 50, 50]});
let red = new Color({spaceId: "lab", coords: [50, 50, 50]});
let redClone = new Color(red);

Color object properties

The three basic properties of a color object are its color space, its coordinates, and its alpha:

let color = new Color("deeppink");; // Color space object === Color.spaces.srgb;
color.spaceId; // same as

However, you can also use color space ids to get the color's coordinates in any other color space:

let color = new Color("deeppink");

In fact, you can even manipulate the color this way!

let color = new Color("deeppink");
color.lch[0] = 90;

Named coordinates are also available:

let color = new Color("deeppink");; = .5;

Note that unless we explicitly change a color's color space, it remains in the same color space it was when it was created. Manipulating coordinates of other color spaces do not change a color's space, it is just internally converted to another space and then back to its own. To convert a color to a different color space, you need to change its space or spaceId properties. Both accept either a color space object, or an id:

let color = new Color("srgb", [0, 1, 0]); = "p3";
color; = Color.spaces.prophoto;

Often, we want to keep our color intact, but also convert it to another color space, creating a new Color object. This is exactly what is for:

let color = new Color("srgb", [0, 1, 0]);
let colorP3 ="p3");

Sometimes, when converting to a color space with a smaller gamut, the resulting coordinates may be out of gamut. You can test for that with color.inGamut() and get gamut mapped coordinates with color.toGamut():

let funkyLime = new Color("p3", [0, 1, 0]);
let boringLime ="srgb");

Note that color.toString() returns gamut mapped coordinates by default. You can turn this off, via the {inGamut: false} option. You can read more about gamut mapping in the Gamut mapping section.