{% extends "base.html.jinja" %} {% block title %}API Reference — hue.gl{% endblock %} {% block content %}

API

API Reference

Complete documentation for the hue.gl TypeScript/JavaScript API.

Installation

npm install hue.gl

Import the library:

import { ColorSwatch, ColorScheme, generatePalette } from 'hue.gl';

ColorSwatch

Represents a single color with LCH values and conversion methods.

Constructor

new ColorSwatch(hue: number, shade: number, name: string, h: number, c: number, l: number)
Parameter Type Description
hue number Hue index (0-24)
shade number Shade value (50, 100, 200, 300, 400, 500, 600, 700, 800)
name string Human-readable name (e.g., "Red 500")
h number LCH Hue angle (0-360)
c number LCH Chroma (0-230)
l number LCH Lightness (0-100)

Methods

getHex(): string

Returns the color as a hex string.

const swatch = new ColorSwatch(0, 500, 'Red 500', 0, 100, 55); swatch.getHex(); // "#e03131"
getRGB(): [number, number, number]

Returns the color as an RGB tuple (0-255 values).

swatch.getRGB(); // [224, 49, 49]
getLCH(): { l: number, c: number, h: number }

Returns the original LCH values.

swatch.getLCH(); // { l: 55, c: 100, h: 0 }
getHSL(): { h: number, s: number, l: number }

Returns the color as HSL values.

swatch.getHSL(); // { h: 0, s: 78, l: 53 }
getCMYK(): { c: number, m: number, y: number, k: number }

Returns the color as CMYK values (0-100).

swatch.getCMYK(); // { c: 0, m: 78, y: 78, k: 12 }
getP3(): string

Returns the color in CSS color() format for Display P3.

swatch.getP3(); // "color(display-p3 0.85 0.2 0.2)"
getOKLCH(): { l: number, c: number, h: number }

Returns the color in OKLCH color space.

swatch.getOKLCH(); // { l: 0.55, c: 0.21, h: 24 }
clone(): ColorSwatch

Creates a copy of the swatch.

isInGamut(): boolean

Returns true if the color is within sRGB gamut.

ColorScheme

Generates complete color palettes from configuration.

Constructor

new ColorScheme(config?: ColorSchemeConfig)
Parameter Type Description
config ColorSchemeConfig Optional configuration object (defaults to built-in hue.gl config)

ColorSchemeConfig

interface ColorSchemeConfig { hues: HueConfig[]; shades: ShadeConfig[]; chroma: number; } interface HueConfig { name: string; angle: number; } interface ShadeConfig { value: number; lightness: number; }

Methods

generate(): void

Generates all color swatches based on configuration.

getColor(hueName: string, shade: number): ColorSwatch | undefined

Gets a specific color by hue name and shade.

const scheme = new ColorScheme(); scheme.generate(); const red500 = scheme.getColor('red', 500);
getHue(hueName: string): ColorSwatch[]

Gets all shades for a specific hue.

const allReds = scheme.getHue('red'); // [Red 50, Red 100, Red 200, ...]
getShade(shade: number): ColorSwatch[]

Gets all colors at a specific shade level.

const all500s = scheme.getShade(500); // [Red 500, Orange 500, Yellow 500, ...]
getAllColors(): ColorSwatch[]

Gets all generated colors as a flat array.

toJSON(): object

Exports the palette as a JSON-serializable object.

toCSSVariables(): string

Generates CSS custom properties for all colors.

scheme.toCSSVariables(); // ":root { --hue-red-50: #fff5f5; --hue-red-100: #ffe3e3; ... }"

Utility Functions

rgb2cmyk(r: number, g: number, b: number): CMYK

Converts RGB values (0-255) to CMYK (0-100).

import { rgb2cmyk } from 'hue.gl'; rgb2cmyk(224, 49, 49); // { c: 0, m: 78, y: 78, k: 12 }
colorToHex(r: number, g: number, b: number): string

Converts RGB values to a hex string.

import { colorToHex } from 'hue.gl'; colorToHex(224, 49, 49); // "#e03131"
convertRGBtoHex(rgb: [number, number, number]): string

Converts an RGB tuple to a hex string.

import { convertRGBtoHex } from 'hue.gl'; convertRGBtoHex([224, 49, 49]); // "#e03131"
pad(value: string | number, length?: number): string

Pads a value with leading zeros.

import { pad } from 'hue.gl'; pad(15, 2); // "15" pad(5, 2); // "05" pad("f", 2); // "0f"

Constants

HUE_NAMES

Array of all hue names in order:

import { HUE_NAMES } from 'hue.gl'; // ['red', 'vermilion', 'orange', 'amber', 'yellow', 'lime', ...]

SHADE_VALUES

Array of all shade values:

import { SHADE_VALUES } from 'hue.gl'; // [50, 100, 200, 300, 400, 500, 600, 700, 800]

DEFAULT_CONFIG

The default ColorScheme configuration:

import { DEFAULT_CONFIG } from 'hue.gl'; // { hues: [...], shades: [...], chroma: 100 }

TypeScript Types

// Color value types type HexColor = string; type RGBTuple = [number, number, number]; interface LCH { l: number; c: number; h: number; } interface HSL { h: number; s: number; l: number; } interface CMYK { c: number; m: number; y: number; k: number; } // Hue name literal type type HueName = | 'red' | 'vermilion' | 'orange' | 'amber' | 'yellow' | 'lime' | 'chartreuse' | 'green' | 'emerald' | 'teal' | 'cyan' | 'sky' | 'azure' | 'blue' | 'indigo' | 'violet' | 'purple' | 'magenta' | 'pink' | 'rose' | 'crimson' | 'gray'; // Shade value literal type type ShadeValue = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800;

Examples

Generate a Custom Palette

import { ColorScheme } from 'hue.gl'; const customScheme = new ColorScheme({ hues: [ { name: 'primary', angle: 220 }, { name: 'secondary', angle: 340 }, { name: 'accent', angle: 45 }, ], shades: [ { value: 100, lightness: 95 }, { value: 500, lightness: 55 }, { value: 900, lightness: 15 }, ], chroma: 80, }); customScheme.generate(); console.log(customScheme.getColor('primary', 500).getHex());

Generate CSS Variables

import { ColorScheme } from 'hue.gl'; import fs from 'fs'; const scheme = new ColorScheme(); scheme.generate(); const css = scheme.toCSSVariables(); fs.writeFileSync('colors.css', css);

Access Pre-built Colors

import { colors } from 'hue.gl'; // Direct access to hex values const red500 = colors.red[500]; // "#e03131" const blue200 = colors.blue[200]; // "#a5d8ff" // Use in React const Button = ({ variant }) => ( <button style={{ background: colors[variant][500] }}> Click me </button> );
{% endblock %}