@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
TypeScript support out of the box
Supports Deno, Next.JS runtimes and Browser (not only chrome) (currently multi nesting is not supported)
Standard API compatible with Chalk, switch from Chalk to Colorize without changing your code

- import chalk from 'chalk';
+ import chalk, { red } from '@visulima/colorize';

chalk.red.bold('Error!'); // <- Chalk like syntax works fine with Colorize
red.bold('Error!');       // <- the same result with Colorize
red.bold`Error!`;         // <- the same result with Colorize

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`
String styling with tagged template literals, see template-literals
Nested template strings red`R ${green`G`} R`
Base ANSI styles dim bold italic underline ~~strikethrough~~
Base ANSI 16 colors red`Error!` redBright`Error!` bgRed`Error!` bgRedBright`Error!`
ANSI 256 colors and TrueColor (RGB, HEX) rgb(224, 17, 95)`Ruby`, hex('#96C')`Amethyst`
TrueColor (RGB, HEX) rgb(224, 17, 95)`Ruby`, hex('#96C')`Amethyst`
Fallback to supported color space: TrueColor → 256 colors → 16 colors → no colors
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
Expressive API
Doesn't extend String.prototype
Up to x3 faster than chalk, see benchmarks
Auto detects color support
Clean and focused
String Gradient´s

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";

// 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!`);

Browser

Note: It has the same API as in Node.js.

The return value of the browser version is an array of strings, not a string, because the browser console use the %c syntax for styling. This is why you need the spread operator ... to log the colorized string.

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

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!`);

Workaround/Hack to not use the spread operator ....

Warning: But you will lose the correct file path and line number in the console.

let consoleOverwritten = false;

// Heck the window.console object to add colorized logging
if (typeof navigator !== "undefined" && typeof window !== "undefined" && !consoleOverwritten) {
    ["error", "group", "groupCollapsed", "info", "log", "trace", "warn"].forEach((o) => {
        const originalMethod = (window.console as any)[o as keyof Console];

        (window.console as any)[o as keyof Console] = (...args: any[]) => {
            if (Array.isArray(args[0]) && args[0].length >= 2 && args[0][0].includes("%c")) {
                originalMethod(...args[0]);
            } else {
                originalMethod(...args);
            }
        };
    });

    consoleOverwritten = true;
}

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`;

Tagged Template Literals

The @visulima/colorize supports the tagged template literals.

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

console.log(template`
CPU: {red ${cpu.totalPercent}%}
RAM: {green ${(ram.used / ram.total) * 100}%}
DISK: {rgb(255,131,0) ${(disk.used / disk.total) * 100}%}
`);

const miles = 18;
const calculateFeet = (miles) => miles * 5280;

console.log(template`
    There are {bold 5280 feet} in a mile.
    In {bold ${miles} miles}, there are {green.bold ${calculateFeet(miles)} feet}.
`);

console.log(template`
    There are also {#FF0000 shorthand hex styles} for
    both the {#ABCDEF foreground}, {#:123456 background},
    or {#ABCDEF:123456 both}.
`);

API

Blocks are delimited by an opening curly brace ({), a style, some content, and a closing curly brace (}).

Template styles are chained exactly like normal Colorize styles. The following two statements are equivalent:

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

console.log(colorize.bold.rgb(10, 100, 200)("Hello!"));
console.log(template`{bold.rgb(10,100,200) Hello!}`);

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:

Base ANSI 16 colors and styles

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`

ANSI 256 colors

The pre-defined set of 256 colors.

Browser

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.

Fallback

If a terminal supports only 16 colors then ANSI 256 colors will be interpolated into base 16 colors.

Usage Example

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

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

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

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

// function is avaliable 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`;

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`;

Fallback

If a terminal does not support ANSI colors, the library will automatically fall back to the next supported color space.

TrueColor —> 256 colors —> 16 colors —> no colors (black & white)

If you use the hex(), rgb() or ansis256() functions in a terminal not supported TrueColor or 256 colors, then colors will be interpolated.

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 (every chrome based browser), ANSI escape codes are natively supported in the developer console.

For other browsers (like firefox) we use the console style syntax command %c.

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	Naming colors	ANSI 256 colors	True- color	Chained syntax	Nested template strings	New Line	Supports CLI params ENV vars	Fallbacks
`@visulima/colorize` `✅ named import`	standard `16` colors	✅	✅	✅	✅	✅	`NO_COLOR` `FORCE_COLOR` `--no-color` `--color`	256 color 16 colors no color
`ansi-colors` `❌ named import`	standard `16` colors	❌	❌	✅	❌	✅	only `FORCE_COLOR`	❌
`ansis` `✅ named import`	standard `16` colors	✅	✅	✅	✅	✅	`NO_COLOR` `FORCE_COLOR` `--no-color` `--color`	256 color 16 colors no color
`chalk` `❌ named import`	standard `16` colors	✅	✅	✅	❌	✅	`NO_COLOR` `FORCE_COLOR` `--no-color` `--color`	256 color 16 colors no color
`cli-color` `❌ named import`	standard `16` colors	✅	❌	✅	❌	❌	only `NO_COLOR`	16 colors no color
`colorette` `✅ named import`	standard `16` colors	❌	❌	❌	❌	❌	`NO_COLOR` `FORCE_COLOR` `--no-color` `--color`	no color
`colors-cli` `❌ named import`	non-standard `16` colors	✅	❌	✅	❌	✅	only `--no-color` `--color`	no color
`colors.js` `❌ named import`	non-standard `16` colors	❌	❌	✅	❌	✅	only `FORCE_COLOR` `--no-color` `--color`	no color
`kleur` `✅ named import`	standard `8` colors	❌	❌	✅	❌	❌	only `NO_COLOR` `FORCE_COLOR`	no color
`picocolors` `❌ named import`	standard `8` colors	❌	❌	❌	❌	❌	`NO_COLOR` `FORCE_COLOR` `--no-color` `--color`	no 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`);

Gradient

The @visulima/colorize/gradient supports the string gradient´s, single and multi line.

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

console.log(gradient("red", "green", "blue")("Hello World!"));

Multi line gradient

In some cases, you may want to apply the same horizontal gradient on each line of a long text (or a piece of ASCII art).

You can use the multilineGradient method of a gradient to ensure that the colors are vertically aligned.

import { multilineGradient, gradient } from "@visulima/colorize/gradient";

console.log(multilineGradient(["orange", "yellow"])(["     __", "   <(o )___", "    ( ._> /", "     `---'"].join("\n")));
console.log(gradient(["blue", "cyan", "blue"])("----------------"));

Benchmark

See benchmark

Reference

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

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

Template:

chalk-template - Terminal string styling with tagged template literals

Gradient:

tinygradient - Easily generate color gradients with an unlimited number of color stops and steps.
gradient-string - Beautiful color gradients in terminal output

License

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

@visulima/colorize