CssColors v0.2.0 CssColors

This module contains functions for creating and manipulating colors.

Color representations

Colors are represented as with either the RGB or HSL color models. Any function in this module can handle both representations, transforming it to the necessary representation as necessary.

All colors contain opacity data.

Parsing and printing

It can parse strings with any valid css color (hex, rgb, rgba, hsl, hsla and named colors).

Any color can be converted to a valid css string. Using to_string/1 will always return a string representation of the color using it’s current color model. You can transform it to the desired color model before stringifying it if desired.

iex> color = parse!("#fe3")
%CssColors.RGB{alpha: 1.0, blue: 51.0, green: 238.0, red: 255.0}
iex> to_string color
"#FFEE33"
iex> to_string hsl(color)
"hsl(55, 100%, 60%)"

Transformations

You can transform any attribute of the color.

Many common operations such as darken/2 are provided as helper functions. See also adjust/4 for the general function.

Examples:

iex> color = parse!("#123456")
%CssColors.RGB{alpha: 1.0, blue: 86.0, green: 52.0, red: 18.0}
iex> get_blue(color)
86.0
iex> get_lightness(color)
0.20392156862745098
iex> darken(color, 0.2)
%CssColors.HSL{alpha: 1.0, hue: 210.0, lightness: 0.0039215686274509665,
 saturation: 0.653846153846154}
iex> to_string lighten(color, 0.2)
"hsl(210, 65%, 40%)"
iex> to_string lighten(color, 0.2) |> transparentize(0.5)
"hsla(210, 65%, 40%, 0.5)"
iex> to_string lighten(color, 0.2) |> transparentize(0.5) |> rgb
"rgba(36, 103, 170, 0.5)"

Summary

Types

A representation of a color in any supported system

A representation of a color in hue, saturation, lightness and alpha

A representation of a color in red, green, blue and alpha

Functions

Adjusts any color attribute and returns the new color

Changes the hue of a color

Returns the complement of a color

Makes a color darker

Makes a color more saturated

Gets the :alpha property of the color

Get’s any color attribute from the color

Gets the :blue property of the color

Gets the :green property of the color

Gets the :hue property of the color

Gets the :lightness property of the color

Gets the :red property of the color

Gets the :saturation property of the color

Converts a color to grayscale

Returns a color with a hsl representation

Creates a color from hue, saturation and lightness values

Creates a color from hue, saturation, lightness and alpha values

Returns the inverse (negative) of a color

Makes a color lighter

Mixes two colors together

Makes a color more opaque

Parses a string as a CSS color value

Parses a string as a CSS color value

Returns a color with a rgb representation

Creates a color from red, green and blue values

Creates a color from red, green, blue and alpha values

Makes a color less saturated

Makes a color more transparent

Types

color()
color() :: hsl_color | rgb_color

A representation of a color in any supported system.

hsl_color()
hsl_color() :: %CssColors.HSL{alpha: :float, hue: :float, lightness: :float, saturation: :float}

A representation of a color in hue, saturation, lightness and alpha.

rgb_color()
rgb_color() :: %CssColors.RGB{alpha: :float, blue: :float, green: :float, red: :float}

A representation of a color in red, green, blue and alpha.

Functions

adjust(struct, amount, field, value_function)
adjust(color, number, atom, (float, number -> number)) :: color

Adjusts any color attribute and returns the new color.

If necessary, this will transform the color between rgb and hsl representations. Will return with a CSSColors.HSL color if adjusting :hue, :saturation or :lightness, a CSSColors.RGB color if adjusting :red, :green or :blue and the original representation if adjusting :alpha.

The value_function must be a function that takes the old value and the amount provided and returns the new value. Simple examples include the arithmetic operators (&+/2, &-/2, &*/2 or &//2).

The final value will be capped to the valid intervals of each field (0-255 for :red, :green and :blue), 0-360 for :hue and 0-1 for :saturation, :lightness and :alpha.

Examples:

iex> rgb(150, 150, 150) |> adjust(50, :blue, &+/2)
%CssColors.RGB{alpha: 1.0, blue: 200.0, green: 150.0, red: 150.0}

iex> rgb(150, 150, 150) |> adjust(250, :blue, &+/2)
%CssColors.RGB{alpha: 1.0, blue: 255.0, green: 150.0, red: 150.0}

iex> rgb(150, 150, 150) |> adjust(200, :hue, &+/2)
%CssColors.HSL{alpha: 1.0, hue: 200.0, lightness: 0.5882352941176471,
 saturation: 0.0}

iex> rgb(150, 150, 150) |> adjust(0, :red, fn(old, new) -> old + (new - old) / 2 end)
%CssColors.RGB{alpha: 1.0, blue: 150.0, green: 150.0, red: 75.0}

Sass equivalents

Developers familiar with sass can use this function as the equivalent of adjust-color, scale-color and change-color by using the correct value function:

  • &+/2 for the eqivalent of adjust-color
  • &*/2 for the eqivalent of scale-color
  • fn _old, new -> new end for the eqivalent of change-color
adjust_hue(color, degrees)
adjust_hue(color, number) :: hsl_color

Changes the hue of a color.

Takes a color and a number of degrees (usually between -360 and 360), and returns a color with the hue rotated along the color wheel by that amount.

complement(color)
complement(color) :: hsl_color

Returns the complement of a color.

This is identical to adjust_hue(color, 180).

darken(color, amount)
darken(color, number) :: hsl_color

Makes a color darker.

Takes a color and a number between 0 and 1, and returns a color with the lightness decreased by that amount.

See also lighten/2 for the opposite effect.

desaturate(color, amount)
desaturate(color, number) :: hsl_color

Makes a color more saturated.

Takes a color and a number between 0 and 100, and returns a color with the saturation increased by that value.

See also saturate/2 for the opposite effect.

get_alpha(color)
get_alpha(color) :: float

Gets the :alpha property of the color.

get_attribute(color, key)
get_attribute(color, atom) :: float

Get’s any color attribute from the color.

get_blue(color)
get_blue(color) :: float

Gets the :blue property of the color.

get_green(color)
get_green(color) :: float

Gets the :green property of the color.

get_hue(color)
get_hue(color) :: float

Gets the :hue property of the color.

get_lightness(color)
get_lightness(color) :: float

Gets the :lightness property of the color.

get_red(color)
get_red(color) :: float

Gets the :red property of the color.

get_saturation(color)
get_saturation(color) :: float

Gets the :saturation property of the color.

grayscale(color)
grayscale(color) :: hsl_color

Converts a color to grayscale.

This is identical to desaturate(color, 1).

hsl(arg1)
hsl(color) :: hsl_color

Returns a color with a hsl representation.

Transforms the color to hsl if necessary.

hsl(hue, saturation, lightness)

Creates a color from hue, saturation and lightness values.

Alpha is set to 1.0 (full opacity).

hsl(hue, saturation, lightness, alpha)

Creates a color from hue, saturation, lightness and alpha values.

Hue should be a number in degrees.

Saturation, lightness and alpha should be a number (ratio) between 0 and 1.

invert(color)
invert(color) :: rgb_color

Returns the inverse (negative) of a color.

The red, green, and blue values are inverted, while the opacity is left alone.

lighten(color, amount)
lighten(color, number) :: hsl_color

Makes a color lighter.

Takes a color and a number between 0 and 1, and returns a color with the lightness increased by that amount.

See also darken/2 for the opposite effect.

mix(color1, color2, weight \\ 0.5)
mix(color, color, number) :: rgb_color

Mixes two colors together.

Specifically, takes the average of each of the RGB components, optionally weighted by the given percentage. The opacity of the colors is also considered when weighting the components.

The weight specifies the amount of the first color that should be included in the returned color. The default, 0.5, means that half the first color and half the second color should be used. 25% means that a quarter of the first color and three quarters of the second color should be used.

## Examples:

iex> to_string mix(parse!("#00f"), parse!("#f00"))
  "#800080"
  iex> to_string mix(parse!("#00f"), parse!("#f00"), 0.25)
  "#BF0040"
  iex> to_string mix(rgb(255, 0, 0, 0.5), parse!("#00f"))
  "rgba(64, 0, 191, 0.75)"
opacify(color, amount)
opacify(color, number) :: hsl_color

Makes a color more opaque.

Takes a color and a number between 0 and 1, and returns a color with the opacity increased by that amount.

See also transparentize/2 for the opposite effect.

parse(string)
parse(String.t) :: {:ok, color} | {:error, atom}

Parses a string as a CSS color value.

The string should be a valid CSS3 color. Returns {:ok, color} on successful parse, or {:error, reason} otherwise

parse!(string)
parse!(String.t) :: color

Parses a string as a CSS color value.

Similar to parse/1 but throws on invalid input. Returns the color if succesful.

rgb(arg1)
rgb(color) :: rgb_color

Returns a color with a rgb representation.

Transforms the color to rgb if necessary.

rgb(red, green, blue)
rgb(number, number, number) :: rgb_color

Creates a color from red, green and blue values.

Alpha is set to 1.0 (full opacity).

rgb(red, green, blue, alpha)
rgb(number, number, number, number) :: rgb_color

Creates a color from red, green, blue and alpha values.

Red, green and blue should given as numbers between 0 and 255.

Alpha should be a number (ratio) between 0 and 1.

saturate(color, amount)
saturate(color, number) :: hsl_color

Makes a color less saturated.

Takes a color and a number between 0 and 100, and returns a color with the saturation decreased by that value.

See also desaturate/2 for the opposite effect.

transparentize(color, amount)
transparentize(color, number) :: color

Makes a color more transparent.

Takes a color and a number between 0 and 1, and returns a color with the opacity decreased by that amount.

See also opacify/2 for the opposite effect.