or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

analysis.mdchannels.mdconstruction.mdconversion.mdindex.mdmanipulation.md
tile.json

tessl/npm-color

Color conversion and manipulation with CSS string support

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

To install, run

npx @tessl/cli install tessl/npm-color@5.0.0

index.mddocs/

Color

Color is a comprehensive JavaScript library for immutable color conversion and manipulation with full support for CSS color strings. It enables developers to create, modify, and convert colors between multiple color models including RGB, HSL, CMYK, and ANSI256, while maintaining chainable, immutable operations that preserve the original color objects.

Package Information

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

Core Imports

import Color from "color";

For CommonJS:

const Color = require("color");

Basic Usage

import Color from "color";

// Create colors from various input formats
const red = Color('#FF0000');
const blue = Color('rgb(0, 0, 255)');
const green = Color({r: 0, g: 255, b: 0});

// Chain operations (immutable)
const lightPink = Color('#FF1493')
  .lighten(0.3)
  .desaturate(0.2)
  .alpha(0.8);

// Convert between color models
console.log(lightPink.hsl().string());  // 'hsla(328, 74%, 75%, 0.8)'
console.log(lightPink.hex());          // #FF69B4

// Analyze colors
console.log(blue.contrast(Color('white')));  // 8.59
console.log(blue.isLight());                 // false

Architecture

Color is built around several key components:

  • Immutable Design: All operations return new Color instances, preserving original objects
  • Multiple Input Formats: Supports CSS strings, objects, arrays, numbers, and other Color instances
  • Color Model Support: 12+ color spaces with full conversion capabilities
  • Chainable API: Fluent interface for complex color manipulations
  • CSS Integration: Full support for CSS color formats and string generation
  • Analysis Tools: WCAG-compliant luminosity and contrast calculations

Capabilities

Color Construction

Core constructor and static factory methods for creating Color instances from various input formats.

function Color(object?: ColorLike, model?: string): ColorInstance;

// Static constructors for each color model
function rgb(...values: number[]): ColorInstance;
function hsl(...values: number[]): ColorInstance;
function hsv(...values: number[]): ColorInstance;
function hwb(...values: number[]): ColorInstance;
function cmyk(...values: number[]): ColorInstance;
function xyz(...values: number[]): ColorInstance;
function lab(...values: number[]): ColorInstance;
function lch(...values: number[]): ColorInstance;
function ansi16(...values: number[]): ColorInstance;
function ansi256(...values: number[]): ColorInstance;
function hcg(...values: number[]): ColorInstance;
function apple(...values: number[]): ColorInstance;

type ColorLike = ColorInstance | string | ArrayLike<number> | number | Record<string, any>;

Color Construction

Color Conversion

Convert colors between different color models and output formats, including CSS strings, objects, and arrays.

// Model conversion methods
rgb(...args?: number[]): ColorInstance;
hsl(...args?: number[]): ColorInstance;
hsv(...args?: number[]): ColorInstance;
hwb(...args?: number[]): ColorInstance;
cmyk(...args?: number[]): ColorInstance;
xyz(...args?: number[]): ColorInstance;
lab(...args?: number[]): ColorInstance;
lch(...args?: number[]): ColorInstance;
ansi16(...args?: number[]): ColorInstance;
ansi256(...args?: number[]): ColorInstance;
hcg(...args?: number[]): ColorInstance;
apple(...args?: number[]): ColorInstance;

// Output format methods
string(places?: number): string;
percentString(places?: number): string;
array(): number[];
object(): ColorObject;
unitArray(): number[];
unitObject(): {r: number; g: number; b: number; alpha?: number};
round(places?: number): ColorInstance;
hex(): string;
hexa(): string;
keyword(): string;
rgbNumber(): number;

Color Conversion

Color Analysis

Analyze color properties including luminosity, contrast ratios, and accessibility compliance for WCAG standards.

luminosity(): number;
contrast(color2: ColorInstance): number;
level(color2: ColorInstance): 'AAA' | 'AA' | '';
isDark(): boolean;
isLight(): boolean;

Color Analysis

Color Manipulation

Immutable color manipulation methods for adjusting lightness, saturation, hue, and alpha values.

lighten(ratio: number): ColorInstance;
darken(ratio: number): ColorInstance;
saturate(ratio: number): ColorInstance;
desaturate(ratio: number): ColorInstance;
whiten(ratio: number): ColorInstance;
blacken(ratio: number): ColorInstance;
fade(ratio: number): ColorInstance;
opaquer(ratio: number): ColorInstance;
rotate(degrees: number): ColorInstance;
negate(): ColorInstance;
grayscale(): ColorInstance;
mix(mixinColor: ColorInstance, weight?: number): ColorInstance;

Color Manipulation

Channel Access

Get and set individual color channel values across different color models with type-safe access patterns.

// Alpha channel
alpha(): number;
alpha(value: number): ColorInstance;

// RGB channels
red(): number;
red(value: number): ColorInstance;
green(): number;
green(value: number): ColorInstance;
blue(): number;
blue(value: number): ColorInstance;

// HSL channels
hue(): number;
hue(value: number): ColorInstance;
saturationl(): number;
saturationl(value: number): ColorInstance;
lightness(): number;
lightness(value: number): ColorInstance;

// Other color model channels available...

Channel Access

Core Types

interface ColorInstance {
  toString(): string;
  toJSON(): ColorJson;
  string(places?: number): string;
  percentString(places?: number): string;
  array(): number[];
  object(): ColorObject;
  unitArray(): number[];
  unitObject(): {r: number; g: number; b: number; alpha?: number | undefined};
  round(places?: number): ColorInstance;
  
  // Alpha and RGB channel access
  alpha(): number;
  alpha(value: number): ColorInstance;
  red(): number;
  red(value: number): ColorInstance;
  green(): number;
  green(value: number): ColorInstance;
  blue(): number;
  blue(value: number): ColorInstance;
  
  // HSL channel access
  hue(): number;
  hue(value: number): ColorInstance;
  saturationl(): number;
  saturationl(value: number): ColorInstance;
  lightness(): number;
  lightness(value: number): ColorInstance;
  
  // HSV channel access
  saturationv(): number;
  saturationv(value: number): ColorInstance;
  value(): number;
  value(value: number): ColorInstance;
  
  // HCG channel access
  chroma(): number;
  chroma(value: number): ColorInstance;
  gray(): number;
  gray(value: number): ColorInstance;
  
  // HWB channel access
  white(): number;
  white(value: number): ColorInstance;
  wblack(): number;
  wblack(value: number): ColorInstance;
  
  // CMYK channel access
  cyan(): number;
  cyan(value: number): ColorInstance;
  magenta(): number;
  magenta(value: number): ColorInstance;
  yellow(): number;
  yellow(value: number): ColorInstance;
  black(): number;
  black(value: number): ColorInstance;
  
  // XYZ channel access
  x(): number;
  x(value: number): ColorInstance;
  y(): number;
  y(value: number): ColorInstance;
  z(): number;
  z(value: number): ColorInstance;
  
  // LAB channel access
  l(): number;
  l(value: number): ColorInstance;
  a(): number;
  a(value: number): ColorInstance;
  b(): number;
  b(value: number): ColorInstance;
  
  // Output format methods
  keyword(): string;
  keyword<V extends string>(value: V): ColorInstance;
  hex(): string;
  hex<V extends string>(value: V): ColorInstance;
  hexa(): string;
  hexa<V extends string>(value: V): ColorInstance;
  rgbNumber(): number;
  
  // Analysis methods
  luminosity(): number;
  contrast(color2: ColorInstance): number;
  level(color2: ColorInstance): 'AAA' | 'AA' | '';
  isDark(): boolean;
  isLight(): boolean;
  
  // Manipulation methods
  negate(): ColorInstance;
  lighten(ratio: number): ColorInstance;
  darken(ratio: number): ColorInstance;
  saturate(ratio: number): ColorInstance;
  desaturate(ratio: number): ColorInstance;
  whiten(ratio: number): ColorInstance;
  blacken(ratio: number): ColorInstance;
  grayscale(): ColorInstance;
  fade(ratio: number): ColorInstance;
  opaquer(ratio: number): ColorInstance;
  rotate(degrees: number): ColorInstance;
  mix(mixinColor: ColorInstance, weight?: number): ColorInstance;
  
  // Color model conversion methods
  rgb(...arguments_: number[]): ColorInstance;
  hsl(...arguments_: number[]): ColorInstance;
  hsv(...arguments_: number[]): ColorInstance;
  hwb(...arguments_: number[]): ColorInstance;
  cmyk(...arguments_: number[]): ColorInstance;
  xyz(...arguments_: number[]): ColorInstance;
  lab(...arguments_: number[]): ColorInstance;
  lch(...arguments_: number[]): ColorInstance;
  ansi16(...arguments_: number[]): ColorInstance;
  ansi256(...arguments_: number[]): ColorInstance;
  hcg(...arguments_: number[]): ColorInstance;
  apple(...arguments_: number[]): ColorInstance;
}

type ColorJson = {
  model: string;
  color: number[];
  valpha: number;
};

type ColorObject = {
  alpha?: number;
} & Record<string, number>;