color
🎨 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({ value: ColorInput; from?: ColorSourceFormat; to?: ColorFormat }): ColorOutput
Takes a single object naming the conversion: value is the color to read, from says how to read an array (default 'rgba'), and to is the format to produce (default 'hex').
value — 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 names likealiceblue,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? }.
from — ColorSourceFormat
Needed only for arrays, which carry no indication of their own colour space. Defaults to 'rgba'; may be 'rgb', 'hsl', 'hsla' or 'oklch'.
to — 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({ value: 'red', to: ColorFormat.HEX }); //=> '#ff0000' color({ value: '#00ff00', to: ColorFormat.RGB }); //=> 'rgb(0, 255, 0)'
2. Using String Literals
color({ value: [0, 0, 255], to: 'hsl' }); //=> 'hsl(240, 100%, 50%)' color({ value: 'rgb(255, 0, 0)', to: 'rgba-object' }); //=> { r: 255, g: 0, b: 0, a: 1 }
3. Working with Alpha Channel
color({ value: 'rgba(255, 0, 0, 0.5)', to: 'hex' }); //=> '#ff000080' color({ value: { r: 0, g: 255, b: 0, a: 0.1 }, to: 'hsla' }); //=> 'hsla(120, 100%, 50%, 0.1)'
3. Smart Format
color({ value: "#ff0000", to: ColorFormat.CSS }); //=> "red" color({ value: "#f0f8ff", to: "css" }); //=> "aliceblue" color({ value: "#123456", to: "css" }); //=> "#123456" color({ value: "rgba(255, 0, 0, 0.5)", to: "css" }); //=> "rgba(255, 0, 0, 0.5)"
4. Advanced Color Spaces (OKLCH)
color({ value: 'red', to: 'oklch' }); //=> 'oklch(0.628 0.2577 29.23)' color({ value: 'oklch(0.628 0.2577 29.23)', to: 'hex' }); //=> '#ff0000'
5. Terminal Output (ANSI)
color({ value: 'red', to: 'ansi' }); //=> "\x1b[38;2;255;0;0m" color({ value: '#00ff00', to: ColorFormat.ANSI }); //=> "\x1b[38;2;0;255;0m"
6. Extracting Data Structures
color({ value: '#ff0000', to: ColorFormat.RGBA_OBJ }); //=> { r: 255, g: 0, b: 0, a: 1 } color({ value: 'hsl(120, 100%, 50%)', to: ColorFormat.HSLA_ARR }); //=> [120, 100, 50, 1]
7. Reading an Array Back
An array carries no indication of its own colour space, so from names it:
const hsla = color({ value: '#3366cc', to: 'hsla-array' }); //=> [220, 60, 50, 1] color({ value: hsla, from: 'hsla' }); //=> '#3366cc'
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({ value: 'invalid-color', to: 'hex' }); } catch (e) { console.error(e.message); //=> "Invalid Color" }
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.