or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-postcss-colormin

Minify colors in your CSS files with PostCSS.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/postcss-colormin@7.0.x

To install, run

npx @tessl/cli install tessl/npm-postcss-colormin@7.0.0

index.mddocs/

PostCSS Colormin

PostCSS Colormin is a PostCSS plugin that automatically minifies color values in CSS files by converting them to their shortest possible representation. It intelligently transforms color formats (RGB, HSL, hex, named colors) based on browser compatibility, optimizing file size while maintaining visual accuracy.

Package Information

  • Package Name: postcss-colormin
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install postcss-colormin

Core Imports

const colormin = require("postcss-colormin");

For standalone color minification:

const minifyColor = require("postcss-colormin/src/minifyColor");

For TypeScript:

import colormin from "postcss-colormin";
import minifyColor from "postcss-colormin/src/minifyColor";

Basic Usage

const postcss = require("postcss");
const colormin = require("postcss-colormin");

const css = 'h1 {color: rgba(255, 0, 0, 1)}';
const result = postcss([colormin()]).process(css).css;
console.log(result); // => 'h1 {color:red}'

With options:

const result = postcss([
  colormin({
    alphaHex: true,
    transparent: false,
    name: true
  })
]).process(css);

Architecture

PostCSS Colormin is built around several key components:

  • Plugin Creator: Main function that creates PostCSS plugin instances with browser-aware optimizations
  • Color Transformer: Core transformation engine that walks CSS value trees and minifies colors
  • Browser Integration: Automatic browserslist integration for context-aware color format selection
  • Utility Function: Standalone color minification function for programmatic use
  • Caching System: Internal caching to optimize repeated transformations

Capabilities

PostCSS Plugin

Creates a PostCSS plugin for automatic color minification in CSS processing pipelines.

/**
 * Creates a PostCSS plugin for color minification
 * @param config - Optional configuration object
 * @returns PostCSS plugin instance
 */
declare function pluginCreator(config?: Options): import("postcss").Plugin;

/**
 * Static property identifying this as a PostCSS plugin
 */
pluginCreator.postcss: true;

// CommonJS export structure
export = pluginCreator;

Usage Examples:

const postcss = require("postcss");
const colormin = require("postcss-colormin");

// Basic usage
const result = await postcss([colormin()])
  .process('h1 { color: rgba(255, 0, 0, 1) }');
// Output: 'h1 { color: red }'

// With custom browserslist
const result = await postcss([
  colormin({
    overrideBrowserslist: ['Chrome >= 62']
  })
]).process('h1 { color: hsla(0, 100%, 50%, 0.4) }');
// Output: 'h1 { color: #f006 }' (using 4-digit hex)

// Disable specific optimizations
const result = await postcss([
  colormin({
    transparent: false,  // Don't convert rgba(0,0,0,0) to transparent
    name: false          // Don't convert hex to named colors
  })
]).process('h1 { color: #ff0000; background: rgba(0,0,0,0) }');

Standalone Color Minification

Minifies individual color values without PostCSS processing.

/**
 * Performs color value minification
 * @param input - CSS color value string
 * @param options - Minification options
 * @returns Minified color value string
 */
declare function minifyColor(input: string, options?: MinifyColorOptions): string;

// CommonJS export structure
export = minifyColor;

Usage Examples:

const minifyColor = require("postcss-colormin/src/minifyColor");

// Basic color minification
minifyColor("rgba(255, 0, 0, 1)"); // => "red"
minifyColor("#ffffff"); // => "#fff"
minifyColor("hsl(0, 100%, 50%)"); // => "red"

// With options
minifyColor("rgba(255, 0, 0, 0.5)", { 
  alphaHex: true 
}); // => "#ff0080"

// Invalid colors pass through
minifyColor("not-a-color"); // => "not-a-color"
minifyColor("rgb(50%, 23, 54)"); // => "rgb(50%, 23, 54)"

Configuration Options

MinifyColorOptions

Color minification behavior configuration.

interface MinifyColorOptions {
  /** Enable hex color optimization (default: true) */
  hex?: boolean;
  /** Enable 4/8-digit hex with alpha channel (default: false, browser-dependent) */
  alphaHex?: boolean;
  /** Enable RGB format optimization (default: true) */
  rgb?: boolean;
  /** Enable HSL format optimization (default: true) */
  hsl?: boolean;
  /** Enable named color optimization (default: true) */
  name?: boolean;
  /** Enable transparent keyword optimization (default: true, browser-dependent) */
  transparent?: boolean;
}

Browser Configuration Options

Browserslist integration for browser-aware optimizations.

interface AutoprefixerOptions {
  /** Override browserslist configuration */
  overrideBrowserslist?: string | string[];
}

interface BrowserslistOptions {
  /** Custom usage statistics for browserslist */
  stats?: any;
  /** Path for browserslist config file resolution */
  path?: string;
  /** Environment for browserslist (e.g., 'production', 'development') */
  env?: string;
}

Complete Options Type

type Options = MinifyColorOptions & AutoprefixerOptions & BrowserslistOptions;

Color Transformation Examples

Format Conversions

// Hex to named colors
minifyColor("#ff0000"); // => "red"
minifyColor("#00ff00"); // => "#0f0" (shorter than "lime")

// RGB/RGBA to optimal format  
minifyColor("rgb(255, 0, 0)"); // => "red"
minifyColor("rgba(255, 0, 0, 0.5)"); // => "rgba(255,0,0,.5)"
minifyColor("rgba(255, 0, 0, 1)"); // => "red"

// HSL/HSLA to optimal format
minifyColor("hsl(0, 100%, 50%)"); // => "red" 
minifyColor("hsla(0, 100%, 50%, 0.5)"); // => "rgba(255,0,0,.5)"

// Transparent handling
minifyColor("rgba(0, 0, 0, 0)"); // => "transparent"
minifyColor("hsla(0, 0%, 0%, 0)"); // => "transparent"

Case Handling

// Case normalization
minifyColor("RED"); // => "red"
minifyColor("#FFFFFF"); // => "#fff"
minifyColor("RGB(255, 0, 0)"); // => "red"

Browser-Specific Optimizations

// Modern browsers with alphaHex support
const modernOptions = { alphaHex: true };
minifyColor("rgba(255, 0, 0, 0.4)", modernOptions); // => "#f006"

// Legacy browser compatibility  
const legacyOptions = { transparent: false };
minifyColor("rgba(0, 0, 0, 0)", legacyOptions); // => "rgba(0,0,0,0)"

CSS Processing Behavior

Properties Processed

The plugin processes color values in most CSS properties but excludes certain properties where colors should not be modified:

  • Processed: color, background, border-color, box-shadow, etc.
  • Excluded: font, font-family, src, filter, -webkit-tap-highlight-color, composes

Value Types Handled

/* Supported color formats */
.example {
  /* Named colors */
  color: red; /* => red (unchanged) */
  color: yellow; /* => #ff0 */
  
  /* Hex colors */
  background: #ffffff; /* => #fff */
  border: #f00; /* => red */
  
  /* RGB/RGBA functions */
  box-shadow: rgb(255, 255, 255); /* => #fff */
  color: rgba(255, 0, 0, 0.5); /* => rgba(255,0,0,.5) */
  
  /* HSL/HSLA functions */
  background: hsl(0, 100%, 50%); /* => red */
  color: hsla(134, 50%, 50%, 1); /* => #40bf5e */
  
  /* Complex values with multiple colors */
  background: linear-gradient(#ff0000, yellow); /* => linear-gradient(red, #ff0) */
}

/* Values that are NOT processed */
.excluded {
  font-family: black; /* Unchanged - font names */
  filter: sepia(100%); /* Unchanged - filter functions */
  content: "red"; /* Unchanged - string content */
}

Math Function Handling

/* CSS math functions are excluded from color processing */
.math {
  width: calc(100vw / 2 - 6px + 0); /* Unchanged */
  height: min(100vh, 500px); /* Unchanged */
}