or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-color-string

Parser and generator for CSS color strings

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/color-string@2.1.x

To install, run

npx @tessl/cli install tessl/npm-color-string@2.1.0

index.mddocs/

Color String

Color String is a comprehensive CSS color string parsing and generation library that enables developers to parse various CSS color formats (hex, rgb, rgba, hsl, hsla, hwb, named colors) into structured data objects and generate CSS color strings from numeric values.

Package Information

  • Package Name: color-string
  • Package Type: npm
  • Language: JavaScript (ES modules with TypeScript definitions)
  • Installation: npm install color-string

Core Imports

import colorString from "color-string";

For CommonJS:

const colorString = require("color-string");

Basic Usage

import colorString from "color-string";

// Parse CSS color strings
const parsed = colorString.get('#FF0000');
// Returns: {model: 'rgb', value: [255, 0, 0, 1]}

const rgbValues = colorString.get.rgb('rgba(255, 0, 0, 0.5)');
// Returns: [255, 0, 0, 0.5]

// Generate CSS color strings
const hexColor = colorString.to.hex(255, 0, 0);
// Returns: "#FF0000"

const rgbaColor = colorString.to.rgb(255, 0, 0, 0.5);
// Returns: "rgba(255, 0, 0, 0.5)"

Architecture

Color String is built around two main namespaces:

  • Parser API (colorString.get): Universal and format-specific color string parsers
  • Generator API (colorString.to): Functions to convert numeric color values back to CSS strings
  • Type Safety: Full TypeScript support with proper type definitions
  • Format Support: Comprehensive support for all modern CSS color formats including space-separated syntax

Capabilities

Universal Color Parsing

Parse any supported CSS color format and auto-detect the color model.

/**
 * Universal color parser that auto-detects format and returns structured color data
 * @param color - CSS color string in any supported format
 * @returns Object with model type and color values, or null if invalid
 */
function get(color: string): {model: Model; value: number[]} | null;

type Model = 'rgb' | 'hsl' | 'hwb';

Usage Examples:

colorString.get('#FF0000');           // {model: 'rgb', value: [255, 0, 0, 1]}
colorString.get('#FFFA');             // {model: 'rgb', value: [255, 255, 255, 0.667]}
colorString.get('hsl(360, 100%, 50%)'); // {model: 'hsl', value: [0, 100, 50, 1]} (hue normalized)
colorString.get('hwb(60, 3%, 60%)');  // {model: 'hwb', value: [60, 3, 60, 1]}

RGB Color Parsing

Parse RGB, RGBA, hex, and named color formats into RGB values.

/**
 * Parse RGB-based color strings including hex, rgb(), rgba(), and named colors
 * @param color - RGB color string (hex, rgb/rgba syntax, or CSS color name)
 * @returns Array [r, g, b, a] where r,g,b are 0-255 and a is 0-1, or null if invalid
 */
function get.rgb(color: string): number[] | null;

Supported RGB Formats:

  • Hex: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
  • RGB functions: rgb(r, g, b), rgba(r, g, b, a), rgb(r g b), rgba(r g b / a)
  • Percentage RGB: rgb(r%, g%, b%), rgba(r%, g%, b%, a)
  • Named colors: red, blue, transparent, etc.

Usage Examples:

colorString.get.rgb('#FFF');                    // [255, 255, 255, 1]
colorString.get.rgb('blue');                    // [0, 0, 255, 1]
colorString.get.rgb('rgba(200, 60, 60, 0.3)');  // [200, 60, 60, 0.3]
colorString.get.rgb('rgba(200 60 60 / 0.3)');   // [200, 60, 60, 0.3]
colorString.get.rgb('rgba(200 60 60 / 30%)');   // [200, 60, 60, 0.3]
colorString.get.rgb('rgb(50%, 25%, 75%)');      // [128, 64, 191, 1]

HSL Color Parsing

Parse HSL and HSLA color formats.

/**
 * Parse HSL/HSLA color strings
 * @param color - HSL color string in hsl() or hsla() format
 * @returns Array [h, s, l, a] where h is 0-360, s,l are 0-100, a is 0-1, or null if invalid
 */
function get.hsl(color: string): number[] | null;

Supported HSL Formats:

  • Traditional: hsl(h, s%, l%), hsla(h, s%, l%, a)
  • Modern space-separated: hsl(h s% l%), hsl(h s% l% / a)

Usage Examples:

colorString.get.hsl('hsl(360, 100%, 50%)');     // [0, 100, 50, 1]
colorString.get.hsl('hsl(360 100% 50%)');       // [0, 100, 50, 1]
colorString.get.hsl('hsla(360, 60%, 50%, 0.4)'); // [0, 60, 50, 0.4]
colorString.get.hsl('hsl(360 60% 50% / 0.4)');  // [0, 60, 50, 0.4]

HWB Color Parsing

Parse HWB (Hue-Whiteness-Blackness) color format.

/**
 * Parse HWB color strings
 * @param color - HWB color string in hwb() format
 * @returns Array [h, w, b, a] where h is 0-360, w,b are 0-100, a is 0-1, or null if invalid
 */
function get.hwb(color: string): number[] | null;

Supported HWB Formats:

  • Comma-separated: hwb(h, w%, b%), hwb(h, w%, b%, a)
  • Space-separated: hwb(h w% b%), hwb(h w% b% / a)

Usage Examples:

colorString.get.hwb('hwb(60 3% 60%)');          // [60, 3, 60, 1]
colorString.get.hwb('hwb(60, 3%, 60%)');        // [60, 3, 60, 1]
colorString.get.hwb('hwb(60, 3%, 60%, 0.6)');   // [60, 3, 60, 0.6]

Hex Color Generation

Generate hexadecimal color strings from RGB values.

/**
 * Generate hex color string from RGB values
 * @param r - Red component (0-255)
 * @param g - Green component (0-255)
 * @param b - Blue component (0-255)
 * @param a - Alpha component (0-1, optional)
 * @returns Hex color string (#RRGGBB or #RRGGBBAA), or null for invalid input
 */
function to.hex(r: number, g: number, b: number, a?: number): string | null;

Usage Examples:

colorString.to.hex(255, 255, 255);     // "#FFFFFF"
colorString.to.hex(0, 0, 255, 0.4);    // "#0000FF66"

RGB Color Generation

Generate RGB/RGBA color strings from numeric values.

/**
 * Generate rgb() or rgba() color string from RGB values
 * @param r - Red component (0-255)
 * @param g - Green component (0-255)
 * @param b - Blue component (0-255)
 * @param a - Alpha component (0-1, optional)
 * @returns RGB color string (rgb() or rgba()), or null for invalid input
 */
function to.rgb(r: number, g: number, b: number, a?: number): string | null;

/**
 * Generate percentage-based rgb() or rgba() color string from RGB values
 * @param r - Red component (0-255)
 * @param g - Green component (0-255)
 * @param b - Blue component (0-255)
 * @param a - Alpha component (0-1, optional)
 * @returns Percentage RGB color string (rgb() or rgba() with % values), or null for invalid input
 */
function to.rgb.percent(r: number, g: number, b: number, a?: number): string | null;

Usage Examples:

colorString.to.rgb(255, 255, 255);     // "rgb(255, 255, 255)"
colorString.to.rgb(0, 0, 255, 0.4);    // "rgba(0, 0, 255, 0.4)"
colorString.to.rgb.percent(0, 0, 255); // "rgb(0%, 0%, 100%)"
colorString.to.rgb.percent(128, 64, 191, 0.5); // "rgba(50%, 25%, 75%, 0.5)"

HSL Color Generation

Generate HSL/HSLA color strings from HSL values.

/**
 * Generate hsl() or hsla() color string from HSL values
 * @param h - Hue component (0-360)
 * @param s - Saturation component (0-100)
 * @param l - Lightness component (0-100)
 * @param a - Alpha component (0-1, optional)
 * @returns HSL color string (hsl() or hsla()), or null for invalid input
 */
function to.hsl(h: number, s: number, l: number, a?: number): string | null;

Usage Examples:

colorString.to.hsl(360, 100, 100);     // "hsl(360, 100%, 100%)"
colorString.to.hsl(240, 100, 50, 0.7); // "hsla(240, 100%, 50%, 0.7)"

HWB Color Generation

Generate HWB color strings from HWB values.

/**
 * Generate hwb() color string from HWB values
 * @param h - Hue component (0-360)
 * @param w - Whiteness component (0-100)
 * @param b - Blackness component (0-100)
 * @param a - Alpha component (0-1, optional)
 * @returns HWB color string, or null for invalid input
 */
function to.hwb(h: number, w: number, b: number, a?: number): string | null;

Usage Examples:

colorString.to.hwb(50, 3, 15);         // "hwb(50, 3%, 15%)"
colorString.to.hwb(280, 40, 60, 0.3);  // "hwb(280, 40%, 60%, 0.3)"

CSS Keyword Generation

Convert RGB values to CSS color keyword names.

/**
 * Convert RGB values to CSS color keyword name
 * @param r - Red component (0-255)
 * @param g - Green component (0-255)
 * @param b - Blue component (0-255)
 * @param a - Alpha component (0-1, optional)
 * @returns CSS color keyword name, or null if no match
 */
function to.keyword(r: number, g: number, b: number, a?: number): string | null;

Usage Examples:

colorString.to.keyword(255, 255, 0);   // "yellow"
colorString.to.keyword(255, 0, 0);     // "red"
colorString.to.keyword(100, 149, 237); // "cornflowerblue"
colorString.to.keyword(123, 123, 123); // undefined (no keyword match)

Types

type Model = 'rgb' | 'hsl' | 'hwb';

interface ColorString {
  get: {
    (color: string): {model: Model; value: number[]} | null;
    rgb: (color: string) => number[] | null;
    hsl: (color: string) => number[] | null;
    hwb: (color: string) => number[] | null;
  };
  to: {
    hex: (r: number, g: number, b: number, a?: number) => string | null;
    rgb: {
      (r: number, g: number, b: number, a?: number): string | null;
      percent: (r: number, g: number, b: number, a?: number) => string | null;
    };
    keyword: (r: number, g: number, b: number, a?: number) => string | null;
    hsl: (h: number, s: number, l: number, a?: number) => string | null;
    hwb: (h: number, w: number, b: number, a?: number) => string | null;
  };
}

Error Handling

All parsing functions return null for invalid input strings rather than throwing exceptions. This provides predictable error handling:

colorString.get.rgb('invalid color');      // null
colorString.get.hsl('not a color');        // null
colorString.get('completely invalid');     // null

Input Processing and Validation

Value Clamping: During parsing, values are automatically clamped to valid ranges:

  • RGB values: 0-255
  • HSL/HWB hue: normalized to 0-360 degrees using modulo arithmetic
  • HSL saturation/lightness: 0-100%
  • HWB whiteness/blackness: 0-100%
  • Alpha values: 0-1

Special Cases:

  • The keyword 'transparent' is handled as a special case returning [0, 0, 0, 0]
  • Hue values are normalized (e.g., 360° becomes 0°, negative values are corrected)
  • Generator functions do not validate inputs and may produce invalid CSS with bad input values

Format Support Notes:

  • HSL supports both comma-separated hsl(h, s%, l%) and space-separated hsl(h s% l%) formats
  • HWB requires at least one space or comma between components
  • Alpha can be specified as decimal (0.5) or percentage (50%) in modern formats with / separator