pastel-wasm

WebAssembly color manipulation library - All the power of color operations in your browser, with zero server calls!

Overview

pastel-wasm is a high-performance WebAssembly library that provides comprehensive color manipulation capabilities directly in the browser. Built with Rust and compiled to WASM, it offers:

• ✨ Zero latency - All processing happens client-side
• 🚀 Blazing fast - Native performance via WebAssembly
• 📦 Lightweight - Only 132KB WASM bundle
• 🎨 Feature-complete - All essential color operations
• 🔒 Type-safe - Full TypeScript support
• 🌐 Works offline - No internet connection required

Features

Color Operations

• Parse any color format (hex, rgb, hsl, named colors)
• Convert between color spaces (RGB, HSL, HSV, Lab, LCH)
• Lighten, darken, saturate, desaturate
• Rotate hue, complement, mix colors
• Calculate luminance, brightness, contrast

Color Generation

• Random color generation (vivid or normal)
• Color gradients
• Color harmony palettes (monochromatic, analogous, complementary, triadic, tetradic)

Accessibility

• Color blindness simulation (protanopia, deuteranopia, tritanopia)
• Text color optimization for contrast
• WCAG contrast ratio calculation

Named Colors

• 148 CSS/X11 named colors
• Search and filter by name

Installation

npm install pastel-wasm
# or
yarn add pastel-wasm
# or
pnpm add pastel-wasm

Usage

Basic Example

import * as pastel from 'pastel-wasm';

// Initialize (call once)
pastel.init();

// Parse a color
const info = pastel.parse_color('#ff0099');
console.log(info);
// {
//   input: "#ff0099",
//   hex: "#ff0099",
//   rgb: [255, 0, 153],
//   hsl: [320, 1.0, 0.5],
//   brightness: 0.498,
//   luminance: 0.286,
//   is_light: false
// }

// Manipulate colors
const lighter = pastel.lighten_color('#ff0099', 0.2);    // "#ff66c2"
const darker = pastel.darken_color('#ff0099', 0.1);      // "#cc007a"
const saturated = pastel.saturate_color('#888888', 0.5); // "#cc4444"

// Mix colors
const mixed = pastel.mix_colors('#ff0000', '#0000ff', 0.5); // "#800080"

// Generate palettes
const palette = pastel.generate_palette('#3498db', 'triadic');
// ["#3498db", "#34db98", "#db9834"]

// Generate gradients
const gradient = pastel.generate_gradient('#ff0000', '#0000ff', 10);
// Array of 10 colors from red to blue

// Random colors
const random = pastel.generate_random_colors(5, true); // 5 vivid colors

Accessibility

// Get optimal text color for a background
const textColor = pastel.get_text_color('#3498db');
console.log(textColor); // "#ffffff" (white text on blue background)

// Calculate contrast ratio
const contrast = pastel.calculate_contrast('#3498db', '#ffffff');
console.log(contrast); // 4.35

// Simulate color blindness
const protanopia = pastel.simulate_protanopia('#ff0099');
const deuteranopia = pastel.simulate_deuteranopia('#ff0099');
const tritanopia = pastel.simulate_tritanopia('#ff0099');

Named Colors

// Get all named colors
const allColors = pastel.get_all_named_colors();
console.log(allColors.length); // 148

// Search named colors
const results = pastel.search_named_colors('blue');
// [{name: "blue", hex: "#0000ff"}, {name: "darkblue", hex: "#00008b"}, ...]

Color Distance

// Calculate color distance (CIE76 or CIEDE2000)
const distance = pastel.color_distance('#ff0000', '#00ff00', true);
console.log(distance); // Perceptual distance using CIEDE2000

Supported Color Formats

Input Formats

• Hex: #ff0099, #f09, ff0099, #ff0099aa
• RGB: rgb(255, 0, 153), rgba(255, 0, 153, 0.5)
• HSL: hsl(280, 100%, 50%), hsla(280, 100%, 50%, 0.8)
• Named: red, rebeccapurple, lightslategray

Color Spaces

• RGB - Red, Green, Blue
• HSL - Hue, Saturation, Lightness
• HSV - Hue, Saturation, Value
• Lab - CIELab (perceptually uniform)
• LCH - Cylindrical Lab

API Reference

Color Information

• parse_color(color: string): ColorInfo - Parse and analyze a color

Color Manipulation

• lighten_color(color: string, amount: number): string
• darken_color(color: string, amount: number): string
• saturate_color(color: string, amount: number): string
• desaturate_color(color: string, amount: number): string
• rotate_hue(color: string, degrees: number): string
• complement_color(color: string): string
• mix_colors(color1: string, color2: string, fraction: number): string

Color Generation

• generate_random_colors(count: number, vivid: boolean): string[]
• generate_gradient(start: string, end: string, steps: number): string[]
• generate_palette(base: string, scheme: string): string[]
  • Schemes: monochromatic, analogous, complementary, triadic, tetradic

Accessibility

• get_text_color(bg_color: string): string
• calculate_contrast(color1: string, color2: string): number
• simulate_protanopia(color: string): string
• simulate_deuteranopia(color: string): string
• simulate_tritanopia(color: string): string

Named Colors

• get_all_named_colors(): NamedColor[]
• search_named_colors(query: string): NamedColor[]

Utilities

• color_distance(color1: string, color2: string, use_ciede2000: boolean): number
• version(): string

Performance

| Operation | Time (avg) | |-----------|------------| | Parse color | < 0.1ms | | Lighten/Darken | < 0.1ms | | Generate gradient (10 steps) | < 0.5ms | | Generate palette | < 0.3ms | | Colorblind simulation | < 0.2ms |

Benchmarks run on M1 MacBook Pro

Browser Support

• ✅ Chrome 57+
• ✅ Firefox 52+
• ✅ Safari 11+
• ✅ Edge 16+

Requires WebAssembly support.

Development

Build from Source

# Install Rust and wasm-pack
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

# Clone the repository
git clone https://github.com/pastel-wasm/pastel-wasm
cd pastel-wasm

# Build
wasm-pack build --target bundler --out-dir pkg

# Build for different targets
wasm-pack build --target web --out-dir pkg-web      # For vanilla JS
wasm-pack build --target nodejs --out-dir pkg-node  # For Node.js

Run Tests

wasm-pack test --headless --firefox --chrome

Comparison

vs pastel-api (REST API)

| Feature | pastel-wasm | pastel-api | |---------|-------------|------------| | Latency | ~0ms | ~50-200ms | | Offline | ✅ Yes | ❌ No | | Server required | ❌ No | ✅ Yes | | Bundle size | 132KB | N/A | | Rate limiting | ❌ No | ✅ Yes |

Recommendation: Use pastel-wasm for client-side applications (React, Vue, Svelte, etc). Use pastel-api for server-side integrations or sharing color operations via URLs.

vs JavaScript Libraries

• Smaller - Many JS color libraries are 150-300KB
• Faster - WebAssembly native performance
• More accurate - Precise color space conversions

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Related Projects

• pastel - The original CLI tool
• pastel-api - REST API wrapper
• pastel-ui - Web UI for color manipulation

Acknowledgments

Inspired by the excellent pastel CLI tool by @sharkdp.