or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-picocolors

The tiniest and the fastest library for terminal output formatting with ANSI colors

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/picocolors@1.1.x

To install, run

npx @tessl/cli install tessl/npm-picocolors@1.1.0

index.mddocs/

Picocolors

Picocolors is a high-performance, zero-dependency library for terminal output formatting with ANSI colors. It provides the smallest and fastest solution for adding colors and text formatting to command-line interfaces, being 14 times smaller and 2 times faster than chalk.

Package Information

  • Package Name: picocolors
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install picocolors

Core Imports

import pc from "picocolors";

For CommonJS:

const pc = require("picocolors");

For TypeScript with named imports:

import { Colors } from "picocolors";

Basic Usage

import pc from "picocolors";

// Basic colors
console.log(pc.red("Error message"));
console.log(pc.green("Success message"));
console.log(pc.blue("Info message"));

// Text formatting
console.log(pc.bold("Important text"));
console.log(pc.italic("Emphasized text"));
console.log(pc.underline("Underlined text"));

// Nested formatting
console.log(pc.red(`Error: ${pc.bold("Something went wrong")}`));

// Background colors
console.log(pc.bgYellow(pc.black("Warning message")));

// Checking color support
if (pc.isColorSupported) {
  console.log(pc.green("Colors are supported!"));
}

Architecture

Picocolors uses a formatter-based architecture that:

  • Auto-detects color support based on environment variables, CLI flags, and terminal capabilities
  • Handles nested formatting by properly managing ANSI escape sequences
  • Optimizes performance through minimal overhead and efficient string operations
  • Provides browser compatibility with a separate browser bundle that disables colors
  • Supports manual configuration via the createColors factory function

The library automatically detects color support by checking:

  • NO_COLOR and FORCE_COLOR environment variables
  • --no-color and --color command-line flags
  • Platform detection (Windows support)
  • TTY detection and TERM environment variable
  • CI environment detection

Capabilities

Color Support Detection

Check if colors are supported in the current environment.

// Property indicating color support
const isColorSupported: boolean;

Color Factory

Create a custom colors object with manual color support configuration.

/**
 * Create a Colors object with custom color support configuration
 * @param enabled - Whether to enable colors (defaults to auto-detection)
 * @returns Colors object with all formatting functions
 */
function createColors(enabled?: boolean): Colors;

Usage Example:

import pc from "picocolors";

// Create colors with manual configuration
const colors = pc.createColors(true);  // Force enable
const noColors = pc.createColors(false); // Force disable

console.log(colors.red("This will be red"));
console.log(noColors.red("This will be plain text"));

Text Formatting

Apply text styling and formatting effects.

// Reset all formatting
const reset: (input: string | number | null | undefined) => string;

// Text styling
const bold: (input: string | number | null | undefined) => string;
const dim: (input: string | number | null | undefined) => string;
const italic: (input: string | number | null | undefined) => string;
const underline: (input: string | number | null | undefined) => string;
const inverse: (input: string | number | null | undefined) => string;
const hidden: (input: string | number | null | undefined) => string;
const strikethrough: (input: string | number | null | undefined) => string;

Usage Examples:

console.log(pc.bold("Bold text"));
console.log(pc.italic("Italic text"));
console.log(pc.underline("Underlined text"));
console.log(pc.strikethrough("Strikethrough text"));
console.log(pc.dim("Dimmed text"));
console.log(pc.inverse("Inverted colors"));
console.log(pc.hidden("Hidden text"));
console.log(pc.reset("Reset formatting"));

Standard Colors

Apply standard foreground colors to text.

// Standard foreground colors
const black: (input: string | number | null | undefined) => string;
const red: (input: string | number | null | undefined) => string;
const green: (input: string | number | null | undefined) => string;
const yellow: (input: string | number | null | undefined) => string;
const blue: (input: string | number | null | undefined) => string;
const magenta: (input: string | number | null | undefined) => string;
const cyan: (input: string | number | null | undefined) => string;
const white: (input: string | number | null | undefined) => string;
const gray: (input: string | number | null | undefined) => string;

Usage Examples:

console.log(pc.black("Black text"));
console.log(pc.red("Red text"));
console.log(pc.green("Green text"));
console.log(pc.yellow("Yellow text"));
console.log(pc.blue("Blue text"));
console.log(pc.magenta("Magenta text"));
console.log(pc.cyan("Cyan text"));
console.log(pc.white("White text"));
console.log(pc.gray("Gray text"));

Background Colors

Apply background colors to text.

// Standard background colors
const bgBlack: (input: string | number | null | undefined) => string;
const bgRed: (input: string | number | null | undefined) => string;
const bgGreen: (input: string | number | null | undefined) => string;
const bgYellow: (input: string | number | null | undefined) => string;
const bgBlue: (input: string | number | null | undefined) => string;
const bgMagenta: (input: string | number | null | undefined) => string;
const bgCyan: (input: string | number | null | undefined) => string;
const bgWhite: (input: string | number | null | undefined) => string;

Usage Examples:

console.log(pc.bgBlack("Text with black background"));
console.log(pc.bgRed("Text with red background"));
console.log(pc.bgGreen("Text with green background"));
console.log(pc.bgYellow("Text with yellow background"));
console.log(pc.bgBlue("Text with blue background"));
console.log(pc.bgMagenta("Text with magenta background"));
console.log(pc.bgCyan("Text with cyan background"));
console.log(pc.bgWhite("Text with white background"));

Bright Colors

Apply bright/high-intensity foreground colors to text.

// Bright foreground colors
const blackBright: (input: string | number | null | undefined) => string;
const redBright: (input: string | number | null | undefined) => string;
const greenBright: (input: string | number | null | undefined) => string;
const yellowBright: (input: string | number | null | undefined) => string;
const blueBright: (input: string | number | null | undefined) => string;
const magentaBright: (input: string | number | null | undefined) => string;
const cyanBright: (input: string | number | null | undefined) => string;
const whiteBright: (input: string | number | null | undefined) => string;

Usage Examples:

console.log(pc.blackBright("Bright black text"));
console.log(pc.redBright("Bright red text"));
console.log(pc.greenBright("Bright green text"));
console.log(pc.yellowBright("Bright yellow text"));
console.log(pc.blueBright("Bright blue text"));
console.log(pc.magentaBright("Bright magenta text"));
console.log(pc.cyanBright("Bright cyan text"));
console.log(pc.whiteBright("Bright white text"));

Bright Background Colors

Apply bright/high-intensity background colors to text.

// Bright background colors
const bgBlackBright: (input: string | number | null | undefined) => string;
const bgRedBright: (input: string | number | null | undefined) => string;
const bgGreenBright: (input: string | number | null | undefined) => string;
const bgYellowBright: (input: string | number | null | undefined) => string;
const bgBlueBright: (input: string | number | null | undefined) => string;
const bgMagentaBright: (input: string | number | null | undefined) => string;
const bgCyanBright: (input: string | number | null | undefined) => string;
const bgWhiteBright: (input: string | number | null | undefined) => string;

Usage Examples:

console.log(pc.bgBlackBright("Text with bright black background"));
console.log(pc.bgRedBright("Text with bright red background"));
console.log(pc.bgGreenBright("Text with bright green background"));
console.log(pc.bgYellowBright("Text with bright yellow background"));
console.log(pc.bgBlueBright("Text with bright blue background"));
console.log(pc.bgMagentaBright("Text with bright magenta background"));
console.log(pc.bgCyanBright("Text with bright cyan background"));
console.log(pc.bgWhiteBright("Text with bright white background"));

Types

// Function signature for all color and formatting functions
type Formatter = (input: string | number | null | undefined) => string;

// Main Colors interface containing all formatting functions
interface Colors {
  // Color support detection
  isColorSupported: boolean;

  // Text formatting
  reset: Formatter;
  bold: Formatter;
  dim: Formatter;
  italic: Formatter;
  underline: Formatter;
  inverse: Formatter;
  hidden: Formatter;
  strikethrough: Formatter;

  // Standard colors
  black: Formatter;
  red: Formatter;
  green: Formatter;
  yellow: Formatter;
  blue: Formatter;
  magenta: Formatter;
  cyan: Formatter;
  white: Formatter;
  gray: Formatter;

  // Background colors
  bgBlack: Formatter;
  bgRed: Formatter;
  bgGreen: Formatter;
  bgYellow: Formatter;
  bgBlue: Formatter;
  bgMagenta: Formatter;
  bgCyan: Formatter;
  bgWhite: Formatter;

  // Bright colors
  blackBright: Formatter;
  redBright: Formatter;
  greenBright: Formatter;
  yellowBright: Formatter;
  blueBright: Formatter;
  magentaBright: Formatter;
  cyanBright: Formatter;
  whiteBright: Formatter;

  // Bright background colors
  bgBlackBright: Formatter;
  bgRedBright: Formatter;
  bgGreenBright: Formatter;
  bgYellowBright: Formatter;
  bgBlueBright: Formatter;
  bgMagentaBright: Formatter;
  bgCyanBright: Formatter;
  bgWhiteBright: Formatter;
}

Advanced Usage

Nested Formatting

Picocolors properly handles nested color and formatting combinations:

// Complex nested formatting
console.log(
  pc.bold(
    pc.yellow(
      pc.bgRed(
        pc.italic("Complex nested formatting")
      )
    )
  )
);

// Inline color changes within text
console.log(
  pc.green(`Success: ${pc.bold("Operation completed")} successfully`)
);

Input Type Handling

All formatter functions accept and handle various input types:

console.log(pc.red(null));      // "null"
console.log(pc.red(undefined)); // "undefined"
console.log(pc.red(123));       // "123"
console.log(pc.red(true));      // "true"
console.log(pc.red(NaN));       // "NaN"

Environment Configuration

Control color behavior through environment variables and CLI flags:

# Disable colors
NO_COLOR=1 node script.js
node script.js --no-color

# Force enable colors
FORCE_COLOR=1 node script.js
node script.js --color

Browser Usage

For browser environments, use the browser-specific bundle:

// Browser bundle automatically disables colors
import pc from "picocolors/picocolors.browser.js";

// All functions return plain strings in browser
console.log(pc.red("This will be plain text in browser"));