Color – JS Standard Library

🎨 A unified utility for parsing and converting colors between various formats.

The color function provides a polymorphic interface for all your color needs, including parsing, conversion, and smart formatting.

Syntax

import { color, ColorFormat } from '@opentf/std';
 
color(input: ColorInput, format: ColorFormat): any

ColorInput

Can be any of the following:

String: Hex (#fff, #ffffff), RGB/RGBA (rgb(255, 0, 0)), HSL/HSLA (hsl(0, 100%, 50%)), or Color Names (supports all 140+ CSS Color Module Level 4 (opens in a new tab) names like aliceblue, rebeccapurple, etc.).
Number: Hex numeric value (e.g., 0xff0000).
Array: [r, g, b] or [r, g, b, a].
Object: { r, g, b, a? } or { h, s, l, a? }.

ColorFormat

The desired output format. You can use the ColorFormat helper constant or the equivalent string literal:

Helper Constant	String Literal	Output Description
`ColorFormat.HEX`	`'hex'`	Hex string (e.g., `#ff0000`)
`ColorFormat.RGB`	`'rgb'`	`rgb()` CSS string
`ColorFormat.RGBA`	`'rgba'`	`rgba()` CSS string
`ColorFormat.HSL`	`'hsl'`	`hsl()` CSS string
`ColorFormat.HSLA`	`'hsla'`	`hsla()` CSS string
`ColorFormat.OKLCH`	`'oklch'`	`oklch()` CSS string
`ColorFormat.CSS`	`'css'`	Smart format: Name (if available), Hex (if opaque), or RGBA (if transparent)
`ColorFormat.NUMBER`	`'number'`	24-bit integer (e.g., `0xff0000`)
`ColorFormat.RGBA_OBJ`	`'rgba-object'`	`{ r, g, b, a }`
`ColorFormat.RGBA_ARR`	`'rgba-array'`	`[r, g, b, a]`
`ColorFormat.HSLA_OBJ`	`'hsla-object'`	`{ h, s, l, a }`
`ColorFormat.HSLA_ARR`	`'hsla-array'`	`[h, s, l, a]`
`ColorFormat.OKLCH_OBJ`	`'oklch-object'`	`{ l, c, h, a }`
`ColorFormat.ANSI`	`'ansi'`	ANSI TrueColor escape code (24-bit)

Examples

1. Using Helper Constants

import { color, ColorFormat } from '@opentf/std';
 
color('red', ColorFormat.HEX); //=> '#ff0000'
color('#00ff00', ColorFormat.RGB); //=> 'rgb(0, 255, 0)'

2. Using String Literals

color([0, 0, 255], 'hsl'); //=> 'hsl(240, 100%, 50%)'
color('rgb(255, 0, 0)', 'rgba-object'); //=> { r: 255, g: 0, b: 0, a: 1 }

3. Working with Alpha Channel

color('rgba(255, 0, 0, 0.5)', 'hex'); //=> '#ff000080'
color({ r: 0, g: 255, b: 0, a: 0.1 }, 'hsla'); //=> 'hsla(120, 100%, 50%, 0.1)'

3. Smart Format

color("#ff0000", ColorFormat.CSS); //=> "red"
color("#f0f8ff", "css");           //=> "aliceblue"
color("#123456", "css");           //=> "#123456"
color("rgba(255, 0, 0, 0.5)", "css"); //=> "rgba(255, 0, 0, 0.5)"

4. Advanced Color Spaces (OKLCH)

color('red', 'oklch'); //=> 'oklch(0.628 0.2577 29.23)'
color('oklch(0.628 0.2577 29.23)', 'hex'); //=> '#ff0000'

5. Terminal Output (ANSI)

color('red', 'ansi'); //=> "\x1b[38;2;255;0;0m"
color('#00ff00', ColorFormat.ANSI); //=> "\x1b[38;2;0;255;0m"

6. Extracting Data Structures

color('#ff0000', ColorFormat.RGBA_OBJ); //=> { r: 255, g: 0, b: 0, a: 1 }
color('hsl(120, 100%, 50%)', ColorFormat.HSLA_ARR); //=> [120, 100, 50, 1]

Error Handling

The color() function is strict about its inputs. If the input color cannot be parsed or the output format is invalid, it will throw an Error.

try {
  color('invalid-color', 'hex');
} catch (e) {
  console.error(e.message); //=> "Invalid Color"
}

Try

Why?

Managing color conversions in JavaScript often requires multiple specialized libraries or many small utility functions. color() provides a single, high-fidelity entry point that handles almost any standard color representation, making your code cleaner and more maintainable.

isNil colorAlpha