JSPM

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 variable that can be accessed from anywhere in your JavaScript code.

1. Copy the JavaScript file colortranslator.web.js, located in the dist 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/instelled/colortranslator.web.js" />

Importing using CommonJS

const { ColorTranslator } = require('colortranslator');

Importing using ES6 modules

import { ColorTranslator } from 'colortranslator';

Using in the browser

/* Use it directly in your JavaScript code */
ColorTranslator;

/* Or access to the global variable if there is a variable with this name in the same scope */
window.ColorTranslator;

Scripts

build

npm run build

Transpiles the TypeScript code and creates two bundles in the dist folder (index.js for Node environments and colortranslator.web.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 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 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

It is not needed to specify the color model from which you are converting, the API will detect the format. You only need to specify to which color model you want to convert calling the specific static method.

There are 7 static methods available and all of them 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:

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

Static methods examples

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

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, .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)