termload

Animated terminal progress bars and spinners for Node.js CLI applications.

Install

npm install termload

Bar

import { Bar } from 'termload'

const bar = new Bar()
bar.start()
bar.message('Starting...')

setTimeout(() => bar.stop('Done!'), 3000)

const { Bar } = require('termload')

Options

const bar = new Bar({
  length: 80,           // bar width (default: terminal width)
  front: '[',           // leading clamp (default: '[')
  back: ']',            // trailing clamp (default: ']')
  character: '-',       // moving character (default: '-')
  before: ' ',          // fill before position (default: ' ')
  after: ' ',           // fill after position (default: ' ')
  interval: 35,         // ms per frame (default: 35)
  mode: 'bounce',       // 'bounce' | 'loop' | 'loop-reverse' (default: 'bounce')
  progress: 0,          // 0–1 enables determinate mode
  colors: [],           // hex gradient array, e.g. Bar.COLORS.rainbow
  bgColors: [],         // background gradient
  colorFill: false,     // apply dimmed gradient to fill chars
  colorCycle: 0,        // gradient shift speed in cycles/second
  shimmer: 0,           // brightness wave amplitude 0–1
  onBounce: () => {},   // fires on direction reversal
  onLoop: () => {},     // fires on position wrap
  onComplete: () => {}, // fires once when progress reaches 1
})

Setters

All properties can be changed while the bar is running.

bar.front = 'Loading: ['
bar.back = '] 42%'
bar.character = '='
bar.before = '-'
bar.after = '-'
bar.empty = '·'           // sets both before and after
bar.mode = 'loop'
bar.progress = 0.5        // switch to determinate
bar.progress = undefined  // back to animation
bar.colors = Bar.COLORS.rainbow
bar.colorCycle = 0.5
bar.shimmer = 0.7

Color gradients

Pass an array of hex colors. The gradient is interpolated across the bar by position.

bar.colors = ['#0000ff', '#ff0000']       // blue → red
bar.colors = Bar.COLORS.rainbow    // preset

Built-in presets: blueRed, redBlue, rainbow, heat, cool, sunset.

API

Method	Description
bar.start()	Begin animation, hide cursor
bar.stop(msg?)	Stop animation, restore cursor, optionally print message
bar.message(string)	Print a line without stopping the bar

---

Spinner

import { Spinner } from 'termload'

const spinner = new Spinner({
  frames: Spinner.FRAMES.braille,
  colors: Bar.COLORS.rainbow,
  colorCycle: 1.0,
  front: 'Loading ',
})
spinner.start()

setTimeout(() => spinner.stop('Done!'), 3000)

Options

const spinner = new Spinner({
  frames: Spinner.FRAMES.braille, // frame array
  front: '',            // prefix string
  back: '',             // suffix string
  interval: 80,         // ms per frame (default: 80)
  colors: [],           // hex gradient
  bgColors: [],         // background gradient
  colorCycle: 0,        // gradient shift speed
  shimmer: 0,           // brightness wave amplitude
  onSpin: () => {},     // fires after each full frame cycle
})

Built-in frame sets: braille, dots, line, arrow, bounce.

---

License

MIT © Jay Deaton