@visulima/colorize

Visulima Colorize

Terminal and Console string styling done right, powered by @visulima/is-ansi-color-supported.

Colorize stands as a sleek, lightning-fast alternative to Chalk, boasting a plethora of additional, valuable features.
Elevate your terminal experience by effortlessly adding vibrant colors to your output with its clean and straightforward syntax.
For instance, you can use green to make green`Hello World!` pop, red`Error!` to signify Errors, or black.bgYellow`Warning!` to highlight warnings.

---

^{Daniel Bannert's open source work is supported by the community on GitHub Sponsors}

---

Why Colorize?

• Supports both ESM and CommonJS
• Standard API like chalk
• Default import
  • import colorize from '@visulima/colorize' or const colorize = require('@visulima/colorize')
• Named import
  • import { red } from '@visulima/colorize' or const { red } = require('@visulima/colorize')
• Chained syntax red.bold.underline('text')
• Template literals red`text`
• Nested template strings red`R ${green`G`} R`
• ANSI 256 colors and Truecolor (RGB, HEX) rgb(224, 17, 95)`Ruby`, hex('#96C')`Amethyst`
• ANSI codes as open and close property for each style `Hello ${red.open}World${red.close}!`
• Strip ANSI codes method colorize.strip()
• Correct style break at the end of line when used \n in string
• Supports the environment variables NO_COLOR FORCE_COLOR and flags --no-color --color
• Supports Deno, Next.JS runtimes and Browser
• Expressive API
• Doesn't extend String.prototype
• Up to x3 faster than chalk, see benchmarks
• Auto detects color support
• TypeScript support out of the box
• Clean and focused

Install

npm install @visulima/colorize

yarn add @visulima/colorize

pnpm add @visulima/colorize

Demo

Usage

// ESM default import
import colorize from "@visulima/colorize";
// ESM named import
import { red, green, blue } from "@visulima/colorize";

or

// CommonJS default import
const colorize = require("@visulima/colorize");
// CommonJS named import
const { red, green, blue } = require("@visulima/colorize");

Some examples:

console.log(colorize.green("Success!"));
console.log(green("Success!"));

// template string
console.log(blue`Info!`);

// chained syntax
console.log(green.bold`Success!`);

// nested syntax
console.log(red`The ${blue.underline`file.js`} not found!`);

API

Colors and styles have standard names used by many popular libraries, such as chalk, colorette, kleur.

Foreground colors	Background colors	Styles
black	bgBlack	dim
red	bgRed	bold
green	bgGreen	italic
yellow	bgYellow	underline
blue	bgBlue	strikethrough (alias strike)
magenta	bgMagenta	doubleUnderline (not included, because not widely supported)
cyan	bgCyan	overline (not included, because not widely supported)
white	bgWhite	frame (not included, because not widely supported)
gray (alias grey)	bgGray (alias bgGrey)	encircle (not included, because not widely supported)
blackBright	bgBlackBright	inverse
redBright	bgRedBright	visible
greenBright	bgGreenBright	hidden
yellowBright	bgYellowBright	reset
blueBright	bgBlueBright
magentaBright	bgMagentaBright
cyanBright	bgCyanBright
whiteBright	bgWhiteBright

Named import

The @visulima/colorize supports both the default import and named import.

// default import
import colorize from "@visulima/colorize";

colorize.red.bold("text");

You can import named colors, styles and functions. All imported colors and styles are chainable.

// named import
import { red, hex, italic } from "@visulima/colorize";

red.bold("text");

Default import and named import can be combined.

// default and named import
import colorize, { red } from "@visulima/colorize";

const redText = red("text"); // colorized ANSI string
const text = colorize.strip(redText); // pure string without ANSI codes

Template literals

The @visulima/colorize supports both the function syntax red('error') and template literals red`error`.

The template literals allow you to make a complex template more readable and shorter.
The function syntax can be used to colorize a variable.

import { red, blue } from "@visulima/colorize";

let message = "error";

red(message);
blue`text`;
blue`text ${message} text`;

Chained syntax

All colors, styles and functions are chainable. Each color or style can be combined in any order.

import { blue, bold, italic, hex } from "@visulima/colorize";

blue.bold`text`;

hex("#FF75D1").bgCyan.bold`text`;

bold.bgHex("#FF75D1").cyan`text`;

italic.yellow.bgMagentaBright`text`;

Nested syntax

You can nest functions and template strings within each other. None of the other libraries (chalk, kleur, colorette, colors.js etc.) support nested template strings.

Nested template strings:

import { red, green } from "@visulima/colorize";

red`red ${green`green`} red`;

Deep nested chained styles:

import { red, green, cyan, magenta, yellow, italic, underline } from "@visulima/colorize";

console.log(red(`red ${italic(`red italic ${underline(`red italic underline`)}`)} red`));

// deep nested chained styles
console.log(green(`green ${yellow(`yellow ${magenta(`magenta ${cyan(`cyan ${red.italic.underline`red italic underline`} cyan`)} magenta`)} yellow`)} green`));

Output:

Multiline nested template strings:

import { red, green, hex, visible, inverse } from "@visulima/colorize";

// defined a truecolor as the constant
const orange = hex("#FFAB40");

// normal colors
console.log(visible`
CPU: ${red`${cpu.totalPercent}%`}
RAM: ${green`${(ram.used / ram.total) * 100}%`}
DISK: ${orange`${(disk.used / disk.total) * 100}%`}
`);

// inversed colors
console.log(inverse`
CPU: ${red`${cpu.totalPercent}%`}
RAM: ${green`${(ram.used / ram.total) * 100}%`}
DISK: ${orange`${(disk.used / disk.total) * 100}%`}
`);

Output:

ANSI 256 colors

The pre-defined set of 256 colors.

Code range	Description
0 - 7	standard colors
8 - 15	bright colors
16 - 231	6 × 6 × 6 cube (216 colors)
232 - 255	grayscale from black to white in 24 steps

Foreground function: ansi256(code) has short alias fg(code)
Background function: bgAnsi256(code) has short alias bg(code)

The ansi256() and bgAnsi256() methods are implemented for compatibility with the chalk API.

See ANSI color codes.

import { bold, ansi256, fg, bgAnsi256, bg } from "@visulima/colorize";

// foreground color
ansi256(96)`Bright Cyan`;
fg(96)`Bright Cyan`;

// background color
bgAnsi256(105)`Bright Magenta`;
bg(105)`Bright Magenta`;

// function is chainable
ansi256(96).bold`bold Bright Cyan`;

// function is available in each style
bold.ansi256(96).underline`bold underline Bright Cyan`;

// you can combine the functions and styles in any order
bgAnsi256(105).ansi256(96)`cyan text on magenta background`;
bg(105).fg(96)`cyan text on magenta background`;

Truecolor (16 million colors)

You can use the hex or rgb format.

Foreground function: hex() rgb()
Background function: bgHex() bgRgb()

import { bold, hex, rgb, bgHex, bgRgb } from "@visulima/colorize";

// foreground color
hex("#E0115F").bold`bold Ruby`;
hex("#96C")`Amethyst`;
rgb(224, 17, 95).italic`italic Ruby`;

// background color
bgHex("#E0115F")`Ruby`;
bgHex("#96C")`Amethyst`;
bgRgb(224, 17, 95)`Ruby`;

// you can combine the functions and styles in any order
bold.hex("#E0115F").bgHex("#96C")`ruby bold text on amethyst background`;

Use ANSI codes

You can use the ANSI escape codes with open and close properties for each style.

import { green, bold } from "@visulima/colorize";

// each style has `open` and `close` properties
console.log(`Hello ${green.open}ANSI${green.close} World!`);

// you can define own style which will have the `open` and `close` properties
const myStyle = bold.italic.black.bgHex("#E0115F");

console.log(`Hello ${myStyle.open}ANSI${myStyle.close} World!`);

Strip ANSI codes

The Colorize class contains the method strip() to remove all ANSI codes from string.

import colorize from "@visulima/colorize";
// or named import
import { strip } from "@visulima/colorize";

const ansiString = colorize.blue`Hello World!`;
const string = colorize.strip(ansiString);

The variable string will contain the pure string without ANSI codes.

New lines

Supports correct style break at the end of line.

import { bgGreen } from "@visulima/colorize";

console.log(bgGreen`\nColorize\nNew Line\nNext New Line\n`);

Environment variables and CLI arguments

Please check @visulima/is-ansi-color-supported for more information.

Browser support

Since Chrome 69, ANSI escape codes are natively supported in the developer console.

Windows

If you're on Windows, do yourself a favor and use Windows Terminal instead of cmd.exe.

Comparison of most popular libraries

Library **__** - name - named import	Code size	Naming colors	ANSI 256 colors	True- color	Chained syntax	Nested template strings	New Line	Supports CLI params
@visulima/colorize ✅ named import		standard 16 colors	✅	✅	✅	✅	✅	NO_COLOR FORCE_COLOR --no-color --color
ansi-colors ❌ named import		standard 16 colors	❌	❌	✅	❌	✅	only FORCE_COLOR
ansis ✅ named import		standard 16 colors	✅	✅	✅	✅	✅	NO_COLOR FORCE_COLOR --no-color --color
chalk ❌ named import		standard 16 colors	✅	✅	✅	❌	✅	NO_COLOR FORCE_COLOR --no-color --color
cli-color ❌ named import		standard 16 colors	✅	❌	✅	❌	❌	only NO_COLOR
colorette ✅ named import		standard 16 colors	❌	❌	❌	❌	❌	NO_COLOR FORCE_COLOR --no-color --color
colors-cli ❌ named import		non-standard 16 colors	✅	❌	✅	❌	✅	only --no-color --color
colors.js ❌ named import		non-standard 16 colors	❌	❌	✅	❌	✅	only FORCE_COLOR --no-color --color
kleur ✅ named import		standard 8 colors	❌	❌	✅	❌	❌	only NO_COLOR FORCE_COLOR
picocolors ❌ named import		standard 8 colors	❌	❌	❌	❌	❌	NO_COLOR FORCE_COLOR --no-color --color

Note

Code size
The size of distributed code that will be loaded via require or import into your app. It's not a package size.

Named import
import { red, green, blue } from 'lib';
or
const { red, green, blue } = require('lib');

Naming colors

• standard: colors have standard names, e.g.: red, redBright, bgRed, bgRedBright
• non-standard: colors have lib-specific names, e.g.: brightRed, bgBrightRed, red_b, red_btt

ANSI 256 colors

The method names:

• @visulima/colorize: ansi256(n) bgAnsi256(n) fg(n) bg(n)
• ansis: ansi256(n) bgAnsi256(n) fg(n) bg(n)
• chalk: ansi256(n) bgAnsi256(n)
• cli-color: xterm(n)
• colors-cli: x<n>

Truecolor

The method names:

• @visulima/colorize: hex() rgb()
• ansis: hex() rgb()
• chalk: hex() rgb()

Chained syntax
lib.red.bold('text')

Nested template strings
lib.red`text ${lib.cyan`nested`} text`

New line
Correct break styles at end-of-line.

lib.bgGreen(`First Line
Next Line`);

Benchmark

See benchmark

Reference

• The opaque named colors
• ANSI escape code

The ANSI Escape sequences control code screen.

echo -e "\033[31;41;4m something here 33[0m"

\033 As the escape character, inform the terminal to switch to the escape mode. [ The beginning of the CSI. m Make the action to be performed. ; ASCII code separator.

Supported Node.js Versions

Libraries in this ecosystem make the best effort to track Node.js’ release schedule. Here’s a post on why we think this is important.

Contributing

If you would like to help take a look at the list of issues and check our Contributing guild.

Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Credits

• WebDiscus
• Daniel Bannert
• All Contributors

About

Related Projects

• ansis - The Node.js library for formatting text in terminal with ANSI colors & styles
• ansi-colors - Easily add ANSI colors to your text and symbols in the terminal.
• chalk - Terminal string styling done right
• cli-color - Colors and formatting for the console
• colorette - Easily set your terminal text color & styles
• colors-cli - Terminal string styling done right.
• colors.js - get colors in your node.js console
• kleur - The fastest Node.js library for formatting terminal text with ANSI colors~!
• picocolors - Tiny yet powerful colors for terminal

License

The visulima colorize is open-sourced software licensed under the MIT