A javascript color library to easily handle color variations to create dynamic color theme, to offer custom colors to your users.

• Introduction
• In short
• Brief introduction to color theory
  • Color properties
  • Color value
  • Colors harmonies
  • The HSL solution
• The Color object
• Creation of a Color
• Creation of a child Color
• Constructor parameters
• Parameter object details
• Properties
• Methods

Color allows to easily handle color manipulation with access to each aspect of it (hue, saturation, light, alpha). For exemple, you can dynamically set tint, tone and shade of a color by changing only the saturation or light properties.

A main Color can be a reference, linked by a other Color with some offset in saturation for exemple. That allows you to create a dynamic color theme through a set of linked Color which will adapt to any change from the main one.

A simple HSL model :

const {hue, saturation, light, alpha} = {360, 90, 70, 100} // A soft red

// Named properties :
const mainColor = new Color({hue, saturation, light, alpha});
// Or direct values :
const mainColor = new Color(hue, saturation, light, alpha);

References to link Color through a dynamic theme :

const darkOffsets = { light: -30 };
const darkMainColor = new Color({ ref: mainColor, offsets: darkOffsets });

// mainColor as reference, with a -30 offset in light :
darMainColor.toHsl(); // "hsl(360, 90%, 40%)"

mainColor.hue = 30; // If the main color change,
// All dependant Color will change accordingly :
darkMainColor.toHsl(); // "hsl(30, 90%, 40%)"

Simple offset or callback to fine-tune the relation between colors :

const offsets = {
	saturation: sat => sat / 2,
	alpha: -30,
};
const shadowColor = new Color(mainColor, alpha);
// Callback give access to the reference property value
shadowColor.toHsl(); // "hsla(30, 45%, 30%, 70%)"

Use the .set() method to update a parent color with a color input value :

// 1 : Offer custom colors to your users :
const colorInput = document.querySelector("input[type='color']");

colorInput.addEventListener("change", event => {
	const userColor = event.currentTarget.value;

	// 2 : Color accept CSS color string to initialize directly from inputs :
	mainColor.set(userColor); // Update your main color with .set()

	// 3 : Update your CSS with the new values :
	document.body.style.setProperty("--main-color", mainColor.toHsl());
	document.body.style.setProperty("--secondary-color", secondaryColor.toHsl());
	document.body.style.setProperty("--background-color", backgroundColor.toHsl());
});

The color wheel.

Colors can be describe by 3 properties : Hue, intensity and value.

Hue :

The pure color value on which the color is based.
From 0 to 360°, it indicates the color position on the color wheel.
This pure color is visible at full intensity and a neutral value (no black or white added).

Intensity :

The saturation of the color :
It describe the brightness or dullness of the color.
Intensity is highest with the pure color (hue).
Intensity is low when a color is dull, tends to a gray.

Value :

Describes the degree of lightness or darkness in color.

There are 3 ways to change the value of a color, Tint, tone and shade :

Tint :

Hue + white.
A pure color with only white added, also called pastel.
A Tint lightens the color, but it remains exactly the same color, only a paler version.

Shade :

Hue + black.
The opposite of tint, a pure color with only black added.

Tone :

Hue + gray.
A color with gray, to tone down the intensity of it : Toned colors are generally considered more pleasing to the eye. They are complex, subtle and sophisticated.

Harmonies are the combination of colors in an aesthetically pleasing way. Here are 7 color schemes to help you choose colors that go well together, to make your design look natural and professional.

Monochromatic Uses different tones, shades and tints of one color.
Analogous Uses colors that are next to each other on the color wheel.
Complementary Uses colors that are opposite each other on the wheel.
Split Complementary Uses the colors on either side of the complement.
Triadic Uses 3 colors that are equally spaced on the color wheel, forming a triangle.
Tetradic Also called double complementary, uses 2 complementary pairs, forming a rectangle on the wheel.
Squared Uses 4 colors that are equally spaced on the color wheel, 2 complementary pairs, forming a square on the wheel.

The HSL color system handle color with 3 properties : Hue, Saturation and Light, based on colors properties from color theory (instead of a thechnical view like the RGB system), which make color manipulation very easy. This is how designer think about color, so it's important that developers can apply this vision easily.

Hue :

The pure color value on which the color is based.
From 0 to 360°, it indicates the color position on the color wheel.
This pure color is directly visible with a 100% saturation and a light at 50%. We can easily obtain colors hamonies from hue : Take the main color, add 180°, and you get the complementary color for exemple.

Saturation :

The Intensity of the color :
- At 100% we have the pure color.
- At 0%, it's gray. The gray value will depend on the light property.
This is how we get tone variation.

Light :

The brightness of the color :
- At 50% we have the pure color.
- With more light, we obtain a brighter color, until pure white at 100%. This is how we get tint variation.
- With less light, we obtain a darker color, until pure black at 0%. This is how we get shade variation.

const hue = 360; // red
const saturation = 90;
const light = 70;
const alpha = 100;

new Color(hue, saturation, light, alpha);

Will create a Color object folowing the HSL system.

const properties = {
	hue: 240,
	saturation: 100,
	light: 30,
	alpha: 80,
};
new Color(properties);
new Color({ properties, offsets: {} });

Color can take an object as parameter, with named properties to ease the DX.

new Color("#ff0000");
new Color("rgb(255, 0, 0)");
new Color("hsl(360, 100, 50)");

Color accept CSS color string as parameter.
All Color properties will be create from the CSS value, every arguments following the string will be ignored.

new Color();

Every parameters are optional.

Default values :

• hue = 0, 0 deg on the color wheel is pure red.
• saturation = 100, 100% : Pure color.
• light = 50, 50% : Pure color (0% is black, 100% is white).
• alpha = 100, 100% : No transparency.

An other Color object can be passed as parameter : It will be the reference to keep a dynamic link to its properties.

const mainColor = new Color(360, 90, 70);

// mainColor as reference, with a -30 offset in light :
const darkMainColor = new Color(mainColor, { light: -30 });

darMainColor.toHsl(); // "hsl(360, 90%, 40%)"

The new instance inherit the properties of the reference. Offset properties allows a dynamic shift of the reference value : If the parent Color change, the child inherit the change as well.

mainColor.hue = 30; // If the main color change,
// All dependant Color will change accordingly :
darkMainColor.toHsl(); // "hsl(30, 90%, 40%)"

new Color(ParentColor, { saturation: -30, light: +20 });

Will create a child Color from the ParentColor object with optional offsets in hue, saturation, light or alpha.

new Color({ ref: ParentColor, offsets: { saturation: -30, light: +20 } });

Color can take an object as parameter, with named properties to ease the DX.

new Color(ParentColor);

Offsets are optional.

Default values :

• hueOffset = 0, No shift from the reference hue.
• saturationOffset = 0, No shift from the reference saturation.
• lightOffset = 0, No shift from the reference light.
• alphaOffset = 0, No shift from the reference alpha.

// Simple offset, added to the reference value :
childColor.saturationOffset = 10;

// Or callback :
childColor.lightOffset = lightRef => lightRef / 2;

childColor.alphaOffset = alphaRef => {
	// take the reference value,
	if (alphaRef > 50) return alphaRef - 20;
	return alphaRef / 2;
	// return a new value.
};

Simple offset or callback to fine-tune the relation between colors.

childColor.saturation = 50; // Set a fixed value on a child Color

A property can be set directly on the child Color. This value will be fixed, independent of the reference value.

Color (Optional)

The 1^st parameter accepts 4 types of value :

• Hue : A number for the color position on the color wheel. It will still work if the number is outside the usual position (between 0 and 360°), or a CSS <angle> string ( deg | turn | rad | grad ), that will determine the hue value.

  For exemple -120 will have the same result as 240 (-120 + 360 = 240 : same position on the wheel).

• CSS color string : A hexadecimal ( "#ff0000" ), RGB ( "rgb(255, 0, 0)" ) or HSL ( "hsl(0, 100, 50)" ) color format that will determine the hue, saturation, light and alpha values.

  See details

  Hexadecimal color format accepts 3 (4 with alpha) or 6 (8 with alpha) hexadecimal values.

  RGB format accepts direct value or %. It accepts comma, space or forward slash for value separator. Optional alpha value is accepted for both rgb and rgba.

  HSL format accepts direct value, or < angle > value ( deg | turn | rad | grad ), for the hue value, and % for other values. It accepts comma, space or forward slash for value separator. Optional alpha value is accepted for both hsl and hsla.

  All next parameters will be ignored.

• Color object : An other Color object can be passed, to be the reference on which this new Color will be based.

  All next parameters become offset to shift from this reference.

• Object : An object with a collection of named properties to easily set any option of the Color object in one go. See the parameter object details section to know more.

  All next parameters will be ignored.

Saturation / Offsets (Optional)

The 2^nd parameter set the saturation value, or the offsets for a child Color :

• If the 1^st parameter is a hue value : this one have to be a number and will set the saturation value (100 by default : Pure color).
• If the 1^st parameter is a Color object : this one have to be a object that will set the offsets values (0 by default for all offsets : No offset).
  See details

  The offsets object accepts 4 properties : hue, saturation, light and alpha, that will sets the offset for the corresponding color value (See offsets parameter object ).
  Each is optionnal, and accept :
  - A number, which will be add to the parent value to obtain the child value,
  - Or a callback, which will get the parent value as parameter, and have to return a number to be the child value.
• If the 1^st parameter is a CSS color string or a object : this one will be ignored.

Light (Optional)

The 3^rd parameter set the light value :

• If the 1^st parameter is a hue value : this one have to be a number and will set the light value ( 50 by default: Pure color ).
• For all other case : this one will be ignored.

Aplha (Optional)

The 4^th parameter set the alpha (transparency) value :

• If the 1^st parameter is a hue value : this one have to be a number and will set the alpha value ( 100 by default : No transparency ).
• For all other case : this one will be ignored.

If the 1^st parameter is a object, all Color properties can be set in one go :

• Every properties are optionnal.
• If a color property is set both directly ( { hue } ) and in a collection of properties object ( { properties: { hue } } ), the value in the set will take priority and the direct property will be ignored.
• Idem for offsets.
• parentColor is a alias for ref to assign a parent Color. If both are put, parentColor will be ignored.

{
   // Color properties :
   hue : number | <angle> string,
   saturation: number,
   light: number,
   alpha: number,

   // Collection of color properties :
   properties: {
      hue : number | <angle> string,
      saturation: number,
      light: number,
      alpha: number,
   }

   // CSS color string (hexa, rgb or hsl) :
   css: string,

   // Color reference :
   ref: Color,
   parentColor: Color, // Alias

   // Offsets :
   hueOffset : number | (parentHue) => number,
   saturationOffset: number | (parentSaturation) => number,
   lightOffset: number | (parentLight) => number,
   alphaOffset: number | (parentAlpha) => number,

   // Collection of offsets :
   Offsets: {
      hue : number | (parentHue) => number,
      saturation: number | (parentSaturation) => number,
      light: number | (parentLight) => number,
      alpha: number | (parentAlpha) => number,
   }
}

If the 1^st argument is a Color object to set the parent reference, the 2^nd argument is a object of offsets :

{
   // Offsets :
   hue : number | (parentHue) => number,
   saturation: number | (parentSaturation) => number,
   light: number | (parentLight) => number,
   alpha: number | (parentAlpha) => number,
}

Color.hue

Get / set the hue value of the color (its position on the color wheel) :

If this value is set on a child Color, the parent hue value will be ignored.

• Getter Color.hue : 0 ⩽ number < 360 .
  • If Color is a child with no own hue value: hue will return the value of the parent with the offset applied.
  • Default value : 0 (red).
• Setter Color.hue = number | css <angle> string :
  • If null or undefined, assignment will be ignored.
  • No need to format the number between 0 and 360, it will still work outside the usual position.

    For exemple -120 will have the same result as 240 (-120 + 360 = 240 : same position on the wheel).

Color.saturation

Get / set the saturation value of the color (its intensity) :

If this value is set on a child Color, the parent saturation value will be ignored.

• Getter Color.saturation : 0 ⩽ number ⩽ 100 .
  • If Color is a child with no own saturation value, saturation will return the value of the parent with the offset applied.
  • Default value : 100 (pure color).
• Setter Color.saturation = number :
  • Every number below 0 will set the saturation to 0.
  • Every number above 100 will set the saturation to 100.
  • If null or undefined, assignment will be ignored.

Color.light

Get / set the light value of the color :

If this value is set on a child Color, the parent light value will be ignored.

• Getter Color.light : 0 ⩽ number ⩽ 100 .
  • If Color is a child with no own light value, light will return the value of the parent with the offset applied.
  • Default value : 50 (pure color).
• Setter Color.light = number :
  • Every number below 0 will set the light to 0.
  • Every number above 100 will set the light to 100.
  • If null or undefined, assignment will be ignored.

Color.alpha

Get / set the alpha value of the color (transparency) :

If this value is set on a child Color, the parent alpha value will be ignored.

• Getter Color.alpha : 0 ⩽ number ⩽ 100 .
  • If Color is a child with no own alpha value, alpha will return the value of the parent with the offset applied.
  • Default value : 100 (no transparency).
• Setter Color.alpha = number :
  • Every number below 0 will set the alpha to 0.
  • Every number above 100 will set the alpha to 100.
  • If null or undefined, assignment will be ignored.

Color.hueOffset

Get / set the offset applied to the hue value of the Color parent's (to obtain this Color hue value).

If Color don't have a parent, offset will be ignored.

• Getter Color.hueOffset : number | function.
  • Default value : 0 (no change from parent value).
• Setter Color.hueOffset = number | function.
  • If hueOffset is a number, the hue value will be Parent.hue + Child.hueOffset.
  • If hueOffset is a function, the Parent.hue value will be given as parameter, and the function must return the wanted hue value.
  • If null or undefined, assignment will be ignored.

Color.saturationOffset

Get / set the offset applied to the saturation value of the Color parent's (to obtain this Color saturation value).

If Color don't have a parent, offset will be ignored.

• Getter Color.saturationOffset : number | function.
  • Default value : 0 (no change from parent value).
• Setter Color.saturationOffset = number | function.
  • If saturationOffset is a number, the saturation value will be Parent.saturation + Child.saturationOffset.
  • If saturationOffset is a function, the Parent.saturation value will be given as parameter, and the function must return the wanted saturation value.
  • If null or undefined, assignment will be ignored.

Color.lightOffset

Get / set the offset applied to the light value of the Color parent's (to obtain this Color light value).

If Color don't have a parent, offset will be ignored.

• Getter Color.lightOffset : number | function.
  • Default value : 0 (no change from parent value).
• Setter Color.lightOffset = number | function.
  • If lightOffset is a number, the light value will be Parent.light + Child.lightOffset.
  • If lightOffset is a function, the Parent.light value will be given as parameter, and the function must return the wanted light value.
  • If null or undefined, assignment will be ignored.

Color.alphaOffset

Get / set the offset applied to the alpha value of the Color parent's (to obtain this Color alpha value).

If Color don't have a parent, offsets will be ignored.

• Getter Color.alphaOffset : number | function.
  • Default value : 0 (no change from parent value).
• Setter Color.alphaOffset = number | function.
  • If alphaOffset is a number, the alpha value will be Parent.alpha + Child.alphaOffset.
  • If alphaOffset is a function, the Parent.alpha value will be given as parameter, and the function must return the wanted alpha value.
  • If null or undefined, assignment will be ignored.

Color.ref

Get / set the parent Color reference (use to get color properties through offsets).

A Color reference cannot be deleted, only update by a new one.

• Getter Color.ref : Color.
  • Default value : undefined ( no parent Color ).
• Setter Color.ref = Color.
  • If null or undefined, assignment will be ignored.

Color.parent

A alias for the .ref property.

A Color reference cannot be deleted, only update by a new one.

• Getter Color.parent : Color.
  • Default value : undefined ( no parent Color ).
• Setter Color.parent = Color.
  • If null or undefined, assignment will be ignored.

.toHsl()

Return the HSL value of the color in CSS compatible string.

const mainColor = new Color(360, 90, 70);
mainColor.toHsl(); // "hsl(360, 90%, 70%)"

mainColor.alpha = 50;
mainColor.toHsl(); // "hsla(360, 90%, 70%, 50%)"

.toRgb()

Return the RGB value of the color in CSS compatible string.

const mainColor = new Color(360, 90, 70);
mainColor.toRgb(); // "rgb(247, 110, 110)"

mainColor.alpha = 50;
mainColor.toRgb(); // "rgba(247, 110, 110, 0.5)"

.toHex()

Return the hexadecimal value of the color in CSS compatible string.

const mainColor = new Color(360, 90, 70);
mainColor.toHex(); // "#f76e6e"

mainColor.alpha = 50;
mainColor.toHex(); // "#f76e6e80"

.set()

Act like a new Color() constructor to update a Color with new values without breaking the reference for the child Color like new Color() would.
Difference with the constructor : if any property in the .set() method is missing, the original will be kept and not set to the default value.

const color = new Color({
	properties: { hue: 180, light: 35 },
	offsets: { saturation: sat => sat / 2 },
});

color.set(); // No changes.
color.set({ hue: 0 }); // Only the hue property will change.
// All color properties will be set from the CSS string :
color.set("#ff0000"); // The offsets will remain unchanged.

.reset()

Act like a new Color() constructor to update a Color with new values without breaking the reference for the child Color like new Color() would.
Every missing property in the .reset() method will be reset to the default value, except the ref ( parent Color ) wich can only be replace by a other Color or remain.

const color = new Color({
	properties: { hue: 180, light: 35 },
	offsets: { saturation: sat => sat / 2 },
});

color.reset(); // Back to default values, no offsets.
// hue property will be 123 :
color.reset({ hue: 123 }); // All other set to default values.
// All color properties will be set from the CSS string :
color.reset("#ff0000"); // The offsets will reset to 0.

.setColorProperties()

Set all color properties ( hue, saturation, light, alpha) at once.
Only the provided values will be update, if any property in the .setColorProperties() method is missing, the original will be kept and not set to the default value.
Accept only a object with color properties { hue?, saturation?, light?, alpha? }.

const color = new Color({ hue: 180, light: 35 });

color.setColorProperties(); // No changes.
color.setColorProperties({ hue: 123 }); // Only hue will change.

.setColorOffsets()

Set all color offsets ( hue, saturation, light, alpha) at once.
Only the provided values will be update, if any property in the .setColorOffsets() method is missing, the original will be kept and not set to the default value.
Accept only a object with color offsets { hue?, saturation?, light?, alpha? }.

const darkChild = new Color(parent, { saturation: -20, light: -20 });

darkChild.setColorOffsets(); // No changes.
darkChild.setColorOffsets({ alpha: -30 }); // Add a alpha offset.