@flemminghansen/color-tools

A small collection of tools to make it easier to work with and convert colors in JavaScript/TypeScript. It provides functions for converting between HEX, RGBA, and HSLA formats, mixing colors, and calculating brightness and contrast ratios.

Table of Contents

• @flemminghansen/color-tools
  • Table of Contents
  • Features
  • Installation
  • Example
  • API Documentation
    • Color Conversion Functions
    • Color Mixing & Channel Utilities
    • Brightness and Contrast
    • HSLA String Utilities

Features

• Color Conversions:
  • Convert HEX strings to RGBA/HSLA objects.
  • Convert RGBA and HSLA values back to HEX strings.
• Color Mixing:
  • Blend individual color channels by a specified percentage.
  • Mix two colors gradually in a given number of steps.
• Brightness & Contrast:
  • Calculate the brightness factor for a color channel.
  • Compute overall brightness for an RGB color.
  • Determine the contrast ratio between two brightness values.
• HSLA Utilities:
  • Validate and adjust HSLA values.
  • Generate formatted HSLA strings, with optional modifications.

Installation

Install via npm:

npm install @flemminghansen/color-tools

Example

import {
  hexToRGBA,
  hexToHSLA,
  hslaToHex,
  rgbaToHex,
  hslaToRGBA,
  rgbaToHSLA,
  mixColors,
  getRGBBrightness,
  getContrastRatio,
  getHSLaAsString,
} from '@flemminghansen/color-tools';

// Convert HEX to RGBA
const rgba = hexToRGBA('#3498db');
console.log(rgba); // { R: 52, G: 152, B: 219, A: 1 }

// Convert HEX to HSLA
const hsla = hexToHSLA('#3498db');
console.log(hsla);

// Mix two colors (in a simple way)
const color1 = { R: 255, G: 0, B: 0 };
const color2 = { R: 0, G: 0, B: 255 };
const mixedColor = mixColors(color1, color2, 10);
console.log(mixedColor);

// Get brightness of an RGB color
const brightness = getRGBBrightness(52, 152, 219);
console.log(`Brightness: ${brightness}`);

// Get contrast ratio between two brightness values
const contrast = getContrastRatio(0.5, 0.8);
console.log(`Contrast Ratio: ${contrast}`);

// Generate an HSLA string with optional modifications
const hslaString = getHSLaAsString({ H: 200, S: 50, L: 40, A: 1 }, { L: 10 });
console.log(hslaString);

API Documentation

Color Conversion Functions

• hexToRGBA(hex: string): { R: number; G: number; B: number; A: number } Converts a HEX color string to an RGBA object. Example: hexToRGBA("#ff5733")

• hexToHSLA(hex: string): { H: number; S: number; L: number; A: number } Converts a HEX color string to an HSLA object by first converting it to RGBA.

• hslaToHex(H: number, S: number, L: number, A?: number): string Converts HSLA values to a HEX string. Note: The alpha channel is appended only if it’s less than 1.

• rgbaToHex(R: number, G: number, B: number, A?: number): string Converts RGBA values to a HEX string.

• hslaToRGBA(H: number, S: number, L: number, A?: number): IRGBa Converts HSLA values to an RGBA object.

• rgbaToHSLA(R: number, G: number, B: number, A?: number): { H: number; S: number; L: number; A: number } Converts RGBA values to an HSLA object.

Color Mixing & Channel Utilities

• channelBlendByPercentage(percentage: number, baseChannel: number, mixChannel: number): number Blends a single color channel between two values based on a percentage.

• mixColors(firstColor: IRGB, oppositeColor: IRGB, steps: number): IRGB Mixes two colors by blending their RGB channels gradually over the specified number of steps.

Brightness and Contrast

• getBrightnessFactor(value: number): number Computes a normalized brightness factor for a single RGB channel.

• getRGBBrightness(R: number, G: number, B: number): number Calculates overall brightness for an RGB color using weighted factors for red, green, and blue.

• getContrastRatio(brightness1: number, brightness2: number): number Computes the contrast ratio between two brightness values.

HSLA String Utilities

• getValidatedHSLAValues({ H, S, L, A }: IHSLa): IHSLa Validates and clamps HSLA values within expected ranges.

• getHSLaAsString(baseHSLA: IHSLa, modifyHSLA?: Partial): string Returns a formatted HSLA string. Optionally, modifications can be applied to the base values.

License MIT