A fast, lightweight, and high-performance terminal string styling library.

Features

• Supports a wide range of color formats, including 8-bit, 256-bit, RGB, HSL, and HEX.
• Modular design enables the creation of color palettes and reusable styles.
• Does not extend String.prototype.
• Minimize's string pollution.
• Ability to nest styles.
• Highly performant.
• No dependencies.
• Lightweight.
• Expressive.
• Maintained.
• Robust.

Support

| Platform / Terminal | Type | Supported | Support Since | | ------------------------- | -------- | --------- | ---------------------------- | | Windows Console (CMD) | Terminal | ❌ | Not supported | | Terminal.app (macOS) | Terminal | ✅ | Since early versions | | PowerShell 6+ | Terminal | ✅ | Since release | | PowerShell 5.1+ | Terminal | ✅ | Windows 10 v1511 (2016) | | Windows Terminal | Terminal | ✅ | Since initial release (2019) | | GNOME Terminal | Terminal | ✅ | Since early versions | | Linux Console | Terminal | ✅ | Since early versions | | iTerm2 (macOS) | Terminal | ✅ | Since early versions | | Konsole (KDE) | Terminal | ✅ | Since early versions | | Chrome DevTools | Browser | ✅ | Since version 69 (2018) | | Cygwin Terminal | Terminal | ✅ | With ANSI support enabled | | ConEmu | Terminal | ✅ | With ANSI support enabled | | xterm | Terminal | ✅ | Since early versions |

Installation

Installation is done using the npm install command:

npm install styled-terminal

Declaration

Using CommonJS (ES5)

const { style } = require("styled-terminal");

Using ES Modules (ES6+)

import { style } from "styled-terminal";

Usage

1. Hello World Example

import { style, Color } from "styled-terminal";

// Prints "Hello World!" with a random foreground color.
console.log(style.fg(Color.random).apply("Hello World!"));

// Or use the shorter syntax:
console.log(style.fg(Color.random)("Hello World!"));

2. Styled String Concatenation

import { style, Color } from "styled-terminal";

// Standard concatenation using the + operator:
console.log(
  style.fg(Color.green)("• ") + style.fg(Color.blue).bold.underline("Headline")
);

// Concatenation using multiple arguments:
console.log(
  style.fg(Color.green)("•", " "),
  style.fg(Color.blue).bold.underline("Headline")
);

// Nested concatenation:
console.log(
  style.fg(Color.green)(
    "•",
    " ",
    style.fg(Color.blue).bold.underline("Headline")
  )
);

3. Define Custom Styles and Colors

import { style, Color } from "styled-terminal";

// Custom colors
const deepSkyBlue = Color.rgb(0, 191, 255);
const mediumOrchid = Color.hex("#BA55D3");
const hotPink = Color.hsl(330, 100, 17);
const darkOrange = Color.hex("#FF8C00");
const redMagenta = Color.hex("#ff0055");
const crimsonRed = Color.hex("#DC143C");
const limeGreen = Color.hex("#32CD32");
const slateBlue = Color.hex("#6A5ACD");
const gold = Color.hex("#FFD700");

// Custom styles
const headline = style.fg(deepSkyBlue).underline.bold;
const description = style.italic;
const highlight = style.fg(gold);

// Custom style function
const codeComment = (comment) =>
  `${style.fg(Color.green).light("// ", comment)}`;

console.log(headline("Headline"), highlight.bold.italic("1"));
console.log(description("A short description..."));

console.log(codeComment("A simple comment."));

API

<class Color>

Represents a Color.

Color.black

Gets the default black color.

Color.brightBlack

Gets the default bright black color.

Color.red

Gets the default red color.

Color.brightRed

Gets the default bright red color.

Color.green

Gets the default green color.

Color.brightGreen

Gets the default bright green color.

Color.yellow

Gets the default yellow color.

Color.brightYellow

Gets the default bright yellow color.

Color.blue

Gets the default blue color.

Color.brightBlue

Gets the default bright blue color.

Color.magenta

Gets the default magenta color.

Color.brightMagenta

Gets the default bright magenta color.

Color.cyan

Gets the default cyan color.

Color.brightCyan

Gets the default bright cyan color.

Color.white

Gets the default white color.

Color.brightWhite

Gets the default bright white color.

Color.random

Gets a random color.

Color.randomBright

Gets a random bright color.

Color.randomDim

Gets a random dim color.

Color.table256(index)

Creates a Color object by choosing an index from the 256-color lookup table.

• index {number} A number between 0-255 which represent a cell index.
• Select a color from the 256 Color's table.

True Colors

• Pick a true color in HEX, RGB or HSL format.

Color.rgb(red, green, blue)

Creates a Color object from RGB (Red, Green, Blue) values.

• red {number} The red component of the color, typically a value between 0 and 255.
• green {number} The green component of the color, typically a value between 0 and 255.
• blue {number} The blue component of the color, typically a value between 0 and 255.

Color.hsl(hue, saturation, lightness)

Creates a Color object from HSL (Hue, Saturation, Lightness) values.

• hue {number} The hue of the color, typically a value between 0 and 360 degrees.
• saturation {number} The saturation of the color, typically a percentage value between 0 and 100.
• lightness {number} The lightness of the color, typically a percentage value between 0 and 100.

Color.hex(hexCode)

Creates a Color instance from a hexadecimal color code.

• hexCode {string} A string representing the color in hexadecimal format (e.g., #FF5733).

<class Style>

Represents a style used for terminal text.

style.<modifier>...<modifier>(string, ...string[])

Example: style.underline.bold.fg(Color.random)("Hello World!")

Modifiers

reset

Resets all the current style modifiers.

hidden

Hides the text.

reveal

Force revealing a hidden text.

autoVisibility

Sets visibility to be auto.

invert

Mode that swaps foreground and background colors.

noInvert

Force disable the mode that swaps foreground and background colors.

autoInvert

Sets the mode that swaps foreground and background colors to auto.

bold

Sets the font weight of the text to bold.

light

Sets the font weight of the text to light.

normal

Sets the font weight of the text to normal.

autoFontWeight

Sets the font weight of the text to auto.

italic

Applies italic styling to the text.

noItalic

Force remove italic styling from the text.

autoItalic

Sets italic styling of the text to auto.

underline

Applies underline styling to the text.

doubleUnderline

Applies double underline styling to the text.

noUnderline

Force remove any underline styling from the text.

autoUnderline

Sets any underline styling from the text to auto.

strikethrough

Applies strikethrough styling to the text.

noStrikethrough

Force remove any strikethrough styling from the text.

autoStrikethrough

Sets any strikethrough styling from the text to auto.

resetFg

Force resetting the foreground color to the terminal default value.

autoFg

Setting the foreground color to auto.

resetBg

Force resetting the background color to the terminal default value.

autoBg

Setting the background color to be auto.

fg(color)

Sets the foreground color of the text.

• color {Color} A Color instance representing a color.

bg(color)

Sets the background color of the text.

• color {Color} A Color instance representing a color.

Methods

start()

Begins a style chain for terminal output. Applies the specified styles until explicitly ended.

Example

import { style } from "styled-terminal";
import * as readline from "readline";

// Create an interface for reading input
const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
});

// Creating an hidden text style.
const hiddenText = style.hidden;

// Hides the input...
rl.question(`Enter password: ${hiddenText.start()}`, (password) => {
  console.log(hiddenText.end());
  /// Rest of the code...
  rl.close();
});

end()

Ends the current style chain or resets terminal styles.

apply(str, ...args)

Applies a style to a string by concatenating it with additional strings.

• str {string} The base string to apply the style to.
• args {string[]} Additional strings to concatenate.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Author

Liav Barsheshet, LBDevelopments

License

MIT