Frontfire documentation

Color

Version 2.1.0

No search results

Bring colour to your life, precisely!

What?

The Color class provides colour conversion and computation functions. That includes conversions between different formats (HTML, CSS) and also colour spaces (RGB, HSL). And it has general tools like colour blending, inversion, lightness adjustment, greyscale conversion, descriptions and more.

As a result, Color is compact and easy to use, increasing the developer’s productivity and happiness. The minified and gzipped code is under 3 KiB. TODO: It is also fully covered by unit tests. (in work)

globe Please excuse the wild spelling of the word “colour”. While source code is generally expected to use US English spelling for consistency with existing APIs, this documentation uses British/int’l English spelling which becomes especially apparent on this page.

How?

Here are a few examples to show its usage and the results.

// Start with a Color let c = new Color("#ff0000"); /**#ff0000**/ // Convert to CSS c.toCSS() → "rgb(255, 0, 0)" c.toCSSHSL() → "hsl(0, 100%, 50%)" // Blend with other colour c = c.blendWith("blue", 0.75) → Color { r: 128, g: 0, b: 255 } ("purple") /**#8000ff**/ c.description() → "purple" c.description("de") → "lila" // Find a contrast foreground colour c.isDark() → true c.text() → Color { r: 255, g: 255, b: 255 } ("white") /**#ffffff**/ // Lighten up a bit c = c.lighten(0.5) → Color { r: 192, g: 128, b: 255 } ("light purple") /**#c080ff**/ // Convert to grey c.gray() → Color { r: 192, g: 192, b: 192 } ("silver") /**#c0c0c0**/

Where?

As a modern JavaScript library, this code is compatible with the following environments:

Earlier versions may work for a limited feature set. The vastly outdated Internet Explorer is explicitly incompatible with this code. Should you be stuck in the past for whatever reason, a transpiler like Babel and a few polyfills might help you out.

This library is released under the terms of the MIT licence. See the complete licence text in the code repository for details.

Documentation

This documentation lists all public members of the Color class. The available parameters are listed for each method, describing which of them are optional or alternative in which combination. The description explains the behaviour and parameter requirements. The return value is shown after the arrow.

A few examples further describe the usage and effect of a method. More comprehensive input and output of a method can be found in the separate test cases included in the source code.

Search

The members are categorised and can be searched (just type ahead). The search also uses aliases for many entries. Start the search text with an equals sign (=) to ignore aliases. Start the search text with the ^ sign to also only find names starting with the search term. Start the search text with the at sign (@) to search by source plugins. Press Escape to reset the search.

Constructor

Color

  • new Color(value) → Color
  • Color(…) → Color

Creates a new Color instance that represents the specified colour. The use of the new keyword is optional. The original format of the specified colour is preserved so it can be formatted back in the same format.

The following value formats are accepted:

  • Empty string (transparent)
  • "hex" (3/4/6/8 hex digits)
  • Any format supported by the browser:
    • "#rgb" (3 hex digits)
    • "#rgba" (4 hex digits)
    • "#rrggbb" (6 hex digits)
    • "#rrggbbaa" (8 hex digits)
    • "rgb(r, g, b)"
    • "rgb(r, g, b, a)"
    • "rgba(r, g, b)"
    • "rgba(r, g, b, a)"
    • "hsl(h, s, l)"
    • "hsl(h, s, l, a)"
    • "hsla(h, s, l)"
    • "hsla(h, s, l, a)"
    • "name" (web colour names as supported by the browser)
  • Number: 0xrrggbb
  • Number: 0xaarrggbb
  • Array: [r, g, b, a]
  • Object: { r, g, b, a }

Instance properties

a

  • a → Number

Gets or sets the alpha value. It must be in the range of 0 to 1.

b

  • b → Number

Gets or sets the blue component value. It must be in the range of 0 to 255.

g

  • g → Number

Gets or sets the green component value. It must be in the range of 0 to 255.

h

  • h → Number

Gets or sets the hue value. It must be in the range of 0 to 360.

l

  • l → Number

Gets or sets the lightness value. It must be in the range of 0 to 1.

r

  • r → Number

Gets or sets the red component value. It must be in the range of 0 to 255.

s

  • s → Number

Gets or sets the saturation value. It must be in the range of 0 to 1.

Update methods

These instance methods update colour component values after changes to the properties.

updateHSL

  • updateHSL() → this

Calculates the HSL components (h, s, l) from the RGB components (r, g, b) in the color object. After changing any of the HSL properties, the RGB properties are not updated automatically. Then this method needs to be called to update the RGB properties to match the HSL colour.

Note:
Most colour processing methods work primarily on the RGB components. They update the HSL components internally when necessary, but only if the h property is unset. As soon as the Color object contains HSL data, it is the caller’s responsibility to keep them updated. This means that you should always call updateHSL() after changing the RGB properties directly if the Color object also contains HSL data.

See also: Color.updateRGB()

updateRGB

  • updateRGB() → this

Calculates the RGB components (r, g, b) from the HSL components (h, s, l) in the color object. After changing any of the RGB properties, the HSL properties are not updated automatically. Then this method needs to be called to update the HSL properties to match the RGB colour.

Note:
Most colour processing methods work primarily on the RGB components. They update the HSL components internally when necessary. This means that you should always call updateRGB() after changing the HSL properties directly.

See also: Color.updateHSL()

Formatting methods

These instance methods return the colour value in a desired format.

toArray

  • toArray() → Array

Converts a color object into an array with [r, g, b, a].

new Color("#ff0000").toArray() → [255, 0, 0] new Color("hsl(120, 100%, 50%, 0.5)").toArray() → [0, 255, 0, 128]

See also: Color.toString(), Color.toCSS(), Color.toCSSHSL(), Color.toHTML(), Color.toIntARGB()

toCSS

  • toCSS() → String

Formats a color object into a CSS rgb() string.

new Color("#ff0000").toCSS() → "rgb(255, 0, 0)" new Color("hsl(120, 100%, 50%, 0.5)").toCSS() → "rgb(0, 255, 0, 0.5)"

See also: Color.toString(), Color.toCSSHSL(), Color.toHTML(), Color.toIntARGB(), Color.toArray()

toCSSHSL

  • toCSSHSL() → String

Formats a color object into a CSS hsl() string.

new Color("#ff0000").toCSSHSL() → "hsl(0, 100%, 50%)" new Color("hsl(120, 100%, 50%, 0.5)").toCSSHSL() → "hsl(120, 100%, 50%, 0.5)"

See also: Color.toString(), Color.toCSS(), Color.toHTML(), Color.toIntARGB(), Color.toArray()

toHTML

  • toHTML() → String

Formats a color object into an HTML hexadecimal string.

new Color("#ff0000").toHTML() → "#ff0000" new Color("hsl(120, 100%, 50%, 0.5)").toHTML() → "#00ff0080"

See also: Color.toString(), Color.toCSS(), Color.toCSSHSL(), Color.toIntARGB(), Color.toArray()

toIntARGB

  • toIntARGB() → Number

Converts a color object into an integer number like 0xAARRGGBB.

new Color("#ff0000").toIntARGB() → 0xff0000 new Color("hsl(120, 100%, 50%, 0.5)").toIntARGB() → 0x8000ff00

See also: Color.toString(), Color.toCSS(), Color.toCSSHSL(), Color.toHTML(), Color.toArray()

toString

  • toString() → String

Formats the color in the format it was originally parsed from.

new Color("#ff0000").toString() → "#ff0000" new Color("hsl(120, 100%, 50%, 0.5)").toString() → "hsl(120, 100%, 50%, 0.5)"

See also: Color.toCSS(), Color.toCSSHSL(), Color.toHTML(), Color.toIntARGB(), Color.toArray()

Processing methods

These instance methods perform colour computations and return the result. The current object instance is not modified by any of these methods.

alpha

  • alpha(value) → Color

Returns a color with a changed alpha value between 0 (transparent) and 1 (opaque). The component values are returned unchanged.

blendByHueWith

  • blendByHueWith(…) → Color

An alias of blendWithHSL().

blendWith

  • blendWith(other, ratio) → Color
  • blendWith(other, ratio, includeAlpha) → Color

Returns a blended color with the specified ratio from 0 (no change) to 1 (only other color). The r, g, b and a values are blended separately.

If the includeAlpha parameter is unset or false, the a property of the returned object is unset. If it is true, the alpha value is blended like the other components. The alpha values are never used to affect the blend ratio itself.

The returned Color instance will have RGB components set. The HSL components are only updated if the were set before.

See also: Color.blendWithHSL()

blendWithHSL

  • blendWithHSL(other, ratio) → Color
  • blendWithHSL(other, ratio, includeAlpha) → Color
  • blendWithHSL(other, ratio, includeAlpha, largeArc) → Color

Returns a blended color with the specified ratio from 0 (no change) to 1 (only other color). The h value is blended on the short or long path around the circle. The s, l and a values are blended normally.

If the includeAlpha parameter is unset or false, the a property of the returned object is unset. If it is true, the alpha value is blended like the other components. The alpha values are never used to affect the blend ratio itself.

By default, the hue is blended on the shortest path around the colour hue circle. This may also wrap at 360 degrees. When using for colour gradients, this will produce a shorter gradient. If the largeArc parameter is set to true, the hue is blended on the longer path. When using for colour gradients, this will produce a longer gradient with more intermediate hues.

The returned Color instance will have RGB and HSL components set.

See also: Color.blendWith()

complement

  • complement() → Color

Returns the complementary color. The alpha value is returned unchanged.

The returned Color instance will have RGB and HSL components set.

See also: Color.invert()

darken

  • darken(factor) → Color

Returns a color that is darker by the factor between 0 (unchanged) and 1 (black). The alpha value is returned unchanged.

The returned Color instance will have RGB and HSL components set.

See also: Color.lighten()

description

  • description() → String
  • description(language) → String

Returns a simple description of the color. The colour does not need to match exactly one specification. The description is rather inaccurate and works with fixed ranges of hue, saturation, lightness and alpha.

If no language is specified, the language is determined by the lang attribute of the document root element (<html>). Currently, the following languages are supported. Specifying a different language will return English names.

  • de: German
  • en: English
  • en-CA, en-US: English (North-American)

Example colour descriptions (in English) are:

  • black
  • red
  • dark purple
  • light green
  • pale light blue
  • brown
  • light gray
  • transparent

gray

  • gray() → Color

Returns the grayscale color by perceived brightness. The alpha value is returned unchanged.

The returned Color instance will have RGB components set. The HSL components are only updated if the were set before.

See also: Color.isDark()

invert

  • invert() → Color

Returns the inverted (negative) color. The alpha value is returned unchanged.

The returned Color instance will have RGB components set. The HSL components are only updated if the were set before.

See also: Color.complement()

isDark

  • isDark() → Boolean

Returns a value indicating whether the specified color is dark.

See also: Color.text(), Color.gray()

lighten

  • lighten(factor) → Color

Returns a color that is lighter by the factor between 0 (unchanged) and 1 (white). The alpha value is returned unchanged.

The returned Color instance will have RGB and HSL components set.

See also: Color.darken()

text

  • text() → Color

Returns white or black as suitable for the text color over the background color. The alpha value is set to 1.

The returned Color instance will have RGB components set. The HSL components are only updated if the were set before.

See also: Color.isDark()