Color-translate NPM

Color Translator

This package allows translating colors among all valid css formats

🌐 Links

Website

Visual Studio Code Extension

NPM

Github Repository

Installation

Using npm:

npm i color-translate

Formats supported

All formats except "Named" accept an alpha value. (See Formats specification)

Format	Example string	Example obj
HEX	`'#FF6600'`	-
HEX 0x	`'0xFF6600'`	-
RGB	`'rgb(255 100 0)'`	`{ r: 255, g: 100, b: 0 }`
HSL	`'hsl(18 100% 50%)'`	`{ h: 18, s: '100%', l: '50%' }`
HWB	`'hwb(18 6% 0.4%)'`	`{ h: 18, w: '6%', w: '0.4%' }`
LAB	`'lab(61.6 61.3 66)'`	`{ l: 61.6, a: 61.3, b: 66 }`
LCH	`'lch(60 91.5 44)'`	`{ l: 60, c: 91.5, h: 44 }`
OKLAB	`'oklab(0.7 0.13 0.14)'`	`{ l: 0.7, a: 0.13, b: 0.14, ok: true }`
OKLCH	`'oklch(0.7 0.2 48)'`	`{ l: 0.7, c: 0.2, h: 48, ok: true }`
CMYK	`'device-cmyk(0 0.5 1 0)'`	`{ c: 0, m: 0.5, y: 1, k: 0 }`
A98	`'color(a98-rgb 1 0.4 0)'`	`{ r: 1, g: 0.4, b: 0, a98: true }`
Named	`'orangered'`	-

Usage

The first step is to create a new ColorTranslator instance

import ColorTranslator from "color-translate";
const color = new ColorTranslator(<input>);

The input value has to be either a valid string or an object (See Formats supported)

const color = new ColorTranslator("rgb(255 100 0)");
const color2 = new ColorTranslator({ r: 255, g: 100, b: 0 });

Example

import ColorTranslator from "color-translate";

const color = new ColorTranslator("hsl(0 100% 50%)");
color
  .updateRgb({ r: 127.5, b: 255, alpha: 0.4 })
  .updateOptions({ angleUnit: "grad" });

console.log(color.lch.l);
// 39.282796563892475

console.log(color.lch.toString());
// 'lch(39.28 121.27 342.22grad / 0.4)'

console.log(color.lch.toString({ angleUnit: "rad" }));
// 'lch(39.28 121.27 5.38rad / 0.4)'

Methods

Once created the ColorTranslator instance, we can call these methods

Method	Description	Example
.\<format>	Returns a color object, containing it's values as properties	`.rgb` = `{ r: 255, g: 100, b: 0 }`
.\<format>.toString()	Returns a string representation of the color in the given format	`.rgb.toString()` = `rgb(255, 100, 0)`
.update\<format>(...)	Updates specific properties in the given format	`.updateRgb({ r: 0 }).rgb` = `{ r: 0, g: 100, b: 0 }`
.options	Returns the current options. (See Options)	`.options` = `{ spaced: true, ... }`
.updateOptions(...)	Updates the given options. (See Options)	`.updateOptions({ spaced: false }).options` = `{ spaced: false, ... }`

Options

Option	Description	Default value
angleUnit	Angle unit	`'none'`
cacheInput	Persist last input	`false`
legacy	Legacy mode	`true`
limitToColorSpace	Clamp colors to format space	`true`
maxDigits	Round color values to a max number of decimal places	`2`
spaced	Space between string color values	`false`

Formats specification

Here is a table with the standard presentations of each color format property (this follows closely the W3C standards)

Color Format/s	Property/ies	Presentations	Examples
ALL FORMATS	alpha (default = 1)	Number/String 0-1, String Percentage	0.5, '0.5', '50%'
RGB	r, g, b	Number/String 0-255, String Percentage	123, '123', '50%'
A98	r, g, b	Number/String 0-1	0.5, '0.5'
HSL, HWB, LCH, OKLCH	h	Number/String 0-360, String Percentage, String Grad, String Rad, String Turn	180, '180', '50%', '200grad', '3.14rad', '0.5turn'
HSL	s, l	Number/String 0-1, String Percentage	0.5, '0.5', '50%'
HWB	w, b	Number/String 0-1, String Percentage	0.5, '0.5', '50%'
LAB, LCH	l	Number/String 0-100, String Percentage	50, '50', '50%'
LAB	a, b	Number/String -125 - 125, String Percentage -100% - 100%	-62.5, '-62.5', '-50%'
LCH	c	Number/String 0-150, String Percentage	75, '75', '50%'
OKLAB, OKLCH	l	Number/String 0-1, String Percentage	0.5, '0.5', '50%'
OKLAB	a, b	Number/String -0.4 - 0.4, String Percentage -100% - 100%	-0.2, '-0.2', '-50%'
OKLCH	c	Number/String 0-0.4, String Percentage	0.2, '0.2', '50%'
CMYK	c, m, y, k	Number/String 0-1, String Percentage	0.5, '0.5', '50%'