tessl/npm-pdfkit

A PDF generation library for Node.js with comprehensive text, graphics, and form support

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Color Management

Name: tessl/npm-pdfkit
Author: tessl

Color handling with support for RGB, CMYK, hex colors, gradients, patterns, and spot colors with comprehensive opacity control.

Capabilities

Basic Color Control

Methods for setting fill and stroke colors with opacity support.

/**
 * Set fill color
 * @param color - Color value in various formats
 * @param opacity - Opacity (0.0 to 1.0)
 * @returns Document instance for chaining
 */
fillColor(color: ColorValue, opacity?: number): PDFDocument;

/**
 * Set stroke color
 * @param color - Color value in various formats
 * @param opacity - Opacity (0.0 to 1.0)
 * @returns Document instance for chaining
 */
strokeColor(color: ColorValue, opacity?: number): PDFDocument;

type ColorValue = 
  | string                              // Hex or named color
  | [number, number, number]            // RGB array (0-255)
  | [number, number, number, number]    // CMYK array (0-100)
  | Gradient                            // Gradient object
  | Pattern;                            // Pattern array

Usage Examples:

// Hex colors
doc.fillColor('#FF0000')      // Red
   .rect(100, 100, 50, 50)
   .fill();

doc.fillColor('#00F')         // Short hex blue
   .rect(200, 100, 50, 50)
   .fill();

// RGB colors (0-255)
doc.fillColor([255, 165, 0])  // Orange
   .rect(300, 100, 50, 50)
   .fill();

// CMYK colors (0-100)
doc.fillColor([0, 100, 100, 0])  // Red in CMYK
   .rect(400, 100, 50, 50)
   .fill();

// Named colors
doc.fillColor('lightblue')
   .rect(100, 200, 50, 50)
   .fill();

// With opacity
doc.fillColor('red', 0.5)     // 50% transparent red
   .rect(200, 200, 50, 50)
   .fill();

Opacity Control

Methods for controlling transparency independently for fill and stroke.

/**
 * Set both fill and stroke opacity
 * @param opacity - Opacity value (0.0 to 1.0)
 * @returns Document instance for chaining
 */
opacity(opacity: number): PDFDocument;

/**
 * Set fill opacity only
 * @param opacity - Fill opacity (0.0 to 1.0)
 * @returns Document instance for chaining
 */
fillOpacity(opacity: number): PDFDocument;

/**
 * Set stroke opacity only
 * @param opacity - Stroke opacity (0.0 to 1.0)
 * @returns Document instance for chaining
 */
strokeOpacity(opacity: number): PDFDocument;

Usage Examples:

// Global opacity
doc.opacity(0.7)
   .fillColor('blue')
   .strokeColor('red')
   .rect(100, 100, 100, 50)
   .fillAndStroke();

// Independent opacity control
doc.fillOpacity(0.3)
   .strokeOpacity(1.0)
   .fillColor('green')
   .strokeColor('black')
   .circle(200, 200, 40)
   .fillAndStroke();

Linear Gradients

Create and use linear gradients for sophisticated color effects.

/**
 * Create linear gradient
 * @param x1 - Start X coordinate
 * @param y1 - Start Y coordinate
 * @param x2 - End X coordinate
 * @param y2 - End Y coordinate
 * @returns Gradient object for use with colors
 */
linearGradient(x1: number, y1: number, x2: number, y2: number): Gradient;

interface Gradient {
  /** Add color stop to gradient */
  stop(offset: number, color: ColorValue, opacity?: number): Gradient;
}

Usage Examples:

// Simple two-color gradient
const gradient1 = doc.linearGradient(100, 100, 200, 100)
  .stop(0, 'red')
  .stop(1, 'blue');

doc.rect(100, 100, 100, 50)
   .fill(gradient1);

// Multi-stop gradient
const gradient2 = doc.linearGradient(100, 200, 100, 300)
  .stop(0, 'yellow')
  .stop(0.5, 'orange') 
  .stop(1, 'red');

doc.rect(100, 200, 100, 100)
   .fill(gradient2);

// Diagonal gradient with opacity
const gradient3 = doc.linearGradient(250, 100, 350, 200)
  .stop(0, 'purple', 1.0)
  .stop(1, 'purple', 0.0);  // Fade to transparent

doc.rect(250, 100, 100, 100)
   .fill(gradient3);

Radial Gradients

Create radial gradients for circular color transitions.

/**
 * Create radial gradient
 * @param x1 - Inner circle center X
 * @param y1 - Inner circle center Y
 * @param r1 - Inner circle radius
 * @param x2 - Outer circle center X
 * @param y2 - Outer circle center Y
 * @param r2 - Outer circle radius
 * @returns Gradient object for use with colors
 */
radialGradient(x1: number, y1: number, r1: number, x2: number, y2: number, r2: number): Gradient;

Usage Examples:

// Concentric radial gradient
const radial1 = doc.radialGradient(150, 150, 0, 150, 150, 50)
  .stop(0, 'white')
  .stop(1, 'black');

doc.circle(150, 150, 50)
   .fill(radial1);

// Offset radial gradient (light source effect)
const radial2 = doc.radialGradient(170, 130, 0, 150, 150, 50)
  .stop(0, 'yellow')
  .stop(0.7, 'orange')
  .stop(1, 'red');

doc.circle(150, 250, 50)
   .fill(radial2);

Pattern Support

Create tiling patterns for complex fills.

/**
 * Create tiling pattern
 * @param bbox - Pattern bounding box [x, y, width, height]
 * @param xStep - Horizontal step between pattern tiles
 * @param yStep - Vertical step between pattern tiles
 * @param stream - Pattern content stream
 * @returns Pattern for use with colors
 */
pattern(bbox: [number, number, number, number], xStep: number, yStep: number, stream: string): Pattern;

type Pattern = [PatternObject, ColorValue];

Usage Examples:

// Simple dot pattern
const dotPattern = doc.pattern([0, 0, 10, 10], 10, 10, `
  2 0 0 2 0 0 cm
  0 0 5 5 re
  f
`);

doc.rect(100, 100, 100, 100)
   .fill([dotPattern, [0, 0, 0]]);  // Black dots

// Diagonal line pattern
const linePattern = doc.pattern([0, 0, 8, 8], 8, 8, `
  1 w
  0 0 m
  8 8 l
  S
`);

doc.rect(250, 100, 100, 100)
   .fill([linePattern, [100, 0, 0]]);  // Red diagonal lines

Spot Colors

Define and use spot colors for professional printing.

/**
 * Add spot color definition
 * @param name - Spot color name
 * @param C - Cyan component (0-100)
 * @param M - Magenta component (0-100)
 * @param Y - Yellow component (0-100)
 * @param K - Black component (0-100)
 * @returns Document instance for chaining
 */
addSpotColor(name: string, C: number, M: number, Y: number, K: number): PDFDocument;

Usage Examples:

// Define Pantone-like spot color
doc.addSpotColor('PMS186', 0, 100, 91, 0);  // Pantone 186 (red)

// Use spot color
doc.fillColor('PMS186')
   .rect(100, 100, 100, 50)
   .fill();

// Spot color with tint
doc.fillColor(['PMS186', 0.5])  // 50% tint
   .rect(100, 200, 100, 50)
   .fill();

Supported Color Formats

Named Colors

PDFKit supports 140+ CSS named colors including:

type NamedColor = 
  // Basic colors
  | 'black' | 'white' | 'red' | 'green' | 'blue' | 'yellow' | 'cyan' | 'magenta'
  // Extended colors
  | 'aliceblue' | 'antiquewhite' | 'aqua' | 'aquamarine' | 'azure' | 'beige'
  | 'bisque' | 'blanchedalmond' | 'blueviolet' | 'brown' | 'burlywood'
  // ... and many more
  ;

Hex Color Formats

// 6-digit hex
doc.fillColor('#FF0000');    // Red
doc.fillColor('#00FF00');    // Green
doc.fillColor('#0000FF');    // Blue

// 3-digit hex (expanded automatically)
doc.fillColor('#F00');       // Red (#FF0000)
doc.fillColor('#0F0');       // Green (#00FF00)
doc.fillColor('#00F');       // Blue (#0000FF)

RGB Color Arrays

// RGB values 0-255
doc.fillColor([255, 0, 0]);     // Red
doc.fillColor([0, 255, 0]);     // Green
doc.fillColor([0, 0, 255]);     // Blue
doc.fillColor([128, 128, 128]); // Gray

CMYK Color Arrays

// CMYK values 0-100
doc.fillColor([0, 100, 100, 0]);   // Red
doc.fillColor([100, 0, 100, 0]);   // Green  
doc.fillColor([100, 100, 0, 0]);   // Blue
doc.fillColor([0, 0, 0, 50]);      // 50% Gray