tessl/npm-gradient-string

Beautiful color gradients in terminal output

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Gradient String

Name: tessl/npm-gradient-string
Author: tessl

Gradient String provides beautiful color gradients in terminal output. It enables developers to create visually appealing CLI tools by applying smooth color transitions to text strings with built-in gradient presets, custom color combinations, and advanced interpolation options.

Package Information

Package Name: gradient-string
Package Type: npm
Language: TypeScript
Installation: npm install gradient-string

Core Imports

import gradient from "gradient-string";

For built-in gradients:

import { rainbow, pastel, morning, cristal } from "gradient-string";

For standalone multiline function:

import { multiline } from "gradient-string";

Mixed imports:

import gradient, { rainbow, pastel, multiline } from "gradient-string";

CommonJS:

const gradient = require("gradient-string");
const { rainbow, pastel, multiline } = require("gradient-string");

Basic Usage

import gradient, { rainbow, pastel } from "gradient-string";

// Create custom gradient
const coolGradient = gradient(['cyan', 'pink']);
console.log(coolGradient('Hello world!'));

// Use built-in gradients
console.log(rainbow('Amazing colors! 🌈'));
console.log(pastel('Soft and beautiful'));

// Multi-line gradients
const art = gradient(['green', 'yellow']).multiline(`
  ASCII
  ART
  HERE
`);
console.log(art);

Architecture

Gradient String is built around several key components and design patterns:

Gradient Factory Pattern: The main gradient() function creates configured gradient functions that can be reused across multiple strings
Color Interpolation Engine: Uses TinyGradient library for RGB and HSV color space interpolation with customizable hue spinning
Terminal Output Integration: Leverages Chalk library for ANSI color code generation and terminal compatibility
Dual Syntax Support: Maintains backward compatibility with deprecated varargs syntax while promoting new array-based syntax
Built-in Theme System: Pre-configured gradient aliases provide ready-to-use color themes without setup
Multi-line Processing: Vertical gradient alignment for ASCII art and formatted text output

Color Processing Pipeline:

Input colors parsed through TinyColor (supports hex, named, RGB, HSV, etc.)
Gradient stops calculated based on string length and color distribution
Color interpolation performed in RGB or HSV color space
Terminal colors generated via Chalk hex color conversion
Characters mapped to colors while preserving whitespace

Interpolation Modes:

RGB: Direct red-green-blue interpolation (default) - produces natural color transitions
HSV: Hue-saturation-value interpolation - creates more vibrant gradients with hue spinning control

Capabilities

Custom Gradient Creation

Create custom gradients with your own color combinations and interpolation settings.

/**
 * Creates a custom gradient function from colors and options (recommended syntax)
 * @param colors - Array of colors in any supported format
 * @param options - Optional gradient configuration
 * @returns Gradient function that can be applied to strings
 */
function gradient(colors: ColorInput[], options?: GradientOptions): GradientFunction;

/**
 * @deprecated - Legacy varargs syntax, use array syntax instead
 * Example migration: gradient('red', 'blue') → gradient(['red', 'blue'])
 */
function gradient(...colors: (ColorInput | StopInput | GradientOptions)[]): GradientFunction;

interface GradientFunction {
  /** Apply gradient to a string */
  (str: string): string;
  /** Apply gradient to multi-line string with vertical alignment */
  multiline: MultiLineGradientFunction;
}

interface MultiLineGradientFunction {
  /** Apply gradient to multi-line string */
  (str: string): string;
  /** @deprecated - Pass options when creating gradient instead */
  (str: string, opts?: GradientOptions): string;
}

interface GradientOptions {
  /** Color interpolation method - 'rgb' or 'hsv' (default: 'rgb') */
  interpolation?: 'rgb' | 'hsv';
  /** HSV hue spinning direction - 'short' or 'long' (default: 'short') */
  hsvSpin?: 'short' | 'long';
}

Usage Examples:

// Basic custom gradient
const fireGradient = gradient(['red', 'orange', 'yellow']);
console.log(fireGradient('This text is on fire!'));

// Gradient with custom color stops
const customGradient = gradient([
  { color: '#d8e0de', pos: 0 },
  { color: '#255B53', pos: 0.8 },
  { color: '#000000', pos: 1 }
]);

// HSV interpolation for brighter colors
const brightGradient = gradient(['red', 'green'], { interpolation: 'hsv' });

// Long HSV spin for rainbow effect
const rainbowGradient = gradient(['red', 'green'], { 
  interpolation: 'hsv', 
  hsvSpin: 'long' 
});

Migration from Deprecated Syntax:

// ❌ Deprecated varargs syntax (still works but not recommended)
const oldGradient = gradient('red', 'green', 'blue');
const oldGradientWithOptions = gradient('red', 'green', { interpolation: 'hsv' });

// ✅ Recommended array syntax  
const newGradient = gradient(['red', 'green', 'blue']);
const newGradientWithOptions = gradient(['red', 'green'], { interpolation: 'hsv' });

// ❌ Deprecated property access (still works but not recommended)
console.log(gradient.rainbow('text'));

// ✅ Recommended named imports
import { rainbow } from 'gradient-string';
console.log(rainbow('text'));

Built-in Gradient Presets

Pre-configured gradient themes ready to use without setup.

interface AliasGradientFunction {
  /** Apply gradient to a string */
  (str: string): string;
  /** Apply gradient to multi-line string */
  multiline: (str: string) => string;
}

/** Ocean-inspired gradient: #feac5e → #c779d0 → #4bc0c8 */
const atlas: AliasGradientFunction;

/** Crystal clear gradient: #bdfff3 → #4ac29a */
const cristal: AliasGradientFunction;

/** Teen spirit gradient: #77a1d3 → #79cbca → #e684ae */
const teen: AliasGradientFunction;

/** Mindful gradient: #473b7b → #3584a7 → #30d2be */
const mind: AliasGradientFunction;

/** Morning sunrise gradient: #ff5f6d → #ffc371 (HSV interpolation) */
const morning: AliasGradientFunction;

/** Vice-like gradient: #5ee7df → #b490ca (HSV interpolation) */
const vice: AliasGradientFunction;

/** Passionate gradient: #f43b47 → #453a94 */
const passion: AliasGradientFunction;

/** Fruity gradient: #ff4e50 → #f9d423 */
const fruit: AliasGradientFunction;

/** Instagram-inspired gradient: #833ab4 → #fd1d1d → #fcb045 */
const instagram: AliasGradientFunction;

/** Retro 9-color gradient: #3f51b1 → ... → #f7c978 */
const retro: AliasGradientFunction;

/** Summer vibes gradient: #fdbb2d → #22c1c3 */
const summer: AliasGradientFunction;

/** Full spectrum rainbow: #ff0000 → #ff0100 (HSV long spin) */
const rainbow: AliasGradientFunction;

/** Soft pastel gradient: #74ebd5 → #74ecd5 (HSV long spin) */
const pastel: AliasGradientFunction;

Usage Examples:

import { rainbow, pastel, morning, cristal } from "gradient-string";

// Use different built-in gradients
console.log(rainbow('Rainbow colors! 🌈'));
console.log(pastel('Soft pastels'));
console.log(morning('Sunrise vibes'));
console.log(cristal('Crystal clear'));

// Multi-line with built-ins
console.log(rainbow.multiline('Multi\nLine\nRainbow'));

Standalone Multi-line Function

Apply gradients to multi-line strings using the standalone multiline function with gradient objects.

/**
 * Apply gradient to multi-line text with vertical alignment
 * @param str - Multi-line string to apply gradient to
 * @param gradient - TinyGradient instance for color interpolation
 * @param opts - Optional gradient configuration
 * @returns String with gradient applied to each line
 */
function multiline(str: string, gradient: TinyGradient, opts?: GradientOptions): string;

Usage Examples:

import { multiline } from "gradient-string";
import tinygradient from "tinygradient";

// Create gradient manually and apply with multiline
const customGradient = tinygradient(['#ff0000', '#00ff00', '#0000ff']);
const result = multiline('Line 1\nLine 2\nLine 3', customGradient, { 
  interpolation: 'hsv' 
});
console.log(result);

// Advanced color stops
const stoppedGradient = tinygradient([
  { color: '#d8e0de', pos: 0 },
  { color: '#255B53', pos: 0.8 },
  { color: '#000000', pos: 1 }
]);
const art = multiline(`
╔══════════════════════╗
║   MULTI-LINE ART     ║
╚══════════════════════╝
`, stoppedGradient);

Multi-line Gradient Support

Apply gradients to multi-line text with vertically aligned colors, perfect for ASCII art and formatted output.

Usage Examples:

// Multi-line ASCII art
const duck = gradient(['green', 'yellow']).multiline(`
  __
<(o )___
 ( ._> /
   ---
`);
console.log(duck);

// Multi-line text with built-in gradients
const header = pastel.multiline(`
╔══════════════════════╗
║   WELCOME TO APP     ║
╚══════════════════════╝
`);
console.log(header);

// Custom gradient with advanced options
const advancedMultiline = gradient(['cyan', 'pink'], { 
  interpolation: 'hsv' 
}).multiline('Line 1\nLine 2\nLine 3');

Color Input Formats

Supports multiple color input formats through integration with TinyColor and TinyGradient libraries.

/**
 * Color formats accepted by the gradient function
 * Uses TinyColor and TinyGradient libraries for color parsing
 */
type ColorInput = string | object; // From tinycolor2 library

type StopInput = {
  color: ColorInput;
  pos: number; // Position between 0 and 1
};

Supported Color Formats:

// Hex strings
gradient(['#FF0000', '#00FF00', '#0000FF'])

// Named colors
gradient(['red', 'green', 'blue'])

// RGB CSS strings
gradient(['rgb(255, 0, 0)', 'rgb(0, 255, 0)'])

// RGB objects
gradient([
  { r: 255, g: 0, b: 0 },
  { r: 0, g: 255, b: 0 }
])

// HSV objects
gradient([
  { h: 0, s: 1, v: 1 },
  { h: 120, s: 1, v: 1 }
])

// Custom color stops
gradient([
  { color: '#d8e0de', pos: 0 },
  { color: '#255B53', pos: 0.8 },
  { color: '#000000', pos: 1 }
])

Error Handling

The package validates inputs and provides clear error messages for common mistakes.

Common Errors:

Missing gradient colors - When no colors are provided to gradient()
Expected an array of colors, received ... - When using deprecated syntax incorrectly
Invalid number of stops (< 2) - When fewer than 2 colors are provided (from tinygradient)
Expected \options` to be an `object`, got `...`` - When options parameter is not an object
Expected \options.interpolation` to be `rgb` or `hsv`, got `...`` - When interpolation value is invalid
Expected \options.hsvSpin` to be a `short` or `long`, got `...`` - When hsvSpin value is invalid

Types

// Main gradient creator interface (matches default export)
interface GradientCreator {
  /** Create gradient with array syntax (recommended) */
  (colors: ColorInput[], options?: GradientOptions): GradientFunction;
  /** @deprecated - Use array syntax: gradient(['red', 'blue'], options) */
  (...colors: (ColorInput | StopInput | GradientOptions)[]): GradientFunction;
  
  // Legacy property access (deprecated)
  /** @deprecated - Use import { atlas } from 'gradient-string' instead */
  atlas: AliasGradientFunction;
  /** @deprecated - Use import { cristal } from 'gradient-string' instead */
  cristal: AliasGradientFunction;
  /** @deprecated - Use import { teen } from 'gradient-string' instead */
  teen: AliasGradientFunction;
  /** @deprecated - Use import { mind } from 'gradient-string' instead */
  mind: AliasGradientFunction;
  /** @deprecated - Use import { morning } from 'gradient-string' instead */
  morning: AliasGradientFunction;
  /** @deprecated - Use import { vice } from 'gradient-string' instead */
  vice: AliasGradientFunction;
  /** @deprecated - Use import { passion } from 'gradient-string' instead */
  passion: AliasGradientFunction;
  /** @deprecated - Use import { fruit } from 'gradient-string' instead */
  fruit: AliasGradientFunction;
  /** @deprecated - Use import { instagram } from 'gradient-string' instead */
  instagram: AliasGradientFunction;
  /** @deprecated - Use import { retro } from 'gradient-string' instead */
  retro: AliasGradientFunction;
  /** @deprecated - Use import { summer } from 'gradient-string' instead */
  summer: AliasGradientFunction;
  /** @deprecated - Use import { rainbow } from 'gradient-string' instead */
  rainbow: AliasGradientFunction;
  /** @deprecated - Use import { pastel } from 'gradient-string' instead */
  pastel: AliasGradientFunction;
}

interface GradientOptions {
  /** Color interpolation method - 'rgb' for natural transitions, 'hsv' for vibrant colors */
  interpolation?: 'rgb' | 'hsv';
  /** HSV hue spinning direction - 'short' for direct path, 'long' for rainbow effect */
  hsvSpin?: 'short' | 'long';
}

interface GradientFunction {
  /** Apply gradient to a string */
  (str: string): string;
  /** Multi-line gradient method */
  multiline: MultiLineGradientFunction;
  /** @deprecated - Pass options when creating gradient instead */
  (str: string, opts?: GradientOptions): string;
}

interface MultiLineGradientFunction {
  /** Apply gradient to multi-line string */
  (str: string): string;
  /** @deprecated - Pass options when creating gradient instead */
  (str: string, opts?: GradientOptions): string;
}

interface AliasGradientFunction {
  /** Apply gradient to a string */
  (str: string): string;
  /** Apply gradient to multi-line string */
  multiline: (str: string) => string;
}

// Color input types (from tinycolor2 and tinygradient libraries)
type ColorInput = 
  | string                    // Hex: '#ff0000', Named: 'red', CSS: 'rgb(255,0,0)'
  | { r: number; g: number; b: number; a?: number }  // RGB object
  | { h: number; s: number; v: number; a?: number }  // HSV object  
  | { h: number; s: number; l: number; a?: number }  // HSL object

interface StopInput {
  /** Color at this gradient stop */
  color: ColorInput;
  /** Position between 0 and 1 */
  pos: number;
}

// TinyGradient instance (for standalone multiline function)
interface TinyGradient {
  /** Generate RGB color array */
  rgb(count: number): TinyColor[];
  /** Generate HSV color array with optional arc mode */
  hsv(count: number, arcMode?: 'short' | 'long' | false): TinyColor[];
  /** Color stops in the gradient */
  stops: any[];
}

// TinyColor instance (color manipulation)
interface TinyColor {
  /** Convert to hex string */
  toHex(): string;
}

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:npm/gradient-string@3.0.x
Publish Source: CLI
Badge