CssColors

v0.2.2

CssColors v0.2.2 CssColors View Source

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)"

Link to this section Summary

Types

color()

A representation of a color in any supported system

hsl_color()

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

rgb_color()

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

Functions

adjust(struct, amount, field, value_function)

Adjusts any color attribute and returns the new color

adjust_hue(color, degrees)

Changes the hue of a color

complement(color)

Returns the complement of a color

darken(color, amount)

Makes a color darker

desaturate(color, amount)

Makes a color more saturated

get_alpha(color)

Gets the :alpha property of the color

get_attribute(color, key)

Get's any color attribute from the color

get_blue(color)

Gets the :blue property of the color

get_green(color)

Gets the :green property of the color

get_hue(color)

Gets the :hue property of the color

get_lightness(color)

Gets the :lightness property of the color

get_red(color)

Gets the :red property of the color

get_saturation(color)

Gets the :saturation property of the color

grayscale(color)

Converts a color to grayscale

hsl(color)

Returns a color with a hsl representation

hsl(hue, saturation, lightness)

Creates a color from hue, saturation and lightness values

hsl(hue, saturation, lightness, alpha)

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

invert(color)

Returns the inverse (negative) of a color

lighten(color, amount)

Makes a color lighter

mix(color1, color2, weight \\ 0.5)

Mixes two colors together

opacify(color, amount)

Makes a color more opaque

parse(string)

Parses a string as a CSS color value

parse!(string)

Parses a string as a CSS color value

rgb(color)

Returns a color with a rgb representation

rgb(red, green, blue)

Creates a color from red, green and blue values

rgb(red, green, blue, alpha)

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

saturate(color, amount)

Makes a color less saturated

transparentize(color, amount)

Makes a color more transparent

Link to this section Types

Link to this type

color() View Source 
color() :: hsl_color() | rgb_color()

A representation of a color in any supported system.

Link to this type

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

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

Link to this type

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

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

Link to this section Functions

Link to this function

adjust(struct, amount, field, value_function) View Source 
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
Link to this function

adjust_hue(color, degrees) View Source 
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.

Link to this function

complement(color) View Source 
complement(color()) :: hsl_color()

Returns the complement of a color.

This is identical to adjust_hue(color, 180).

Link to this function

darken(color, amount) View Source 
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.

Link to this function

desaturate(color, amount) View Source 
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.

Link to this function

get_alpha(color) View Source 
get_alpha(color()) :: float()

Gets the :alpha property of the color.

Link to this function

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

Get's any color attribute from the color.

Link to this function

get_blue(color) View Source 
get_blue(color()) :: float()

Gets the :blue property of the color.

Link to this function

get_green(color) View Source 
get_green(color()) :: float()

Gets the :green property of the color.

Link to this function

get_hue(color) View Source 
get_hue(color()) :: float()

Gets the :hue property of the color.

Link to this function

get_lightness(color) View Source 
get_lightness(color()) :: float()

Gets the :lightness property of the color.

Link to this function

get_red(color) View Source 
get_red(color()) :: float()

Gets the :red property of the color.

Link to this function

get_saturation(color) View Source 
get_saturation(color()) :: float()

Gets the :saturation property of the color.

Link to this function

grayscale(color) View Source 
grayscale(color()) :: hsl_color()

Converts a color to grayscale.

This is identical to desaturate(color, 1).

Link to this function

hsl(color) View Source 
hsl(color()) :: hsl_color()

Returns a color with a hsl representation.

Transforms the color to hsl if necessary.

Link to this function

hsl(hue, saturation, lightness) View Source

Creates a color from hue, saturation and lightness values.

Alpha is set to 1.0 (full opacity).

Link to this function

hsl(hue, saturation, lightness, alpha) View Source

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.

Link to this function

invert(color) View Source 
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.

Link to this function

lighten(color, amount) View Source 
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.

Link to this function

mix(color1, color2, weight \\ 0.5) View Source 
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)"
Link to this function

opacify(color, amount) View Source 
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.

Link to this function

parse(string) View Source 
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

Link to this function

parse!(string) View Source 
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.

Link to this function

rgb(color) View Source 
rgb(color()) :: rgb_color()

Returns a color with a rgb representation.

Transforms the color to rgb if necessary.

Link to this function

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

Creates a color from red, green and blue values.

Alpha is set to 1.0 (full opacity).

Link to this function

rgb(red, green, blue, alpha) View Source 
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.

Link to this function

saturate(color, amount) View Source 
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.

Link to this function

transparentize(color, amount) View Source 
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.