Color parser and format converter for colors with up to 5 channels, such as those used by various LED strip types like RGB, RGBW, and RGBCCT. Formats in this package use the typical red, green, and blue, but drop alpha and instead add white and white2.
npm install rgbcct-color-handlerDue to inconsistencies in the labelling and order of white channels on RGBCCT strips, and the fact that RGBW strips have no queryable way to identify their white channel's temperature, it's up to the user to decide how w and w2 will be assigned.
When outputting color objects, channels will use the keys in the table below. These are also the preferred keys to use when inputting color objects, however RGBCCT-Color-Handler will check for reasonable alternative names of each as well.
| Output / Preferred Input Key | Corresponding Channel |
|---|---|
| r | Red |
| g | Green |
| b | Blue |
| w | White |
| w2 | 2nd White |
NOTE: If 2 white channels are defined in an input color object, but neither is named some variation of 'w2' or 'white 2', the parser will blindly assign 'w2' to the 2nd white channel it reads and 'w' to the first.
- input - The color to convert. See examples below for acceptable input formats
- outputFormat - Supported output formats include 'hex', 'arr', and 'obj' for hex code string, color channel array, and color channel object respectively
import {convertColor} from 'rgbcct-color-handler';
// Color hex code string inputs
const hexIn = '#10204080FF';// (case insensitive)
let hexOut1 = convertColor(hexIn, 'hex');// returns "#10204080ff"
let arrOut1 = convertColor(hexIn, 'arr');// returns [ 16, 32, 64, 128, 255 ]
let objOut1 = convertColor(hexIn, 'obj');// returns { r:16, g:32, b:64, w:128, w2:255 }
// Color array inputs
const arrIn = [ 16, 32, 64, 128, 255 ];
let hexOut2 = convertColor(arrIn, 'hex');// returns "#10204080ff"
let arrOut2 = convertColor(arrIn, 'arr');// returns [ 16, 32, 64, 128, 255 ]
let objOut2 = convertColor(arrIn, 'obj');// returns { r:16, g:32, b:64, w:128, w2:255 }
// Color object inputs
const objIn = { r:16, g:32, b:64, w:128, w2:255 };
let hexOut3 = convertColor(objIn, 'hex');// returns "#10204080ff"
let arrOut3 = convertColor(objIn, 'arr');// returns [ 16, 32, 64, 128, 255 ]
let objOut3 = convertColor(objIn, 'obj');// returns { r:16, g:32, b:64, w:128, w2:255 }import {convertColor} from 'rgbcct-color-handler';
// Shorthand hex code strings
const hex3In = '#ABC';// Shorthand RGB code
const hex4In = '#Abcd';// Shorthand RGBW code
const hex5In = '#abCdE';// Shorthand RGBCCY code
let hexOut1 = convertColor(hex3In, 'hex');// returns "#aabbcc"
let arrOut1 = convertColor(hex4In, 'arr');// returns [ 170, 187, 204, 221 ]
let objOut1 = convertColor(hex5In, 'obj');// returns { r:170, g:187, b:204, w:221, w2:238 }
// Hexadecimal number strings (Hex codes prefixed with '0x' rather than '#')
const zeroHexIn = '0x00FffF';// NOTE: Non-string hexadecimal numbers are not yet supported
let hexOut2 = convertColor(zeroHexIn, 'hex');// returns "#00ffff"
let arrOut2 = convertColor(zeroHexIn, 'arr');// returns [ 0, 255, 255 ]
let objOut2 = convertColor(zeroHexIn, 'obj');// returns { r:0, g:255, b:255 }
// Hex code strings with no prefixes
const noPrefixHexIn = '00ff80FF';
let hexOut3 = convertColor(noPrefixHexIn, 'hex');// returns "#00ff80ff"
let arrOut3 = convertColor(noPrefixHexIn, 'arr');// returns [ 0, 255, 128, 255 ]
let objOut3 = convertColor(noPrefixHexIn, 'obj');// returns { r:0, g:255, b:128, w:255 }Other formats supported include percentages and fraction decimals
- Strings containing a "%" character will interpreted as a percentage.
- Strings containing a decimal in the range of 0.0 to 1.0 will be interpreted as a fraction.
import {convertColor} from 'rgbcct-color-handler';
// Arrays of number strings
const arrOfStrIn = [ '16', '32', '64' ];
let hexOut1 = convertColor(arrOfStrIn, 'hex');// returns "#102040"
let arrOut1 = convertColor(arrOfStrIn, 'arr');// returns [ 16, 32, 64 ]
let objOut1 = convertColor(arrOfStrIn, 'obj');// returns { r:16, g:32, b:64 }
// Arrays of percentages
const arrOfPctIn = [ '6.25%', '12.5 %', '25 %', '50 %' ];// NOTE: All whitespace between the number and "%" character will be ignored.
let hexOut2 = convertColor(arrOfPctIn, 'hex');// returns "#10204080"
let arrOut2 = convertColor(arrOfPctIn, 'arr');// returns [ 16, 32, 64, 128 ]
let objOut2 = convertColor(arrOfPctIn, 'obj');// returns { r:16, g:32, b:64, w:128 }
// Arrays of decimals
const arrOfDecIn = [ 0.0625, 0.125, 0.25, 0.5, 1.0 ];// NOTE the difference between these outputs and those of similar-looking fractions below
let hexOut3 = convertColor(arrOfDecIn, 'hex');// returns "#0000000101"
let arrOut3 = convertColor(arrOfDecIn, 'arr');// returns [ 0, 0, 0, 1, 1 ]
let objOut3 = convertColor(arrOfDecIn, 'obj');// returns { r:0, g:0, b:0, w:1, w2:1 }
// Arrays of fractions
const arrOfFrcIn = [ '0.0625', '0.125', '0.25', '0.5', '1.0' ];// NOTE: Stringed decimals greater than 1.0 will be treated the same as normal non-string floats like in the example above
let hexOut4 = convertColor(arrOfFrcIn, 'hex');// returns "#10204080ff"
let arrOut4 = convertColor(arrOfFrcIn, 'arr');// returns [ 16, 32, 64, 128, 255 ]
let objOut4 = convertColor(arrOfFrcIn, 'obj');// returns { r:16, g:32, b:64, w:128, w2:255 }In addition to integers, object input values also support the same expanded formats that arrays do (e.g. number strings, percentages, decimals, fractions) Input objects will also be checked for different forms of the keys 'r', 'g', 'b', 'w', and 'w2' if any of these 5 are not found. These forms include:
- Keys with the wrong case (e.g. 'R', 'G', 'B', 'W', 'W2' )
- Keys using the full name of the channel rather than the abbreviation (e.g. 'red', 'Green', 'BLUE', 'wHITE', 'whitE2' )
- 3-letter abbreviations of color channel names (e.g. 'red', 'Grn', 'BLU', 'wHT', 'whT2' )
- Specific types of white channels commonly used on LED strips (e.g. 'coldWhite', 'CoolWhite', 'NaturalWHT', 'DAYLIGHTwht', 'dayLIGHT', 'WARMWHITE', 'hotWHITE' )
- Any of the above with spaces, plusses, dashes (including en dash, em dash, and hyphen characters), or underscores (e.g. 'cold White', 'Cool+White', 'Natural_WHT', 'DAY-LIGHT-wht', 'day–LIGHT', 'WARM—WHITE', 'hot‐WHITE' )
import {convertColor} from 'rgbcct-color-handler';
// Objects of number strings
const objOfStrIn = { R:'16', Green:'32', BLU:'64' };
let hexOut1 = convertColor(objOfStrIn, 'hex');// returns "#102040"
let arrOut1 = convertColor(objOfStrIn, 'arr');// returns [ 16, 32, 64 ]
let objOut1 = convertColor(objOfStrIn, 'obj');// returns { r:16, g:32, b:64 }
// Objects of percentages
const objOfPctIn = { red:'6.25%', grn:'12.5 %', B:'25 %', "natural white":'50 %' };
let hexOut2 = convertColor(objOfPctIn, 'hex');// returns "#10204080"
let arrOut2 = convertColor(objOfPctIn, 'arr');// returns [ 16, 32, 64, 128 ]
let objOut2 = convertColor(objOfPctIn, 'obj');// returns { r:16, g:32, b:64, w:128 }
// Objects of decimals
const objOfDecIn = { "r":0.0625, "green":0.125, "b":0.25, white:0.5, w2:1.0 };// NOTE: w2 (white2) should never be included in an input object without another defined white key present. If two types of white channels are defined but neither is explicitly named 'w2', 'white2', 'wht_2', etc. then they will be assigned to w and w2 in the order that they appear within the object. For this reason, it's best for you to stick with using the keys listed in #channel-key-names.
let hexOut3 = convertColor(objOfDecIn, 'hex');// returns "#0000000101"
let arrOut3 = convertColor(objOfDecIn, 'arr');// returns [ 0, 0, 0, 1, 1 ]
let objOut3 = convertColor(objOfDecIn, 'obj');// returns { r:0, g:0, b:0, w:1, w2:1 }
// Objects of fractions
const objOfDecIn = { r:'0.0625', g:'0.125', b:'0.25', w:'0.5', "warm_White":'1.0' };// NOTE: Stringed decimals greater than 1.0 will be treated the same as normal non-string floats like in the example above
let hexOut4 = convertColor(objOfDecIn, 'hex');// returns "#10204080ff"
let arrOut4 = convertColor(objOfDecIn, 'arr');// returns [ 16, 32, 64, 128, 255 ]
let objOut4 = convertColor(objOfDecIn, 'obj');// returns { r:16, g:32, b:64, w:128, w2:255 }4-channel codes have been repurposed to represent RGBW (color + white) rather than the standard RGBA (color + alpha). Hex codes that include alpha channels are not currently supported as there's no straightforward way to designate a bit for alpha without requiring that EVERY hex code input includes an alpha channel.
RGBCCT-Color-Handler supports shorthand hex codes (for example, #123 => #112233). Since the shortest 'full-length' hex code is 6 characters long (i.e. plain RGB codes like #ff00ff), the longest possible shorthand that can be supported without resorting to defining a new unique format is 5 characters long, or in other words, 5 channel color codes (conveniently the same number used by RGBCCT strips).
Output values will always rounded to the nearest integer.
Stringed numbers will typically be treated as raw numbers, with the exception of stringed decimals from 0.0 to 1.0. These will always be treated as fractions (see next bullet).
Many standardized color formats use fractions of 1 (as decimals from 0 to 1) to represent intensity percentages. In order to distinguish these cases from the uncommon scenario where someone actually attempts to set a color value to a fraction of 1 out of 255, fractions of 1 intended to represent a percentage should be wrapped as strings. Any floats from 0.0 to 1.0 will be treated as though they're meant to be near-zero values out of 255. e.g. ['0.0', '0.25', '0.5', '1.0'] => [0, 64, 128, 255] == #004080ff [ 0.0, 0.25, 0.5, 1.0 ] => [0, 0, 1, 1 ] == #00000101
- Add support for raw hexadecimal numbers ( e.g. accept 0xff00ff in addition to '0xff00ff' )
- Add support for named web colors ( e.g. 'red', 'silver', 'rebeccapurple' )
- Add support for other common color model formats like HSL, HSV, CMYK, etc. ( e.g. hsl(210, 100%, 50%) or hsl(210, 1.0, 0.5) )
Copyright © 2026, phasn phasn@proton.me (https://github.com/phasn).
Licensed under the MIT License.