Skip to content

FrostColor is a free, open-source color manipulation library for JavaScript.

License

Notifications You must be signed in to change notification settings

elusivecodes/FrostColor

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

94 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

FrostColor

FrostColor is a free, open-source immutable color manipulation library for JavaScript.

It is a lightweight (~4kb gzipped) and modern library, and features full support for RGB, HSL, HSV, CMY and CMYK color-spaces.

Table Of Contents

Installation

In Browser

<script type="text/javascript" src="/path/to/frost-color.min.js"></script>

Using NPM

npm i @fr0st/color

In Node.js:

import Color from '@fr0st/color';

Basic Usage

From RGB

  • red is a number between 0 and 255.
  • green is a number between 0 and 255.
  • blue is a number between 0 and 255.
  • alpha is a number between 0 and 1, and will default to 1.
const color = new Color(red, green, blue, alpha);

From Brightness

  • brightness is a number between 0 and 100.
  • alpha is a number between 0 and 1, and will default to 1.
const color = new Color(brightness, alpha);

Color Creation

From String

Create a new Color from a HTML color string.

  • colorString is a string containing a color value in either hexadecimal, RGB, RGBA, HSL, HSLA or a standard HTML color name.
const color = Color.fromString(colorString);

From CMY

Create a new Color from CMY values.

  • cyan is a number between 0 and 100.
  • magenta is a number between 0 and 100.
  • yellow is a number between 0 and 100.
  • alpha is a number between 0 and 1, and will default to 1.
const color = Color.fromCMY(cyan, magenta, yellow, alpha);

From CMYK

Create a new Color from CMYK values.

  • cyan is a number between 0 and 100.
  • magenta is a number between 0 and 100.
  • yellow is a number between 0 and 100.
  • key is a number between 0 and 100.
  • alpha is a number between 0 and 1, and will default to 1.
const color = Color.fromCMYK(cyan, magenta, yellow, key, alpha);

From HSL

Create a new Color from HSL values.

  • hue is a number between 0 and 360.
  • saturation is a number between 0 and 100.
  • lightness is a number between 0 and 100.
  • alpha is a number between 0 and 1, and will default to 1.
const color = Color.fromHSL(hue, saturation, lightness, alpha);

From HSV

Create a new Color from HSV values.

  • hue is a number between 0 and 360.
  • saturation is a number between 0 and 100.
  • value is a number between 0 and 100.
  • alpha is a number between 0 and 1, and will default to 1.
const color = Color.fromHSV(hue, saturation, value, alpha);

Color Formatting

To String

Return a HTML string representation of the color.

The colorString returned will be a string containing either a HTML color name (if one exists), a hexadecimal string (if alpha is 1) or an RGBA string.

const colorString = color.toString();

To Hex String

Return a hexadecimal string representation of the color.

const hexString = color.toHexString();

To RGB String

Return a RGB/RGBA string representation of the color.

const rgbString = color.toRGBString();

To HSL String

Return a HSL/HSLA string representation of the color.

const hslString = color.toHSLString();

Label

Get the closest color name for the color.

const label = color.label();

Color Attributes

Get Alpha

Get the alpha value of the color (between 0 and 1).

const alpha = color.getAlpha();

Get Brightness

Get the brightness value of the color (between 0 and 100).

const brightness = color.getBrightness();

Get Hue

Get the hue value of the color (between 0 and 360).

const hue = color.getHue();

Get Saturation

Get the saturation value of the color (between 0 and 100).

const saturation = color.getSaturation();

Luma

Get the relative luminance value of the color (between 0 and 1).

const luma = color.luma();

Set Alpha

Set the alpha value of the color.

  • alpha is a number between 0 and 1.
const newColor = color.setAlpha(alpha);

Set Brightness

Set the brightness value of the color.

  • brightness is a number between 0 and 100.
const newColor = color.setBrightness(brightness);

Set Hue

Set the hue value of the color.

  • hue is a number between 0 and 360.
const newColor = color.setHue(hue);

Set Saturation

Set the saturation value of the color.

  • saturation is a number between 0 and 100.
const newColor = color.setSaturation(saturation);

Color Manipulation

Darken

Darken the color by a specified amount.

  • amount is a number between 0 and 1.
const newColor = color.darken(amount);

Invert

Invert the color.

const newColor = color.invert();

Lighten

Lighten the color by a specified amount.

  • amount is a number between 0 and 1.
const newColor = color.lighten(amount);

Shade

Shade the color by a specified amount.

  • amount is a number between 0 and 1.
const newColor = color.shade(amount);

Tint

Tint the color by a specified amount.

  • amount is a number between 0 and 1.
const newColor = color.tint(amount);

Tone

Tone the color by a specified amount.

  • amount is a number between 0 and 1.
const newColor = color.tone(amount);

Color Schemes

Complementary

Create a complementary color variation.

const complementary = color.complementary();

Split

Create an array with 2 split color variations.

const [secondary, accent] = color.split();

Analogous

Create an array with 2 analogous color variations.

const [secondary, accent] = color.analogous();

Triadic

Create an array with 2 triadic color variations.

const [secondary, accent] = color.triadic();

Tetradic

Create an array with 3 tetradic color variations.

const [secondary, alternate, accent] = color.tetradic();

Color Palettes

Create a palette of colors from a Color object you have created using the following methods.

Shades

Create an array with a specified number of shade variations.

  • shades is a number indicating how many shades you wish to generate, and will default to 10.
const colorShades = color.shades(shades);

Tints

Create an array with a specified number of tint variations.

  • tints is a number indicating how many tints you wish to generate, and will default to 10.
const colorTints = color.tints(tints);

Tones

Create an array with a specified number of tone variations.

  • tones is a number indicating how many tones you wish to generate, and will default to 10.
const colorTones = color.tones(tones);

Palette

Create a palette object with a specified number of shades, tints and tone variations.

  • options is an object containing options for how the palette should be generated.
    • shades is a number indicating how many shades you wish to generate, and will default to 10.
    • tints is a number indicating how many tints you wish to generate, and will default to 10.
    • tones is a number indicating how many tones you wish to generate, and will default to 10.
const colorPalette = color.palette(options);

Static Methods

Contrast

Calculate the contrast between two colors (between 1 and 21).

  • color1 is a Color object.
  • color2 is a Color object.
const contrast = Color.contrast(color1, color2);

Distance

Calculate the distance between two colors.

  • color1 is a Color object.
  • color2 is a Color object.
const distance = Color.dist(color1, color2);

Find Contrast

Find an optimally contrasting color for another color.

  • color1 is a Color object.
  • color2 is a Color object, and will default to null.
  • options is an object containing options for how the contrasting color should be found.
    • minContrast is a number between 1 and 21 indicating the minimum valid contrast, and will default to 4.5.
    • stepSize is a number between 0 and 1 indicating the amount to darken/lighten the color on each iteration, and will default to 0.01.
const contrastColor = Color.findContrast(color1, color2, options);

If color2 value is null, color1 will be used instead.

This method will tint/shade color2 until it meets a minimum contrast threshold with color1, then the new color will be returned. If no valid contrast value can be found, this method will return null instead.

Mix

Create a new Color by mixing two colors together by a specified amount.

  • color1 is a Color object.
  • color2 is a Color object.
  • amount is a number between 0 and 1.
const mixed = Color.mix(color1, color2, amount);

Multiply

Create a new Color by multiplying two colors together by a specified amount.

  • color1 is a Color object.
  • color2 is a Color object.
  • amount is a number between 0 and 1.
const multiplied = Color.multiply(color1, color2, amount);