CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-cli-progress

Terminal progress bar library with single/multi bar support

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

presets-formatting.mddocs/

Presets and Formatting

Built-in themes and advanced formatting system for creating custom progress bar appearances. CLI Progress provides comprehensive formatting options including preset themes, custom format strings, and specialized formatting functions.

Capabilities

Presets Collection

Built-in preset configurations providing common visual themes and styling patterns.

interface Presets {
  legacy: PresetConfiguration;
  shades_classic: PresetConfiguration;
  shades_grey: PresetConfiguration;
  rect: PresetConfiguration;
}

interface PresetConfiguration {
  format?: string;
  barCompleteChar?: string;
  barIncompleteChar?: string;
  [key: string]: any;
}

Available Presets:

const cliProgress = require('cli-progress');

// Legacy style (ASCII characters)
cliProgress.Presets.legacy
// { format: 'progress [{bar}] {percentage}% | ETA: {eta}s | {value}/{total}', barCompleteChar: '=', barIncompleteChar: '-' }

// Classic shades (Unicode block characters)
cliProgress.Presets.shades_classic
// { format: ' {bar} {percentage}% | ETA: {eta}s | {value}/{total}', barCompleteChar: '\u2588', barIncompleteChar: '\u2591' }

// Grey shades variant (with ANSI color codes)
cliProgress.Presets.shades_grey
// { format: ' \u001b[90m{bar}\u001b[0m {percentage}% | ETA: {eta}s | {value}/{total}', barCompleteChar: '\u2588', barIncompleteChar: '\u2591' }

// Rectangle style
cliProgress.Presets.rect
// { format: ' {bar}\u25A0 {percentage}% | ETA: {eta}s | {value}/{total}', barCompleteChar: '\u25A0', barIncompleteChar: ' ' }

Usage Examples:

// Use preset directly
const bar1 = new cliProgress.SingleBar({}, cliProgress.Presets.shades_classic);

// Combine preset with custom options
const bar2 = new cliProgress.SingleBar({
  hideCursor: true,
  clearOnComplete: true
}, cliProgress.Presets.legacy);

// Override preset properties
const bar3 = new cliProgress.SingleBar({
  format: 'Custom |{bar}| {percentage}%'
}, cliProgress.Presets.shades_classic);

Format Object

Collection of formatting utilities for advanced customization and rendering control.

interface Format {
  Formatter: (options: ProgressBarOptions, params: FormatParams, payload: object) => string;
  BarFormat: (progress: number, options: ProgressBarOptions) => string;
  ValueFormat: (value: any, options: ProgressBarOptions, type: string) => any;
  TimeFormat: (seconds: number, options: ProgressBarOptions, roundTo?: number) => string;
}

Default Formatter Function

Main formatting function that processes format strings with token replacement and alignment.

/**
 * Default progress bar formatter with token replacement
 * @param options - Progress bar configuration options
 * @param params - Current progress parameters and metrics
 * @param payload - Custom payload data for token replacement
 * @returns Formatted progress bar string
 */
Format.Formatter(
  options: ProgressBarOptions,
  params: FormatParams,
  payload: object
): string;

interface FormatParams {
  progress: number;    // Normalized progress (0.0 - 1.0)
  eta: number;        // Estimated time remaining in seconds
  startTime: number;  // Start timestamp
  stopTime?: number;  // Stop timestamp (if stopped)
  total: number;      // Total/maximum value
  value: number;      // Current progress value
  maxWidth: number;   // Available terminal width
}

Usage Examples:

// Custom formatter function
const bar = new cliProgress.SingleBar({
  format: function(options, params, payload) {
    // Custom logic for formatting
    const percent = Math.floor(params.progress * 100);
    return `Progress: ${percent}% [${payload.filename}]`;
  }
});

// Using built-in formatter directly
const formatted = cliProgress.Format.Formatter(
  { format: '{bar} {percentage}%' },
  { progress: 0.5, value: 50, total: 100, /* ... */ },
  { filename: 'data.csv' }
);

Bar Rendering Formatter

Renders the visual progress bar component with complete/incomplete characters.

/**
 * Renders the visual progress bar component
 * @param progress - Normalized progress value (0.0 - 1.0)
 * @param options - Configuration options containing bar characters and size
 * @returns Rendered progress bar string
 */
Format.BarFormat(progress: number, options: ProgressBarOptions): string;

Usage Examples:

// Custom bar formatter
const bar = new cliProgress.SingleBar({
  formatBar: function(progress, options) {
    const barSize = options.barsize || 40;
    const completeSize = Math.round(progress * barSize);
    const incompleteSize = barSize - completeSize;
    
    return '█'.repeat(completeSize) + '░'.repeat(incompleteSize);
  }
});

// Using built-in bar formatter
const barString = cliProgress.Format.BarFormat(0.75, {
  barsize: 20,
  barCompleteChar: '=',
  barIncompleteChar: '-'
});
// Result: "===============-----"

Value Formatting Utility

Formats numeric values with optional auto-padding for consistent width.

/**
 * Formats values with optional auto-padding
 * @param value - Value to format
 * @param options - Configuration options including padding settings
 * @param type - Value type for specific formatting ('percentage', etc.)
 * @returns Formatted value
 */
Format.ValueFormat(value: any, options: ProgressBarOptions, type: string): any;

Usage Examples:

// Auto-padding for consistent width
const bar = new cliProgress.SingleBar({
  autopadding: true,
  autopaddingChar: '   ', // 3 identical characters required
  formatValue: function(value, options, type) {
    if (type === 'percentage') {
      return (options.autopaddingChar + value).slice(-3); // Right-align to 3 chars
    }
    return value;
  }
});

// Using built-in value formatter
const formatted = cliProgress.Format.ValueFormat('85', {
  autopadding: true,
  autopaddingChar: '   '
}, 'percentage');
// Result: " 85" (right-aligned to 3 characters)

Time Formatting Utility

Formats time duration into human-readable strings with appropriate units.

/**
 * Formats time duration into human-readable format
 * @param seconds - Time duration in seconds
 * @param options - Configuration options including padding
 * @param roundTo - Multiple to round to (optional)
 * @returns Formatted time string (e.g., "1h23m", "45s")
 */
Format.TimeFormat(seconds: number, options: ProgressBarOptions, roundTo?: number): string;

Usage Examples:

// Custom time formatter
const bar = new cliProgress.SingleBar({
  formatTime: function(seconds, options, roundTo) {
    if (seconds > 3600) {
      const hours = Math.floor(seconds / 3600);
      const minutes = Math.floor((seconds % 3600) / 60);
      return `${hours}h${minutes}m`;
    } else if (seconds > 60) {
      const minutes = Math.floor(seconds / 60);
      const secs = Math.floor(seconds % 60);
      return `${minutes}m${secs}s`;
    }
    return `${Math.floor(seconds)}s`;
  }
});

// Using built-in time formatter
const timeString = cliProgress.Format.TimeFormat(3725, {}, 5);
// Result: "1h02m" (rounded to multiple of 5 seconds)

Format String Tokens

Built-in placeholder tokens available in format strings for dynamic content replacement.

interface FormatTokens {
  '{bar}': string;              // Visual progress bar
  '{percentage}': string;       // Progress percentage (0-100)
  '{total}': string;           // Total/maximum value
  '{value}': string;           // Current progress value
  '{eta}': string;             // ETA in seconds
  '{duration}': string;        // Elapsed time in seconds
  '{eta_formatted}': string;   // ETA in human-readable format
  '{duration_formatted}': string; // Duration in human-readable format
  '[payload_key]': string;     // Custom payload values by key
}

Usage Examples:

// Format string with all built-in tokens
const bar = new cliProgress.SingleBar({
  format: 'Progress |{bar}| {percentage}% | {value}/{total} | ETA: {eta_formatted} | Elapsed: {duration_formatted}'
});

// Format string with custom payload tokens
const bar2 = new cliProgress.SingleBar({
  format: '{filename} |{bar}| {percentage}% | Speed: {speed} | Status: {status}'
});

bar2.start(100, 0, {
  filename: 'data.csv',
  speed: 'N/A',
  status: 'starting'
});

Advanced Formatting Patterns

Conditional Formatting

const bar = new cliProgress.SingleBar({
  format: function(options, params, payload) {
    const percent = Math.floor(params.progress * 100);
    let status = '';
    
    if (percent < 25) {
      status = '🔴 Starting';
    } else if (percent < 50) {
      status = '🟡 Processing';
    } else if (percent < 100) {
      status = '🟢 Nearly Done';
    } else {
      status = '✅ Complete';
    }
    
    return `${status} |${cliProgress.Format.BarFormat(params.progress, options)}| ${percent}%`;
  }
});

Color and Styling Integration

// Note: Requires external color library like 'ansi-colors'
const colors = require('ansi-colors');

const bar = new cliProgress.SingleBar({
  format: `${colors.cyan('Progress')} |{bar}| ${colors.yellow('{percentage}%')} | {value}/{total}`,
  barCompleteChar: colors.green('█'),
  barIncompleteChar: colors.gray('░'),
  
  // Custom bar formatter with colors
  formatBar: function(progress, options) {
    const barSize = options.barsize || 40;
    const completeSize = Math.round(progress * barSize);
    const incompleteSize = barSize - completeSize;
    
    return colors.green('█').repeat(completeSize) + 
           colors.gray('░').repeat(incompleteSize);
  }
});

Multi-line Progress Display

const bar = new cliProgress.SingleBar({
  format: function(options, params, payload) {
    const barString = cliProgress.Format.BarFormat(params.progress, options);
    const percent = Math.floor(params.progress * 100);
    const eta = cliProgress.Format.TimeFormat(params.eta, options);
    
    return [
      `File: ${payload.filename}`,
      `Progress: |${barString}| ${percent}%`,
      `Speed: ${payload.speed} | ETA: ${eta}`
    ].join('\n');
  },
  
  // Adjust for multi-line output
  clearOnComplete: true
});

Dynamic Width Adaptation

const bar = new cliProgress.SingleBar({
  format: function(options, params, payload) {
    // Adapt bar size to terminal width
    const fixedContent = `Progress  100% | 999/999 | ETA: 99m99s`;
    const availableWidth = params.maxWidth - fixedContent.length - 4; // margin
    const dynamicBarSize = Math.max(10, Math.min(50, availableWidth));
    
    // Override bar size for this render
    const barOptions = { ...options, barsize: dynamicBarSize };
    const barString = cliProgress.Format.BarFormat(params.progress, barOptions);
    
    const percent = Math.floor(params.progress * 100);
    const eta = cliProgress.Format.TimeFormat(params.eta, options);
    
    return `Progress |${barString}| ${percent}% | ${params.value}/${params.total} | ETA: ${eta}`;
  }
});

Install with Tessl CLI

npx tessl i tessl/npm-cli-progress

docs

index.md

multi-bar.md

presets-formatting.md

single-bar.md

tile.json