Spectrum class

The Spectrum class is a fundamental component of the library, representing colors in HEX, HSL, HWB, and RGB color spaces. Spectrum instances can be used with various methods to convert between color spaces and access individual color channels.

// Create a Spectrum instance from a hex color value
const spectrum = new Spectrum('hex', '#FF0000');

spectrum.rgb; // { r: 255, g: 0, b: 0, a: 1 }
spectrum.hsl; // { h: 0, s: 1, l: 0.5, a: 1 }
spectrum.hwb; // { h: 0, w: 0, b: 0, a: 1 }
spectrum.hex; // "#ff0000"

Constructor

new Spectrum('colorSpace', value);

Parameters

Name	Type	Description
colorSpace	'hex' | 'hsl' | 'hwb' | 'rgb' | CssNamedColor	The color space of the input value
value	string | Array<string | number> | undefined	The color value. The format depends on the color space. See details.

Value

The allowed input formats for each color space are as follows:

For hexcolor space:

• The input can be only a string value with optional preceding #.
• It also accepts shorthand HEX notation and alpha channel. See examples.

For hsl, hwb, and rgb color spaces an input can be:

• A string of space-separated or comma-separated values.
• An array of values in a valid format.

For hsl, the format is [hue, saturation, lightness, opacity].

For hwb, the format is [hue, whiteness, blackness, opacity].

For rgb, the format is [red, green, blue, opacity].

You can also use a CSS named color as a first parameter. For example, 'red' or 'blue'. In this case, you should not provide a second parameter. See examples.

Valid formats

For hsl:

Value	Format	Example
hue	string | number without a unit	180, '180'
saturation	Percentage string or a decimal point number in range [0; 1]	'25%', 0.25
lightness	Percentage string or a decimal point number in range [0; 1]	'50%', 0.5
opacity	Percentage string or a decimal point number in range [0; 1]	'90%', 0.9

For hwb:

Value	Format	Example
hue	string | number without a unit	180, '180'
whiteness	Percentage string or a decimal point number in range [0; 1]	'25%', 0.25
blackness	Percentage string or a decimal point number in range [0; 1]	'50%', 0.5
opacity	Percentage string or a decimal point number in range [0; 1]	'90%', 0.9

Note

If the sum of whiteness and blackness is 100% or greater, the color is normalized to a shade of gray, and a warning is displayed in the console.

For rgb:

Value	Format	Example
red	string | number	255, '255'
green	string | number	'90', 90
blue	string | number	'30', 30
opacity	Percentage string or a decimal point number in range [0; 1]	'90%', 0.9

Examples

With hex

new Spectrum('hex', '#AE2127');
new Spectrum('hex', 'ae2127');
new Spectrum('hex', '236aa9cc');

new Spectrum('hex', '#eee');
new Spectrum('hex', 'EEE');
new Spectrum('hex', '#ea3c');

With hsl

new Spectrum('hsl', '180 0.3 0.9');
new Spectrum('hsl', '180, 0.3, 0.9');
new Spectrum('hsl', '180, 0.3, 0.9, 20%');
new Spectrum('hsl', '180 30% 90% 0.2');

new Spectrum('hsl', [180, 0.3, 0.9]);
new Spectrum('hsl', [180, 0.3, 0.9, 0.2]);
new Spectrum('hsl', [180, '30%', '90%', '20%']);
new Spectrum('hsl', [180, '30%', '90%', 0.2]);

With hwb

new Spectrum('hwb', '180 0.3 0.25');
new Spectrum('hwb', '180, 0.3, 0.25');
new Spectrum('hwb', '180, 0.3, 0.25, 20%');
new Spectrum('hwb', '180 30% 25% 0.2');

new Spectrum('hwb', [180, 0.3, 0.25]);
new Spectrum('hwb', [180, 0.3, 0.25, 0.2]);
new Spectrum('hwb', [180, '30%', '25%', '20%']);
new Spectrum('hwb', [180, '30%', '25%', 0.2]);

With rgb

new Spectrum('rgb', '255 255 255');
new Spectrum('rgb', '255, 255, 255');
new Spectrum('rgb', '255, 255, 255, 20%');
new Spectrum('rgb', '255 255 255 0.2');

new Spectrum('rgb', [255, 255, 255]);
new Spectrum('rgb', ['255', '255', '255']);
new Spectrum('rgb', [255, 255, 255, 0.2]);
new Spectrum('rgb', ['255', '255', '255', '20%']);
new Spectrum('rgb', ['255', '255', '255', '0.2']);

With CSS named color

new Spectrum('red');
new Spectrum('blue');
new Spectrum('lightseagreen');

Static class methods

Apart from the constructor, you can also create a new Spectrum instance: using the class methods fromHslObj, fromHwbObj, and fromRgbObj. These methods allow you to create a new instance from the objects returned by hsl, hwb, and rgb instance properties or by providing a custom object of your own.

Caution

The objects passed to fromHslObj(), fromHwbObj(), and fromRgbObj() methods must be numeric values. Thus, valid value for the saturation property is only s: 0.7. Setting it as s: '70%' will result in an error.

fromHslObj()

Creates a new instance of the Spectrum class using an HSL object as an input. All properties of an HSL object are required.

Usage

Spectrum.fromHslObj({ h: 8, s: 0.5, l: 0.41, a: 0.9 }: HslObj);

Parameters

Name	Type	Description
hslObj	HslObj	An object representing the HSL color values with properties h (hue), s (saturation), l (lightness), and a (alpha).

Returns Spectrum instance.

Examples

const color = Spectrum.fromHslObj({ h: 180, s: 0.5, l: 0.75, a: 1 });
console.log(color.hsl); // { h: 180, s: 0.5, l: 0.75, a: 1 }

const green = new Spectrum('rgb', [0, 255, 0]);
const greenCopy = Spectrum.fromHslObj(green.hsl);

---

fromHwbObj()

Creates a new instance of the Spectrum class using an HWB object as an input. All properties of an HWB object are required.

Usage

Spectrum.fromHwbObj({ h: 8, w: 0.35, b: 0.2, a: 0.9 }: HwbObj);

Parameters

Name	Type	Description
hwbObj	HwbObj	An object representing the HWB color values with properties h (hue), w (whiteness), b (blackness), and a (alpha).

Returns Spectrum instance.

Examples

const color = Spectrum.fromHwbObj({ h: 180, w: 0.35, b: 0.2, a: 1 });
console.log(color.hwb); // { h: 180, w: 0.35, b: 0.2, a: 1 }

const green = new Spectrum('rgb', [0, 255, 0]);
const greenCopy = Spectrum.fromHwbObj(green.hwb);

---

fromRgbObj()

Creates a new instance of the Spectrum class using an RGB object as an input. All properties of an RGB object are required.

Usage

Spectrum.fromRgbObj({ r: 255, g: 0, b: 0, a: 1 }: RgbObj);

Parameters

Name	Type	Description
rgbObj	RgbObj	An object representing the RGB color values with properties r (red), g (green), b (blue), and a (alpha).

Returns Spectrum instance.

Examples

const color = Spectrum.fromRgbObj({ r: 255, g: 130, b: 60, a: 0.8 });
console.log(color.rgb); // { r: 255, g: 130, b: 60, a: 0.8 }

const red = new Spectrum('rgb', [255, 0, 0]);
const redCopy = Spectrum.fromRgbObj(red.rgb);

Instance properties

hex

The hex property retrieves the hexadecimal representation of the color.

Returns: string.

const color = new Spectrum('hex', '412ED1');
color.hex; // #412ed1

---

hsl

The hsl property retrieves the HSL object of the color.

Returns HslObj.

const color = new Spectrum('hsl', '180 70% 50% 82%');
color.hsl; // { h: 180, s: 0.7, l: 0.5, a: 0.82 }

---

hwb

The hwb property retrieves the HWB object of the color.

Returns HwbObj.

const color = new Spectrum('hwb', '180 25% 30% 82%');
color.hwb; // { h: 180, s: 0.25, l: 0.3, a: 0.82 }

---

rgb

The rgb property retrieves the RGB object of the color.

Returns RgbObj.

const color = new Spectrum('rgb', '230 90 115 82%');
color.rgb; // { r: 230, g: 90, b: 115, a: 0.82 }

---

alpha

The alpha property retrieves the alpha channel value of the color.

Returns: number.

const color = new Spectrum('rgb', '230 90 115 82%');
color.alpha; // 0.82

---

red

The red property retrieves the red channel value of the color.

Returns: number.

const color = new Spectrum('rgb', '230 90 115 82%');
color.red; // 230

---

green

The green property retrieves the green channel value of the color.

Returns: number.

const color = new Spectrum('rgb', '230 90 115 82%');
color.green; // 90

---

blue

The blue property retrieves the blue channel value of the color.

Returns: number.

const color = new Spectrum('rgb', '230 90 115 82%');
color.blue; // 115

---

hue

The hue property retrieves the hue value of the color.

Returns: number.

const color = new Spectrum('hsl', '180 70% 50% 82%');
color.hue; // 180

---

saturation

The saturation property retrieves the saturation value of the color.

Returns: number.

const color = new Spectrum('hsl', '180 70% 50% 82%');
color.saturation; // 0.7

lightness

The lightness property retrieves the lightness value of the color.

Returns: number.

const color = new Spectrum('hsl', '180 70% 50% 82%');
color.lightness; // 0.5

whiteness

The whiteness property retrieves the whiteness value of the color.

Returns: number.

const color = new Spectrum('hwb', '180 25% 30% 82%');
color.whiteness; // 0.25

blackness

The blackness property retrieves the blackness value of the color.

Returns: number.

const color = new Spectrum('hwb', '180 25% 30% 82%');
color.blackness; // 0.3

Instance methods

toHslString()

Returns a string formatted as a CSS hsl() color function.

Returns: string.

const spectrum = new Spectrum('hsl', [180, 0.5, 0.85, 0.4]);
spectrum.toHslString(); // hsl(180 50% 85% / 0.4)

---

toHwbString()

Returns a string formatted as a CSS hwb() color function.

Returns: string.

const spectrum = new Spectrum('hwb', [180, 0.32, 0.5, 0.4]);
spectrum.toHwbString(); // hwb(180 32% 50% / 0.4)

---

toRgbString()

Returns a string formatted as a CSS rgb() color function.

Returns: string.

const spectrum = new Spectrum('rgb', [255, 130, 60, 0.4]);
spectrum.toRgbString(); // rgb(255 130 60 / 0.4)