ColorTranslator

ColorTranslator copied to clipboard

A JavaScript library, written in TypeScript, to convert among different color models

Demo

https://elchininet.github.io/ColorTranslator/

Installation

Using NPM

npm install colortranslator

Using Yarn

yarn add colortranslator

In the browser

It is possible to include a compiled version of the package directly in an HTML file. It will create a global colortranslator object containing all the exported modules that can be accessed from anywhere in your JavaScript code.

1. Copy the JavaScript file colortranslator.js, located in the dist/web/ folder
2. Put it in the folder that you prefer in your web server
3. Include it in your HTML file

<script src="wherever/you/installed/colortranslator.js"></script>

/* There will be a global variable named colortranslator containing all the modules */
colortranslator.ColorTranslator;
colortranslator.Harmony;
colortranslator.Mix;

Importing using CommonJS

const { ColorTranslator, Harmony, Mix } = require('colortranslator');

Importing using ES6 modules

import { ColorTranslator, Harmony, Mix } from 'colortranslator';

Scripts

build

npm run build

Transpiles the TypeScript code and creates three bundles in the dist folder (index.js for commonjs, esm/index.js for ESM, and web/colortranslator.js to use directly in the browser).

test

npm run test

Runs multiple dynamic tests converting from / to all the color models available (excepting CMYK) using a table of colors.

lint

npm run lint

Runs eslint in source files.

demo

npm run demo

Opens a development server that provides live reloading using webpack-dev-server. Some demo examples located in the @demo folder will be shown. You can modify the code of the demos and the changes will be live reloaded in the browser.

API

Note: The conversion to a CMYK color is made taking a random value of black as a base (in this case, taking the greater value from red, green or blue). When a value of black is assumed, the rest of the colors can be calculated from it. The result will be visually similar to the original light color, but if you try to convert it back you will not obtain the same original value.

Input

The most wonderful thing about colortranslator is that you don‘t need to specify the input that you are using, the library will recognise it automatically. The input can be a CSS string or an object:

CSS string inputs

Object inputs

Class instantiation

It is possible to instantiate the class using any of the previous inputs:

Class instantiation examples

const keyword = new ColorTranslator('deeppink');

const hex = new ColorTranslator('#FF00FF');

const rgb = new ColorTranslator('rgb(255, 0, 0)');

const hsl = new ColorTranslator('hsl(50, 20%, 90%)');

const hsla = new ColorTranslator({ r: 115, g: 200, b: 150, a: 0.5 });

const cmyk = new ColorTranslator({ c: 100, m: 100, y: 0, k: 0 });

Class public methods

There are 11 chainable public methods and all of them accept a number as input:

Class public methods examples

You can also consult the demo 1 and the demo 2 to check the use of the public methods.

const color = new ColorTranslator('#FF00FF');

color
  .setH(120)
  .setS(80)
  .setA(0.5);

color
  .setR(255)
  .setG(150)
  .setA(0.25);

Class public readonly properties

There are 7 properties to get the CSS representation of the color:

There are 7 properties to get the object representation of the color:

There are 11 properties to get the individual color values:

Class public properties examples

You can also consult the demo 1 and the demo 2 to check the use of the public properties.

const color = new ColorTranslator('#FF00FF');

color.R; // 255
color.G; // 0
color.B; // 255
color.RGB; // rgb(255,0,255)
color.HSLA; // hsla(300,100%,50%,1)

Class static methods

For the static methods, it is not needed to specify the input color model, the API will detect the format automatically. It is only needed to specify to which color model one wants to convert calling the specific static method.

There are 22 static methods available, 7 of them to convert colors, 6 to create color blends, one to get shades, one to get tints, 6 to mix colors, and one to create color harmonies.

Color conversion static methods

The static methods to convert colors accept any of the mentioned inputs as the first parameter. The second parameter is optional and it specifies if the output should be a CSS string or an object:

convertColorStaticMethod(
  color: string | object,
  css: boolean = true
)

Color conversion static methods description

Color conversion static methods examples

ColorTranslator.toHEX('gold'); // #FFD700

ColorTranslator.toRGB('#FF00FF'); // rgb(255,0,255)

ColorTranslator.toRGBA('hsl(50, 20%, 90%)'); // rgba(235,233,224,1)

ColorTranslator.toHSL('rgb(255, 0, 0)'); // hsl(0,100%,50%)

ColorTranslator.toHSLA('rgba(0, 255, 255, 0.5)'); // hsla(180,100%,50%,0.5)

ColorTranslator.toCMYK('#F0F', false); // {c: 0, m: 100, y: 0, k: 0}

ColorTranslator.toCMYK('#F0F'); // cmyk(0%,100%,0%,0%)

ColorTranslator.toRGB({ h: 115, s: '70%', l: '45%' }); // rgb(48,195,34)

ColorTranslator.toHSLA({ r: 115, g: 200, b: 150, a: 0.5 }); // hsla(145,44%,62%,0.5)

You can also consult the demo 3, and the demo 4 to check the use of these static methods.

Color blends static methods

The static methods to create color blends accept any of the mentioned inputs as the first and second parameter, the third parameter is optional and it is the number of steps of the blending, and the fourth parameter is also optional and it specifies if the output colors should be CSS strings or objects:

getBlendColorsStaticMethod(
  fromColor: string | object,
  toColor: string | object,
  steps: number = 5,
  css: boolean = true
)

Color blends static methods description

Color blends static methods examples

ColorTranslator.getBlendHEX('#FF0000', '#0000FF', 5);

// [
//   "#FF0000",
//   "#BF003F",
//   "#7F007F",
//   "#3F00BF",
//   "#0000FF"
// ]

ColorTranslator.getBlendHSLA('#FF000000', '#0000FFFF', 3);

// [
//   "hsla(0,100%,50%,0)",
//   "hsla(300,100%,25%,0.5)",
//   "hsla(240,100%,50%,1)"
// ]

ColorTranslator.getBlendRGBA('#F000', 'rgba(0,0,255,1)', 5, false);

// [
//   {r: 255, g: 0, b: 0, a: 0},
//   {r: 191.25, g: 0, b: 63.75, a: 0.25},
//   {r: 127.5, g: 0, b: 127.5, a: 0.5},
//   {r: 63.75, g: 0, b: 191.25, a: 0.75},
//   {r: 0, g: 0, b: 255, a: 1}
// ]

You can also consult the demo 5 to check the use of these static methods.

Color shades and color tints static methods

The static methods to get shades or tints of a color accept any of the mentioned inputs as the first parameter, and a second parameter that specifies the number of shades or tints that should be returned. This method will return the colors in the same format that was sent as input:

getShades(
  color: string | object,
  shades: number
)

getTints(
  color: string | object,
  tints: number
)

Color shades and color tints static methods description

Color shades and color tints static methods examples

ColorTranslator.getShades('#FF0000', 5);

// [
//   "#D40000",
//   "#AA0000",
//   "#800000",
//   "#550000",
//   "#2A0000"
// ]

ColorTranslator.getTints({r: 255, g: 0, b: 0, a: 0.5}, 5);

// [
//   {r: 255, g: 43, b: 43, a: 0.5},
//   {r: 255, g: 85, b: 85, a: 0.5},
//   {r: 255, g: 128, b: 128, a: 0.5},
//   {r: 255, g: 170, b: 170, a: 0.5},
//   {r: 255, g: 213, b: 213, a: 0.5}
// ]

You can also consult the demo 6 to check the use of these static methods.

Color mix static methods

The static methods to mix colors accept an array of any of the mentioned inputs as the first parameter. The second parameter is optional and specifies the mixing mode (by default it will be Mix.ADDITIVE). The third parameter is also optional and it specifies if the output should be a CSS string or an object:

Note: The subtractive mix simulates the mixing of pigments, to achieve this, the rgb colors are converted to ryb color model, the addition is performed in this mode and at the end the result is converted back to rgb. The result is OK most of the time, but as this is not a real mix of pigments, sometimes the result could differ from the reality.

getMixColorsStaticMethod(
  colors: [string | object][],
  mode: Mix = Mix.ADDITIVE,
  css: boolean = true
)

Color mix static methods description

Color mix static methods examples

ColorTranslator.getMixHEX(['#FF0000', '#0000FF']);

// #FF00FF

ColorTranslator.getMixHSL(['rgba(255, 0, 0, 1)', '#00FF00']);

// hsl(60,100%,50%)

ColorTranslator.getMixHEXA(['#F00', 'rgb(0, 0, 255)'], Mix.ADDITIVE, true);

// { r: '0xFF', g: '0x00', b: '0xFF', a: '0xFF' }

ColorTranslator.getMixHEX(['#FF0', '#F00'], Mix.SUBTRACTIVE);

// #FF7F00

You can also consult the demo 7 and demo 8 to check the use of these static methods.

Color harmonies static method

The static method to create color harmonies accepts three parmeters, the first one could be any of the mentioned inputs, the second one is optional and it is to specify the kind of harmony (by default it will be Harmony.COMPLEMENTARY), and the third one is also optional and it specifies if the returned harmony is based on additive or subtractive colors (by default it will be Mix.ADDITIVE). This method will return the colors in the same format that was sent as input:

getHarmony(
  color: string | object
  harmony: Harmony = Harmony.COMPLEMENTARY,
  mode: Mix = Mix.ADDITIVE
)

Color harmonies static method description

Available armonies

Color harmonies static method examples

ColorTranslator.getHarmony('#FF00FF');

// ["#FF00FF", "#00FF00"]

ColorTranslator.getHarmony('rgba(0, 255, 255, 0.5)', Harmony.ANALOGOUS);

// [
//   "rgba(0,255,255,0.5)",
//   "rgba(0,128,255,0.5)",
//   "rgba(0,255,128,0.5)"
// ]

ColorTranslator.getHarmony({ r: 115, g: 200, b: 150, a: 0.5 }, Harmony.COMPLEMENTARY);

// [
//   {r: 115, g: 201, b: 151, a: 0.5},
//   {r: 201, g: 115, b: 165, a: 0.5}
// ]

ColorTranslator.getHarmony('#FF0000', Harmony.COMPLEMENTARY, Mix.SUBTRACTIVE);

// ["#FF0000", "#00FF00"]

You can also consult the demo 9 and demo 10 to check the use of this static method.

TypeScript Support

The package has its own type definitions, so it can be used in a TypeScript project without any issues. The next interfaces are exposed and can be imported in your project:

HEXObject

This type is returned by the HEXObject, and HEXAObject properties, the toHEX, toHEXA, getBlendHEX, getBlendHEXA, getMixHEX, and getMixHEXA methods (when the css property is false), and the getHarmony method (when the input is an HEXObject).

interface HEXObject {
    r: string;
    g: string;
    b: string;
    a?: string;
}

RGBObject

This type is returned by the RGBObject, and RGBAObject properties, the toRGB, toRGBA, getBlendRGB, getBlendRGBA, getMixRGB, and getMixRGBA methods (when the css property is false), and the getHarmony method (when the input is an RGBObject).

interface RGBObject {
    r: number;
    g: number;
    b: number;
    a?: number;
}

HSLObject

This type is returned by the HSLObject, and HSLAObject properties, the toHSL, toHSLA, getBlendHSL, getBlendHSLA, getMixHSL, and getMixHSLA methods (when the css property is false), and the getHarmony method (when the input is an HSLObject).

interface HSLObject {
    h: number;
    s: number;
    l: number;
    a?: number;
}

CMYKObject

This type is returned by the CMYKObject property, and the toCMYK method.

interface CMYKObject {
    c: number;
    m: number;
    y: number;
    k: number;
}