Install

npm install termfont

Or run directly with npx:

npx termfont "Hello" --color=cyan

Examples

Solid colors

npx termfont "Hello" --font=sans --color=white

npx termfont "ARCADE" --font=block --color=lime

npx termfont "Quiz.ai" --font=block --color=gold

npx termfont "hack" --font=block --color=lime

Gradients

npx termfont "sunset" --font=bold --gradient=orange,pink,purple

npx termfont "NEON" --font=block --gradient=purple,cyan,lime

npx termfont "fire" --font=block --gradient=red,yellow

npx termfont "ice" --font=block --gradient=white,cyan,blue

Rainbow

npx termfont "rainbow" --font=bold --rainbow

Per-word colors

npx termfont "open|code" --font=block --color=cyan,gray

Use | as a zero-width color separator (no space between words). Use commas to assign colors to words.

Effects

npx termfont "RETRO" --font=block --color=coral --shadow

npx termfont "outline" --font=bold --color=cyan --outline

Fonts

npx termfont "Hello" --font=sans

npx termfont "GOLD" --font=serif --color=gold

npx termfont "slim" --font=slim --color=pink

npx termfont "NARROW" --font=narrow --color=violet

npx termfont "ARCADE" --font=block --color=lime

| Font | Style | Width | |------|-------|-------| | sans | Clean default | 5px | | serif | Decorative serifs | 5px | | slim | Thin strokes | 5px | | bold | Heavy weight | 6px | | narrow | Condensed | 3px | | block | Chunky geometric | 7px |

Sizes

Terminal output supports three sizes:

# Small - compact half-block rendering
npx termfont "Hello" --size=sm

# Medium (default) - full block characters
npx termfont "Hello" --size=md

# Large - double-width, double-height blocks
npx termfont "Hello" --size=lg

SVG output

SVGs render as flat pixel art on a transparent background, ready to use on websites. Same-color pixels are merged into single <path> elements for minimal file size.

# Save to file
npx termfont "Logo" --svg --color=cyan --out=logo.svg

# Custom pixel size
npx termfont "Big" --svg --font=block --color=gold --size-px=24 --out=big.svg

# Gradient SVG
npx termfont "Neon" --svg --font=block --gradient=purple,cyan --out=neon.svg

CLI

termfont <text> [options]

Options:
  --color=<color>       Text color (name or hex, default: white)
                        Use commas for per-word colors (e.g. cyan,gray)
  --gradient=<a,b>      Gradient from color A to B (e.g. red,yellow)
                        Supports 3-stop: --gradient=red,yellow,green
  --rainbow             Rainbow color mode
  --font=<name>         Font: sans (default), serif, slim, bold, narrow, block
  --size=<size>         Size: sm, md (default), lg
  --compact             Half-block mode (sm is always compact)
  --shadow              Add drop shadow
  --shadow-color=<c>    Shadow color (default: gray)
  --outline             Add outline around text
  --border              Add pixel-art border frame
  --padding=<n>         Padding around text (default: 1)
  --svg                 Output SVG instead of terminal
  --size-px=<n>         SVG pixel size (default: 16)
  --out=<file>          Write output to file
  -h, --help            Show this help

API

import {
  composeText,
  renderTerminal,
  renderSVG,
  applyPadding,
  applyShadow,
  computeOutline,
  parseColor,
} from "termfont";

Terminal output

import { composeText, renderTerminal, applyPadding } from "termfont";

const grid = composeText("Hello", { font: "block" });
const padded = applyPadding(grid, 1);

const lines = renderTerminal(padded, {
  colorMode: { type: "solid", color: [0, 220, 220] },
});
console.log(lines.join("\n"));

SVG output

import { composeText, renderSVG } from "termfont";

const grid = composeText("Hello", { font: "block" });
const svg = renderSVG(grid, {
  colorMode: { type: "rainbow" },
  pixelSize: 16,
});
// svg is a string ready to write to a file or embed in HTML

Gradients

import { composeText, renderTerminal, applyPadding } from "termfont";

const grid = composeText("Fire", { font: "block" });
const padded = applyPadding(grid, 1);

const lines = renderTerminal(padded, {
  colorMode: {
    type: "gradient",
    from: [255, 0, 0],
    to: [255, 255, 0],
    direction: "horizontal",
  },
});
console.log(lines.join("\n"));

3-stop gradient

const lines = renderTerminal(padded, {
  colorMode: {
    type: "gradient",
    from: [128, 0, 255],
    via: [0, 220, 220],
    to: [50, 255, 50],
    direction: "horizontal",
  },
});

Shadow

import { composeText, renderTerminal, applyPadding, applyShadow } from "termfont";

let grid = composeText("Shadow", { font: "block" });
grid = applyPadding(grid, 1);
const { grid: shadowed, shadowMask } = applyShadow(grid, 1, 1);

const lines = renderTerminal(shadowed, {
  colorMode: { type: "solid", color: [255, 100, 80] },
  shadowMask,
  shadowColor: [80, 80, 80],
});
console.log(lines.join("\n"));

Outline

import { composeText, renderTerminal, applyPadding, computeOutline } from "termfont";

let grid = composeText("Outline", { font: "bold" });
grid = applyPadding(grid, 1);
const outlineMask = computeOutline(grid);

const lines = renderTerminal(grid, {
  colorMode: { type: "solid", color: [0, 220, 220] },
  outlineMask,
});
console.log(lines.join("\n"));

Per-word colors

import { composeText, renderTerminal, applyPadding, getWordBoundaries, parseColor } from "termfont";

const text = "open|code";
const fontName = "block";
const grid = composeText(text.replace(/\|/g, ""), { font: fontName });
const padded = applyPadding(grid, 1);
const boundaries = getWordBoundaries(text, { font: fontName });

const lines = renderTerminal(padded, {
  colorMode: {
    type: "segments",
    segments: [
      { endX: boundaries[0] + 1, mode: { type: "solid", color: parseColor("cyan") } },
      { endX: Infinity, mode: { type: "solid", color: parseColor("gray") } },
    ],
  },
});
console.log(lines.join("\n"));

Compact mode

const lines = renderTerminal(padded, {
  colorMode: { type: "solid", color: [255, 255, 255] },
  compact: true, // half-block rendering, half the height
});

Color modes

// Solid
{ type: "solid", color: [255, 0, 0] }

// Gradient (2 or 3 stops)
{ type: "gradient", from: [255, 0, 0], to: [255, 255, 0], direction: "horizontal" }
{ type: "gradient", from: [255, 0, 0], via: [255, 255, 0], to: [0, 255, 0], direction: "horizontal" }

// Rainbow
{ type: "rainbow" }

// Per-segment
{ type: "segments", segments: [
  { endX: 20, mode: { type: "solid", color: [0, 220, 220] } },
  { endX: Infinity, mode: { type: "solid", color: [128, 128, 128] } },
]}

Named colors

white black red green blue yellow cyan magenta orange pink purple lime teal navy gold gray coral violet silver darkgray lightgray

License

MIT